/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.
Requiere autenticación (cabecera Bearer o X-API-Key)
Ejecutar en el área de pruebas →Parámetros
keywordstringopcionalPartial 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. · ejemplo:버거킹region_codestringopcionalRegion 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_categorystringopcionalOne 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. · ejemplo:restaurantmin_confidencenumberopcionalMinimum confidence, 0 to 1, compared with each venue's confidence field. Venues below it are left out, and this filter is never dropped. · ejemplo:0.6sortstringopcionaldiscovery 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. · ejemplo:discoveryrecommended_forstringopcionalOccasion 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. · ejemplo:group_diningatmospherestringopcionalAtmosphere 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). · ejemplo:quietparkingbooleanopcionalOnly venues with confirmed parking. If nothing matches, this filter is dropped and listed in meta.relaxedFilters. Use parking_type for the kind of parking. · ejemplo:trueparking_typestringopcionalKind of parking: onsite, valet, partner (a partner lot), nearby, none. Korean words work too (발렛 → valet). · ejemplo:onsitereservablebooleanopcionalOnly 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. · ejemplo:truepayment_methodsstringopcionalPayment 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. · ejemplo:alipayservesstringopcionalWhat 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. · ejemplo:alcoholdietarystringopcionalDietary 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. · ejemplo:vegan_optionsforeign_languagesstringopcionalLanguages 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). · ejemplo:ensubtypestringopcionalVenue 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. · ejemplo:korean_bbqbbq_meatstringopcionalMeat 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). · ejemplo:porkviewstringopcionalView 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. · ejemplo:oceanmax_dish_priceintegeropcionalOnly 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. · ejemplo:10000foreigner_friendlybooleanopcionalVenues 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. · ejemplo:truelegacybooleanopcionalOfficially 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. · ejemplo:truelocal_foodstringopcionalVenues 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. · ejemplo:부산excludestringopcionalLeaves 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. · ejemplo:돼지국밥muslim_friendlybooleanopcionalVenues 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. · ejemplo:truefeatured_bystringopcionalOnly 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. · ejemplo:성시경associated_withstringopcionalOnly 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. · ejemplo:BTSpet_friendlybooleanopcionalExample 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. · ejemplo:trueopen_atstringopcionalOnly 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. · ejemplo:2026-08-26T19:00include_unknown_hoursbooleanopcionalOnly 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. · ejemplo:truereservation_channelstringopcionalHow 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. · ejemplo:yumifieldsstringopcionalFields 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. · ejemplo:core,reviewCount,accessHintspageintegeropcionalPage (default 1) · ejemplo:1page_sizeintegeropcionalResults 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. · ejemplo:20
Ejemplo de respuesta
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
}
}