/api/v1/placesSearch places
Search venues by keyword, region, business type, and filters. Results are sorted by discovery, which weighs query match, freshness, cross-source verification, and data completeness, and come back in pages. Choose the response fields with fields; the call costs the highest field tier requested. If a search finds nothing, it widens step by step: it drops convenience filters, includes venues with unknown hours, reads the keyword another way (translation, sub-type, a fuzzy name match), and may look in the beauty or fitness group. Each step is reported in meta (relaxedFilters, interpretedFilters, keywordTranslated, keywordFuzzy, openAt). Params it can't use are ignored and listed in meta.ignoredFilters. Results never mix food with beauty or fitness, and permanently closed venues are never returned.
Authentification requise (en-tête Bearer ou X-API-Key)
Exécuter dans le playground →Paramètres
keywordstringfacultatifPartial match on venue name, address, or menu item. English or romanized names (Starbucks) and dish names in other languages (bibimbap, ビビンバ, 拌饭) work as-is; if a dish name was translated to Korean, meta.keywordTranslated says so. Each result carries matchReason, plus matchedMenu when a menu item matched. · exemple:버거킹region_codestringfacultatifRegion code: a 10-digit legal-dong (beopjeong-dong) code from GET /api/v1/regions, or a prefix for a wider area (5 digits for a si/gun/gu such as 11680 Gangnam-gu, 2 digits for a province such as 11 Seoul). Comma-separate up to 8 codes to search several areas.business_categorystringfacultatifOne business type. Food: restaurant, cafe, bar. Beauty: salon, nail, esthetic, lash, waxing, or beauty for all five. Fitness: gym, pilates, yoga, or fitness for all three (Yumi Partner venues only). A search covers one of these groups and never mixes them. Without business_category the search covers food. A keyword that names a beauty or fitness type (네일샵) is searched as that type, and a keyword that finds nothing in food is tried in beauty and then fitness; meta.interpretedFilters says so. Values: GET /api/v1/meta, filters.businessCategory. · exemple:restaurantmin_confidencenumberfacultatifMinimum confidence, 0 to 1, compared with each venue's confidence field. Venues below it are left out, and this filter is never dropped. · exemple:0.6sortstringfacultatifdiscovery is the default and the only value: a recommendation sort. distance needs coordinates, so use /places/nearby for it; sort=distance here is ignored and listed in meta.ignoredFilters. meta.sort reports the sort actually used and can fall back to reviews on very broad searches. · exemple:discoveryrecommended_forstringfacultatifOccasion filter. Comma-separated; a venue must match every value. Values include solo_dining, date, group_dining, family, business_meeting, formal_gathering, and late_night. Korean phrases work too (회식 → group_dining, 혼밥 → solo_dining, 상견례 → formal_gathering). Full list and aliases: GET /api/v1/meta. · exemple:group_diningatmospherestringfacultatifAtmosphere preference, comma-separated: quiet, lively, view, cozy, trendy, spacious, traditional, clean, work_study, rainy_mood. Matching venues are ranked higher; no venue is removed. Applied values are echoed in meta.softenedFilters. Korean words work too (조용한 → quiet). · exemple:quietparkingbooleanfacultatifOnly venues with confirmed parking. If nothing matches, this filter is dropped and listed in meta.relaxedFilters. Use parking_type for the kind of parking. · exemple:trueparking_typestringfacultatifKind of parking: onsite, valet, partner (a partner lot), nearby, none. Korean words work too (발렛 → valet). · exemple:onsitereservablebooleanfacultatifOnly venues that take reservations: either confirmed in source data, or able to take a Yumi request (Yumi Partners and most other venues with a phone number). To filter by how a booking is made, use reservation_channel. · exemple:truepayment_methodsstringfacultatifPayment methods, comma-separated; a venue must accept every value: cash, card, naver_pay, kakao_pay, toss_pay, zero_pay, local_gift, gov_support, alipay, wechat_pay, unionpay, apple_pay, samsung_pay. apple_pay, samsung_pay, and unionpay come from owners. Apple Pay acceptance doesn't guarantee that foreign cards work, so treat it as a hint. Values for foreign-issued cards are ignored and reported in meta.ignoredFilters. · exemple:alipayservesstringfacultatifWhat the venue serves, comma-separated; a venue must match every value: coffee, alcohol, dessert, vegetarian, vegan. Meal times sent here by mistake (serves=lunch) are moved to open_at. · exemple:alcoholdietarystringfacultatifDietary needs, comma-separated: vegan_options, vegetarian_options, fully_vegan, mixed_group_suitable, vegetarian_mixed_group_suitable, gluten_free. Plain words in Korean or English work too (vegan, plant-based → vegan_options; gf → gluten_free; halal is moved to muslim_friendly). For a vegan eating with non-vegans, use mixed_group_suitable: it needs a confirmed vegan meal, so cafes with only vegan drinks are left out. gluten_free uses owner-confirmed data only. If the search area has fewer than 5 confirmed gluten-free venues, you get 0 results and meta.dietaryCoverage says coverage is still too thin. · exemple:vegan_optionsforeign_languagesstringfacultatifLanguages the staff can serve guests in (ISO 639-1), comma-separated; a venue must match every value: en, zh, ja, es, de, fr. Owner-confirmed. Korean words work too (영어 → en, 일본어 → ja). · exemple:ensubtypestringfacultatifVenue sub-type, 40 values in total; commas mean OR. Food: korean, korean_bbq, gukbap_soup, noodles, chinese, japanese, sushi_sashimi, italian, seafood, and more. Cafe: coffee, dessert, bakery, brunch, traditional_tea, and more. Bar: cocktail_bar, wine_bar, izakaya, pocha, hof_beer, and more. Korean words work too (삼겹살 → korean_bbq, 국밥 → gukbap_soup). When the user asks for a kind of venue, use subtype before business_category. Full list: GET /api/v1/meta. · exemple:korean_bbqbbq_meatstringfacultatifMeat served at a Korean BBQ venue, comma = OR: pork, beef, duck, lamb. Use it with subtype=korean_bbq: subtype picks the venue type and bbq_meat narrows the meat. A venue that serves both pork and beef matches either value. Korean words work too (삼겹살 → pork, 한우 → beef). · exemple:porkviewstringfacultatifView from the venue, comma = OR: ocean, sunset, river, mountain, night, city, garden. A venue with both an ocean and a sunset view matches either. Korean words work too (바다뷰 → ocean, 한강뷰 → river, 야경 → night). Set only where there is evidence, so a missing value means unknown. If nothing matches, view stops filtering, ranks venues with a good view higher, and is listed in meta.relaxedFilters. · exemple:oceanmax_dish_priceintegerfacultatifOnly venues with at least one dish at or under this price, in KRW. 'Meals under 10,000 won' is max_dish_price=10000. The check uses the cheapest real dish, so rice, noodle add-ons, and other extras don't count. Venues with unknown prices are left out, and this filter is never dropped. For 'good value' without a price, use good_value=true. · exemple:10000foreigner_friendlybooleanfacultatifVenues a guest can manage without Korean: there is an English or other foreign-language menu, or the staff can serve guests in a foreign language. For the menu only, use english_menu=true; for a specific language, use foreign_languages. If nothing matches, this filter is dropped and listed in meta.relaxedFilters. · exemple:truelegacybooleanfacultatifOfficially designated long-running venues only: Centennial Stores (백년가게), Seoul Oraegage (서울 오래가게), and Seoul Future Heritage (서울미래유산). For old-school or heritage restaurants, use this instead of keyword=노포, which also matches unrelated names and addresses. · exemple:truelocal_foodstringfacultatifVenues that feature a local specialty of the region in their name or signature dish (in Busan: dwaeji-gukbap, milmyeon, and so on). Pass a region name (local_food=부산) or a sido code, or pass true together with region_code. Covers all 17 sido. An unrecognized value is ignored and reported in meta.ignoredFilters. · exemple:부산excludestringfacultatifLeaves out venues whose name or signature dish is that food ('anything but…'). Comma-separate several foods; each term needs at least 2 characters, up to 12 terms. Venues that only list it as a side dish stay in. · exemple:돼지국밥muslim_friendlybooleanfacultatifVenues known to welcome Muslim guests: halal wording in the name or menu, or confirmed by the owner. This is different from official halal certification. The response meta always includes a note telling the guest to confirm certification, a pork-free kitchen, and alcohol with the venue. · exemple:truefeatured_bystringfacultatifOnly venues introduced by an ambassador (influencer) who gave written consent. Partial match on name, handle, or channel name, at least 2 characters. If no one matches, you get 0 results and meta.featuredBy lists who is available. Alias: influencer. · exemple:성시경associated_withstringfacultatifOnly venues publicly reported in connection with a celebrity, group, or show ('where BTS ate', 'Goblin filming location'). If nothing matches, you get 0 results and meta.associatedWith lists the subjects available. · exemple:BTSpet_friendlybooleanfacultatifExample boolean presence filter. Attach the param to require =true (only confirmed places). All 54 boolean filters supported today: wifi, parking, outdoor_seating, group_friendly, kids_friendly, reservable, takeout, delivery, dine_in, catering, corkage_free, corkage_available, wheelchair_accessible, high_chair, no_kids_zone, smoking_area, restroom_gender_separated, power_outlets, stroller_storage, deposit_required, restroom_clean, waiting_expected, leftover_packing, repeat_customers, private_room, has_promotion, real_bar, english_menu, foreigner_friendly, good_value, rooftop, hanok, photo_spot, local_favorite, nursing_room, live_music, fireplace, floor_seating, counter_seating, inside_market, board_game, sports_bar, temple_food, natural_wine, craft_beer, omakase, unlimited_refill, charcoal_grill, domestic_ingredients, traditional_liquor, kids_play_area, fine_dining, michelin_star. Special filters (muslim_friendly, legacy, local_food, exclude, featured_by, associated_with) at /api/v1/meta. · exemple:trueopen_atstringfacultatifOnly venues open at that time (KST). A point in time: 2026-08-26T19:00, '2026-08-26 19:00', '19:00' (today), or now. A point means the venue still takes orders then, so venues past last order are left out. A window: lunch or 점심 (11:00-14:00), dinner or 저녁 (17:30-21:00), breakfast (07:00-10:00), brunch (10:00-13:00), late_night (22:00-01:00), a custom range such as '11:00-14:00', or a date plus a window such as '2026-08-29 lunch'. A window matches venues that take orders at some point in it. Relative days are limited to 오늘/today, 내일/tomorrow, and 모레; send other days as a date. The resolved range is echoed in meta.openAt.window. Regular hours, last order, break times, hours past midnight, and announced temporary closures (holidays and the like) are all checked. Unannounced closures and full tables can't be known. Venues with unconfirmed hours are left out and meta.openAt.unknownHoursExcluded is set; if that leaves 0 results, they are added back and meta.openAt.includedUnknownHours is set. A value that can't be read is ignored and reported in meta.ignoredFilters. · exemple:2026-08-26T19:00include_unknown_hoursbooleanfacultatifOnly used with open_at. true also returns venues whose hours are unconfirmed; whether those are open at that time is unknown. Venues on an announced temporary closure are still left out. · exemple:truereservation_channelstringfacultatifHow the venue can be booked, comma = OR. yumi: you can send a request with POST /api/v1/reservations. phone: the venue books by phone and can't take a Yumi request. Taking reservations doesn't mean a table is free at your time; you only find out by sending a request. On /places, yumi needs a narrower scope as well: a district- or dong-level region_code, keyword, subtype, bbq_meat, featured_by, or local_food. business_category alone doesn't count. Without one you get 400 partner_scope_required. If a yumi-only search finds nothing, it is widened to all venues and meta.reservationFallback says so. · exemple:yumifieldsstringfacultatifFields to return (Field Mask). Comma-separated tier names (core, contact_hours, quality, edge, media), all, or individual field names; you can mix them. The same value can also be sent in the X-Map3-Fieldmask header. Defaults to core, and core fields are always included. A call costs the highest tier you request, once per request: core 1, contact_hours 2, quality 2, edge 4, media 8 tokens. page_size does not change the cost. Unknown names are ignored and listed in meta.ignoredFields and the X-Map3-Ignored-Fields header. Owner photos (venue and menu image URLs) come in photos, which is the media tier, so fields=all costs 8; in lists, request photoCount (quality) to get just the count. recommendedFor can include occasion tags such as solo_dining, late_night, and late_night_eatery. · exemple:core,reviewCount,accessHintspageintegerfacultatifPage (default 1) · exemple:1page_sizeintegerfacultatifResults per page. Default 20, max 100. Billing is per request, so page_size does not change the cost. A live API key can page through a limited result window: 100 results on the free plan, more on a contract. Asking past it (page × page_size) returns 400 bulk_export_required; use Bulk Export for larger pulls. · exemple:20
Exemple de réponse
json
{
"success": true,
"data": [
{
"id": "11892345",
"name": "콩부자 홍제점",
"category": "restaurant",
"categoryLabel": "국밥",
"location": {
"lat": 37.5891,
"lng": 126.9436
},
"address": {
"road": "서울 서대문구 통일로 450",
"jibun": "서울 서대문구 홍제동 330"
},
"regionCode": "1141011100",
"confidence": 0.64,
"sourceCount": 2,
"possiblyClosed": false,
"lastSeenAt": "2026-06-18T03:00:00.000Z",
"placeUrl": "https://heyyumi.ai/places/11892345"
}
],
"meta": {
"total": 5,
"page": 1,
"pageSize": 20,
"totalPages": 1
}
}