GET
/api/v1/placesSearch places
Search refined places (the oneset) by keyword, region, category, and confidence. Default sort is discovery (query fit, recency, cross-source verification, and completeness together), paginated. Use fields to shape the response.
Auth required (Bearer / X-API-Key header preferred)
Run in playground →Parameters
keywordstringoptionalPartial match on name/address/menu item. English or romanized venue names (Starbucks) and foreign dish names (bibimbap, ビビンバ, 拌饭) work as-is; when a dish name is translated to Korean, meta.keywordTranslated says so. · example:버거킹region_codestringoptionalRegion (admin-dong) codebusiness_categorystringoptionalBusiness type (restaurant/cafe/bar, plus Yumi partner non-food types salon/gym/esthetic/nail). Non-food types return approved partners only and never mix into plain food searches. Values: GET /api/v1/meta → filters.businessCategory · example:restaurantmin_confidencenumberoptionalMinimum confidence (0-1) · example:0.6sortstringoptionaldiscovery (default, only value) — recommendation sort. distance is unavailable without coordinates. meta.sort reports the sort actually applied and may degrade to reviews on very broad searches. · example:discoveryrecommended_forstringoptionalNarrow by occasion (comma, all must match). Natural language resolves too. Values: solo_dining, date, group_dining, family, business_meeting, formal_gathering, late_night… Full list & aliases at /api/v1/meta. · example:group_diningatmospherestringoptionalAtmosphere (comma). quiet, lively, view, cozy, trendy, spacious, traditional, clean, work_study, rainy_mood. · example:quietparkingbooleanoptionalOnly places with confirmed parking. See parking_type for the kind. · example:trueparking_typestringoptionalParking type: onsite, valet, partner, nearby, none. Natural language (e.g. 발렛→valet) resolves. · example:onsitereservablebooleanoptionalOnly reservable places (crawl-confirmed plus Yumi Partner venues). · example:truepayment_methodsstringoptionalRequire payment methods (comma, all must match). cash, card, naver_pay, kakao_pay, toss_pay, alipay, wechat_pay, unionpay, apple_pay, samsung_pay… apple_pay/samsung_pay/unionpay are owner-confirmed. · example:alipayservesstringoptionalServes (comma). coffee, alcohol, dessert, vegetarian, vegan. · example:alcoholdietarystringoptionalDietary (comma). vegan_options, vegetarian_options, fully_vegan, mixed_group_suitable, vegetarian_mixed_group_suitable, gluten_free. Natural words (KR/EN) resolve (vegan/plant-based → vegan_options, mixed → mixed_group_suitable, gf → gluten_free). For a mixed group use mixed_group_suitable (confirmed vegan MEAL, not just a drink). gluten_free is owner-confirmed only; if a region has fewer than 10 confirmed venues the result is withheld and meta.dietaryCoverage reports it. · example:vegan_optionsforeign_languagesstringoptionalLanguages the venue can serve customers in (ISO 639-1, comma, all must match). en, zh, ja, es, de, fr. Owner-confirmed. Natural language (영어→en, 일본어→ja) resolves. e.g. English-speaking venues for foreign guests. · example:ensubtypestringoptionalNormalized venue sub-type (comma = OR, 40+). Food: korean, korean_bbq, gukbap_soup, noodles, chinese, japanese, sushi_sashimi, italian, seafood… Cafe: coffee, dessert, bakery, brunch, traditional_tea… Bars: cocktail_bar, wine_bar, izakaya, pocha, hof_beer… Natural language resolves. Prefer subtype over broad business_category for venue-type intent. Full list at /api/v1/meta. · example:korean_bbqbbq_meatstringoptionalMeat type a Korean BBQ venue serves (comma = OR): pork, beef, duck, lamb. Independent of subtype — subtype=korean_bbq picks the venue type, bbq_meat=pork narrows the meat. Mixed venues match both. · example:porkviewstringoptionalView type (comma = OR): ocean, sunset, river, mountain, night, city, garden. A venue with ocean+sunset matches both. Natural language (바다뷰→ocean, 한강뷰→river, 야경→night) resolves. · example:oceanmax_dish_priceintegeroptionalOnly venues with at least one dish at or under this price (KRW). 'Meals under 10,000 won' = max_dish_price=10000. Judged on the cheapest real dish (sides like rice or noodle add-ons excluded); venues with unknown prices are not included. For 'good value' without a number, use good_value=true. · example:10000foreigner_friendlybooleanoptionalPlaces you can manage without Korean: a foreign-language menu OR confirmed foreign-language service (either one). Menu only: english_menu=true. A specific language: foreign_languages. · example:truelegacybooleanoptionalOfficially designated long-running venues only (Centennial Stores, Seoul Oraegage, Seoul Future Heritage). For 'old-school / heritage restaurants' use this instead of a keyword. · example:truelocal_foodstringoptionalVenues whose name or signature dish is a local specialty of that region (Busan = dwaeji-gukbap, milmyeon…). Value: a region name (local_food=부산) or sido code, or true together with region_code. All 17 provinces. · example:부산excludestringoptional'Anything but…'. Removes venues whose name or signature dish is that food (comma = exclude all). Venues that merely list it as a side item stay. · example:돼지국밥muslim_friendlybooleanoptionalVenues known to welcome Muslim guests (halal wording in the name/menu, or owner-confirmed). NOT official halal certification — the response meta always carries a note to confirm certification, a pork-free kitchen, and alcohol with the venue. · example:truefeatured_bystringoptionalOnly venues introduced by a consenting ambassador (influencer). Partial match on name, handle, or channel. If nobody matches, you get 0 results plus meta.featuredBy listing who is available. · example:성시경associated_withstringoptionalOnly venues publicly reported as linked to a celebrity, group, or show ('where BTS ate', 'Goblin filming spot'). If nothing matches, you get 0 results plus meta.associatedWith listing available subjects. · example:BTSpet_friendlybooleanoptionalExample 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. · example:trueopen_atstringoptionalOnly places open at that time — a point or a meal window (KST). Point: 2026-08-26T19:00, '2026-08-26 19:00', '19:00' (today), 'now'. Meal windows: 'lunch' (11:00-14:00), 'dinner' (17:30-21:00), breakfast, brunch, late_night, a custom range '11:00-14:00', or combined with a date '2026-08-29 lunch'. Relative days: only 오늘/내일/모레 (today/tomorrow) are understood — send any other date absolutely. A window matches venues open for at least part of it, and the resolved range is echoed in meta.openAt.window. Based on regular hours, last order, and break times, including past-midnight sessions. Temporary closures and being full are not knowable. Venues with unconfirmed hours are excluded by default and reported via meta.openAt.unknownHoursExcluded. · example:2026-08-26T19:00include_unknown_hoursbooleanoptionalEscape hatch for open_at only. true also returns venues whose hours are unconfirmed (those are 'unknown', not 'open at that time'). · example:truereservation_channelstringoptionalHow the venue can be booked (comma = OR): yumi (bookable via POST /api/v1/reservations) · phone. 'Accepts reservations' is not 'has a table at that time' — actual availability is only known by placing a request. · example:yumifieldsstringoptionalPick fields (Field Mask). Comma-separated tier names (core/contact_hours/quality/edge/media), 'all', or individual field names. Defaults to core. Call tokens = the highest field tier requested (per-request; page_size does not affect tokens). Owner-uploaded photos come via photos (media tier, highest cost 8 — venue & menu image URLs); in lists use photoCount (quality) for a cheap count. recommendedFor may include occasion tags such as solo_dining, late_night, and late_night_eatery. · example:core,reviewCount,accessHintspageintegeroptionalPage (default 1) · example:1page_sizeintegeroptionalItems per page (max 100). Does not affect tokens (per-request billing). Live API keys can reach a per-plan result window (free 100 · Starter 1,000 · Pro/Scale 5,000); beyond that use Bulk Export. · example:20
Response example
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
}
}