{"openapi":"3.1.0","info":{"title":"HeyYumi API","version":"1.0.0","description":"Refined food & drink venue data (the 'oneset'): identity, location, standardized hours, menu, price band, review count, freshness, confidence, plus reservation endpoints so AI can find, recommend, and book. One curator's notebook, served as an API.\n\n## Field Mask & tiered billing\nUse the `fields` query param (comma-separated) to choose what you receive. Tokens can be tier names, `all`, or individual field names. Unknown tokens are ignored and reported via the `X-Map3-Ignored-Fields` response header. When `fields` is omitted, the default is `core`.\n\n## Authentication\nUse `Authorization: Bearer <API_KEY>` or the `X-API-Key` header. Do not put API keys in URLs. `?api_key=` is deprecated and scheduled for removal (it will be rejected with `401 query_auth_disabled`) because URLs are commonly stored in browser, proxy, server, and error logs.\n\nBilling is per request: each call is billed at the highest field tier you request (returned in the `X-Map3-Units` header). `page_size` does not change tokens.\n- `core` (= 1 token/request): id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt, placeUrl\n- `contact_hours` (= 2 tokens/request): phone, homepage, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h\n- `quality` (= 2 tokens/request): reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation\n- `edge` (= 4 tokens/request): accessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, ownerStory, influencerFeatures, culturalAssociations, legacy, reputation\n- `media` (= 8 tokens/request): photos\n\nAbuse is controlled by limits, not price: per-key rate limit (requests/min) and a token cap by plan (daily on the free tier, monthly on paid plans; 429 with `Retry-After`), and a result window for the live API (100 results on the free tier, 1,000 on Starter, 5,000 on Pro and Scale). Larger or full-dataset extraction requires Bulk Export / data licensing, not paginated API calls (see Acceptable Use in the Terms).","contact":{"name":"heyyumi","url":"https://heyyumi.ai"}},"servers":[{"url":"https://api.heyyumi.ai"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Preferred: Authorization: Bearer <API_KEY>. Do not pass keys in URLs."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative header auth. Query-string api_key is deprecated."}}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/api/v1/places":{"get":{"operationId":"list-places","summary":"Search places","description":"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.","parameters":[{"name":"keyword","in":"query","required":false,"description":"Partial 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.","schema":{"type":"string"},"example":"버거킹"},{"name":"region_code","in":"query","required":false,"description":"Region (admin-dong) code","schema":{"type":"string"}},{"name":"business_category","in":"query","required":false,"description":"One business type. Food: restaurant/cafe/bar. Beauty: salon/nail/esthetic/lash/waxing (or beauty for all of them). Fitness: gym/pilates/yoga (or fitness; Yumi partners only). Each search covers one of these groups; without business_category you get food only, even with a keyword. Values: GET /api/v1/meta → filters.businessCategory","schema":{"type":"string"},"example":"restaurant"},{"name":"min_confidence","in":"query","required":false,"description":"Minimum confidence (0-1)","schema":{"type":"number"},"example":"0.6"},{"name":"sort","in":"query","required":false,"description":"discovery (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.","schema":{"type":"string"},"example":"discovery"},{"name":"recommended_for","in":"query","required":false,"description":"Narrow 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.","schema":{"type":"string"},"example":"group_dining"},{"name":"atmosphere","in":"query","required":false,"description":"Atmosphere (comma). quiet, lively, view, cozy, trendy, spacious, traditional, clean, work_study, rainy_mood.","schema":{"type":"string"},"example":"quiet"},{"name":"parking","in":"query","required":false,"description":"Only places with confirmed parking. See parking_type for the kind.","schema":{"type":"boolean"},"example":"true"},{"name":"parking_type","in":"query","required":false,"description":"Parking type: onsite, valet, partner, nearby, none. Natural language (e.g. 발렛→valet) resolves.","schema":{"type":"string"},"example":"onsite"},{"name":"reservable","in":"query","required":false,"description":"Only reservable places (crawl-confirmed plus Yumi Partner venues).","schema":{"type":"boolean"},"example":"true"},{"name":"payment_methods","in":"query","required":false,"description":"Require 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.","schema":{"type":"string"},"example":"alipay"},{"name":"serves","in":"query","required":false,"description":"Serves (comma). coffee, alcohol, dessert, vegetarian, vegan.","schema":{"type":"string"},"example":"alcohol"},{"name":"dietary","in":"query","required":false,"description":"Dietary (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.","schema":{"type":"string"},"example":"vegan_options"},{"name":"foreign_languages","in":"query","required":false,"description":"Languages 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.","schema":{"type":"string"},"example":"en"},{"name":"subtype","in":"query","required":false,"description":"Normalized 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.","schema":{"type":"string"},"example":"korean_bbq"},{"name":"bbq_meat","in":"query","required":false,"description":"Meat 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.","schema":{"type":"string"},"example":"pork"},{"name":"view","in":"query","required":false,"description":"View type (comma = OR): ocean, sunset, river, mountain, night, city, garden. A venue with ocean+sunset matches both. Natural language (바다뷰→ocean, 한강뷰→river, 야경→night) resolves.","schema":{"type":"string"},"example":"ocean"},{"name":"max_dish_price","in":"query","required":false,"description":"Only 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.","schema":{"type":"integer"},"example":"10000"},{"name":"foreigner_friendly","in":"query","required":false,"description":"Places 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.","schema":{"type":"boolean"},"example":"true"},{"name":"legacy","in":"query","required":false,"description":"Officially designated long-running venues only (Centennial Stores, Seoul Oraegage, Seoul Future Heritage). For 'old-school / heritage restaurants' use this instead of a keyword.","schema":{"type":"boolean"},"example":"true"},{"name":"local_food","in":"query","required":false,"description":"Venues 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.","schema":{"type":"string"},"example":"부산"},{"name":"exclude","in":"query","required":false,"description":"'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.","schema":{"type":"string"},"example":"돼지국밥"},{"name":"muslim_friendly","in":"query","required":false,"description":"Venues 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.","schema":{"type":"boolean"},"example":"true"},{"name":"featured_by","in":"query","required":false,"description":"Only 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.","schema":{"type":"string"},"example":"성시경"},{"name":"associated_with","in":"query","required":false,"description":"Only 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.","schema":{"type":"string"},"example":"BTS"},{"name":"pet_friendly","in":"query","required":false,"description":"Example 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.","schema":{"type":"boolean"},"example":"true"},{"name":"open_at","in":"query","required":false,"description":"Only 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.","schema":{"type":"string"},"example":"2026-08-26T19:00"},{"name":"include_unknown_hours","in":"query","required":false,"description":"Escape hatch for open_at only. true also returns venues whose hours are unconfirmed (those are 'unknown', not 'open at that time').","schema":{"type":"boolean"},"example":"true"},{"name":"reservation_channel","in":"query","required":false,"description":"How 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.","schema":{"type":"string"},"example":"yumi"},{"name":"fields","in":"query","required":false,"description":"Pick 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.","schema":{"type":"string"},"example":"core,reviewCount,accessHints"},{"name":"page","in":"query","required":false,"description":"Page (default 1)","schema":{"type":"integer"},"example":"1"},{"name":"page_size","in":"query","required":false,"description":"Items 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.","schema":{"type":"integer"},"example":"20"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"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}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/places/nearby":{"get":{"operationId":"nearby-places","summary":"Nearby search","description":"Find places around a coordinate (lat·lng) within a radius (m), nearest first. Each result includes distanceM (meters from center). sort=discovery switches to recommendation ranking within the radius. fields/tokens behave like Search places.","parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"number"},"example":"37.5704"},{"name":"lng","in":"query","required":true,"description":"Longitude","schema":{"type":"number"},"example":"126.9921"},{"name":"radius","in":"query","required":false,"description":"Radius in meters (default 1000, max 5000)","schema":{"type":"integer"},"example":"500"},{"name":"business_category","in":"query","required":false,"description":"Business type filter (same values as search; fitness = Yumi partners only)","schema":{"type":"string"},"example":"cafe"},{"name":"keyword","in":"query","required":false,"description":"Partial 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.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"distance (default, nearest first) or discovery (recommendation ranking within the radius). Use distance for 'closest to me', discovery for 'somewhere good near here'. meta.sort reports the sort actually applied (may degrade to distance on deep pages or wide radii).","schema":{"type":"string"},"example":"discovery"},{"name":"recommended_for","in":"query","required":false,"description":"Narrow 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.","schema":{"type":"string"},"example":"group_dining"},{"name":"atmosphere","in":"query","required":false,"description":"Atmosphere (comma). quiet, lively, view, cozy, trendy, spacious, traditional, clean, work_study, rainy_mood.","schema":{"type":"string"},"example":"quiet"},{"name":"parking","in":"query","required":false,"description":"Only places with confirmed parking. See parking_type for the kind.","schema":{"type":"boolean"},"example":"true"},{"name":"parking_type","in":"query","required":false,"description":"Parking type: onsite, valet, partner, nearby, none. Natural language (e.g. 발렛→valet) resolves.","schema":{"type":"string"},"example":"onsite"},{"name":"reservable","in":"query","required":false,"description":"Only reservable places (crawl-confirmed plus Yumi Partner venues).","schema":{"type":"boolean"},"example":"true"},{"name":"payment_methods","in":"query","required":false,"description":"Require 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.","schema":{"type":"string"},"example":"alipay"},{"name":"serves","in":"query","required":false,"description":"Serves (comma). coffee, alcohol, dessert, vegetarian, vegan.","schema":{"type":"string"},"example":"alcohol"},{"name":"dietary","in":"query","required":false,"description":"Dietary (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.","schema":{"type":"string"},"example":"vegan_options"},{"name":"foreign_languages","in":"query","required":false,"description":"Languages 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.","schema":{"type":"string"},"example":"en"},{"name":"subtype","in":"query","required":false,"description":"Normalized 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.","schema":{"type":"string"},"example":"korean_bbq"},{"name":"bbq_meat","in":"query","required":false,"description":"Meat 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.","schema":{"type":"string"},"example":"pork"},{"name":"view","in":"query","required":false,"description":"View type (comma = OR): ocean, sunset, river, mountain, night, city, garden. A venue with ocean+sunset matches both. Natural language (바다뷰→ocean, 한강뷰→river, 야경→night) resolves.","schema":{"type":"string"},"example":"ocean"},{"name":"max_dish_price","in":"query","required":false,"description":"Only 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.","schema":{"type":"integer"},"example":"10000"},{"name":"foreigner_friendly","in":"query","required":false,"description":"Places 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.","schema":{"type":"boolean"},"example":"true"},{"name":"legacy","in":"query","required":false,"description":"Officially designated long-running venues only (Centennial Stores, Seoul Oraegage, Seoul Future Heritage). For 'old-school / heritage restaurants' use this instead of a keyword.","schema":{"type":"boolean"},"example":"true"},{"name":"local_food","in":"query","required":false,"description":"Venues 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.","schema":{"type":"string"},"example":"부산"},{"name":"exclude","in":"query","required":false,"description":"'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.","schema":{"type":"string"},"example":"돼지국밥"},{"name":"muslim_friendly","in":"query","required":false,"description":"Venues 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.","schema":{"type":"boolean"},"example":"true"},{"name":"featured_by","in":"query","required":false,"description":"Only 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.","schema":{"type":"string"},"example":"성시경"},{"name":"associated_with","in":"query","required":false,"description":"Only 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.","schema":{"type":"string"},"example":"BTS"},{"name":"pet_friendly","in":"query","required":false,"description":"Example 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.","schema":{"type":"boolean"},"example":"true"},{"name":"open_at","in":"query","required":false,"description":"Only 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.","schema":{"type":"string"},"example":"2026-08-26T19:00"},{"name":"include_unknown_hours","in":"query","required":false,"description":"Escape hatch for open_at only. true also returns venues whose hours are unconfirmed (those are 'unknown', not 'open at that time').","schema":{"type":"boolean"},"example":"true"},{"name":"reservation_channel","in":"query","required":false,"description":"How 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.","schema":{"type":"string"},"example":"yumi"},{"name":"fields","in":"query","required":false,"description":"Pick 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.","schema":{"type":"string"},"example":"core,reviewCount,accessHints"},{"name":"page","in":"query","required":false,"description":"Page (default 1)","schema":{"type":"integer"},"example":"1"},{"name":"page_size","in":"query","required":false,"description":"Items 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.","schema":{"type":"integer"},"example":"20"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"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","distanceM":0}],"meta":{"total":12,"page":1,"pageSize":20,"totalPages":1,"center":{"lat":37.5704,"lng":126.9921},"radius":500}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/places/{id}":{"get":{"operationId":"get-place","summary":"Place detail","description":"A single place. Use fields to fetch only the tiers you need (fields=all returns hours, menu, access hints, recommendation context, and more).","parameters":[{"name":"id","in":"path","required":true,"description":"Place id (canonical)","schema":{"type":"string"},"example":"11782345"},{"name":"fields","in":"query","required":false,"description":"Pick 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.","schema":{"type":"string"},"example":"core,reviewCount,accessHints"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"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","rating":null,"reviewCount":10731,"latestReviewDate":"2026-06-15","freshnessScore":0.82,"dataQuality":{"veracity":5,"completeness":1,"confidence":0.64,"recency":0.99,"last_verified_days_ago":4},"price":{"level":2,"avg":8000,"min":4500,"max":12000},"menuSummary":{"count":12,"items":["콩나물국밥","수육","모둠전"]},"openNow":{"open":true,"reason":"open","lastOrderPassed":false},"closureSignal":null,"promotion":null,"nearestStation":{"station":"홍제","walkMin":5},"photoCount":5,"photos":{"count":5,"main":"https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000000.jpg","gallery":[{"category":"interior","url":"https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000000.jpg","isMain":true},{"category":"exterior","url":"https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000001.jpg","isMain":false}],"menu":[{"menuItem":"콩나물국밥","url":"https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000002.jpg"}],"menuBoard":["https://<supabase>/storage/v1/object/public/owner-photos/<uid>/11892345/1718000000003.jpg"]},"phone":"02-123-4567","homepage":null,"bookingUrl":null,"yumiReservable":false,"reservationChannels":["phone"],"snsLinks":null,"businessHours":[{"day":"mon","closed":false,"open":"00:00","close":"24:00","endsNextDay":false,"breaks":[],"lastOrder":null}],"is24h":true,"temporaryClosures":null,"accessHints":{"subway":[{"station":"홍제","lines":["3호선"],"distanceM":360,"walkMin":5},{"station":"무악재","lines":["3호선"],"distanceM":920,"walkMin":13}]},"recommendedFor":["solo_dining","late_night","late_night_eatery"],"atmosphere":["캐주얼","빠른"],"menu":[{"name":"콩나물국밥","price":8000,"recommend":true,"isNew":false,"description":"24시간 끓인 진한 국물에 아삭한 콩나물."},{"name":"매생이굴국밥","price":9500,"recommend":false,"isNew":true}],"serviceAttributes":{"parking":true,"parking_type":"onsite","parking_fee":"paid","parking_note":"매장 주차 가능(유료)","dine_in":true,"reservable":true,"venue_subtype":"gukbap_soup","foreign_languages":["en"],"dietary":{"fully_vegan":false,"vegan_options":true,"vegetarian_options":true,"mixed_group_suitable":true,"vegan_menu_count":3,"vegan_main_count":2,"non_vegan_menu_count":8,"confidence":0.62,"note":"비건 메뉴와 일반 메뉴가 함께 있어 비건과 비(非)비건이 같이 가기 좋아요. 조리 분리는 확인이 필요해요."}},"atmosphereScores":{"late_night":6,"late_night_eatery":8,"quiet":6.5,"lively":4},"aiSummary":"홍제역 근처 캐주얼 국밥집, 혼밥·심야식당 수요에 적합.","influencerFeatures":[{"platform":"instagram","account":"example.creator","profileUrl":"https://www.instagram.com/example.creator","featuredAt":"2026-08-19","dishes":[],"contentUrls":[{"url":"https://www.instagram.com/reel/EXAMPLE1/","postedAt":"2026-08-19"}],"media":[{"kind":"video_cover","url":"https://…/influencer-media/example.creator/1/0.jpg","posterUrl":null,"postUrl":"https://www.instagram.com/reel/EXAMPLE1/","postedAt":"2026-08-19","credit":"@example.creator (Instagram)"}]}]}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/places/{id}/history":{"get":{"operationId":"place-history","summary":"Place history","description":"A record of the days when the review count or latest review date changed (updated nightly, newest first, up to 365 rows). Gaps between dates mean nothing changed in between. Use it to judge changes in a place's activity yourself. Star ratings are not provided, so rating is always null.","parameters":[{"name":"id","in":"path","required":true,"description":"Place id (canonical)","schema":{"type":"string"},"example":"11782345"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"success":true,"data":[{"date":"2026-10-16","reviewCount":10812,"rating":null,"latestReviewDate":"2026-10-15","freshnessScore":0.97},{"date":"2026-06-18","reviewCount":10731,"rating":null,"latestReviewDate":"2026-06-15","freshnessScore":0.82}],"meta":{"recording":"change_only","note":"A row is recorded only on days when reviewCount, latestReviewDate or source count changed; gaps mean no change."}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/regions":{"get":{"operationId":"list-regions","summary":"Regions · resolve dong name","description":"Resolves a dong (neighborhood) name into codes & coordinates (location lookup when you have no GPS). Dong names are not unique (e.g. Hongje-dong = Seoul Seodaemun-gu + Gangwon Gangneung), so candidates are returned disambiguated by sido/sigungu, with place counts and a representative center. Feed a chosen center into /places/nearby to also cover adjacent dongs. Without dong, lists all regions that have places.","parameters":[{"name":"dong","in":"query","required":false,"description":"Dong name (e.g. 홍제동) — returns candidates","schema":{"type":"string"},"example":"홍제동"},{"name":"sigungu","in":"query","required":false,"description":"Narrow by sigungu (e.g. 서대문구)","schema":{"type":"string"}},{"name":"sido","in":"query","required":false,"description":"Narrow by sido (e.g. 서울특별시)","schema":{"type":"string"}},{"name":"region_code","in":"query","required":false,"description":"Look up a single region code","schema":{"type":"string"}},{"name":"include_empty","in":"query","required":false,"description":"Include regions with no places yet (default false)","schema":{"type":"boolean"}}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"success":true,"data":[{"regionCode":"1141011100","sido":"서울특별시","sigungu":"서대문구","dong":"홍제동","fullName":"서울특별시 서대문구 홍제동","center":{"lat":37.577976,"lng":126.938483},"placeCount":280}]}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/categories":{"get":{"operationId":"list-categories","summary":"Categories","description":"Place counts per category in the oneset.","parameters":[],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"success":true,"data":[{"category":"restaurant","count":354029}]}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/stats":{"get":{"operationId":"stats","summary":"Dataset stats","description":"Total places, regions, multi-source share, average confidence, category breakdown.","parameters":[],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"success":true,"data":{"totalPlaces":523685,"totalRegions":2453,"multiSourcePlaces":414650,"avgConfidence":0.869,"byCategory":[{"category":"restaurant","count":354029},{"category":"cafe","count":134241},{"category":"bar","count":35239}]}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/meta":{"get":{"operationId":"meta","summary":"Filter & field vocabulary","description":"Key-free (no billing, 1h cache). Returns the supported attribute filters, values, natural-language aliases, and field tiers. The single source of truth for filter vocabulary, which MCP and SDKs sync from automatically.","parameters":[],"security":[],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"version":1,"filters":{"boolean":["wifi","parking","outdoor_seating","pet_friendly","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"],"enum":{"parking_type":["onsite","valet","partner","nearby","none"]},"subtype":["cocktail_bar","whisky_bar","wine_bar","bar_generic","izakaya","pocha","hof_beer","korean_pub","coffee","dessert","bakery","ice_cream","brunch","tea","traditional_tea","juice_fruit","themed","korean","korean_bbq","gopchang","jokbal_bossam","chicken","chinese","japanese","sushi_sashimi","western","italian","vietnamese","asian","noodles","bunsik","burger","gukbap_soup","jjigae","shabu","seafood","salad_healthy","sandwich_deli","lunchbox","buffet"],"bbq_meat":["pork","beef","duck","lamb"],"view":["ocean","sunset","river","mountain","night","city","garden"],"reservationChannel":["yumi","phone"],"array":{"payment_methods":["cash","card","toss_pay","kakao_pay","naver_pay","zero_pay","local_gift","gov_support","alipay","wechat_pay","apple_pay","samsung_pay","unionpay"],"serves":["coffee","alcohol","dessert","vegetarian","vegan"],"dietary":["vegan_options","vegetarian_options","fully_vegan","mixed_group_suitable","vegetarian_mixed_group_suitable","gluten_free"],"foreign_languages":["en","zh","ja","es","de","fr"],"recommended_for":["solo_dining","solo_drinking","date","group_dining","group_drinking","family","business_meeting","formal_gathering","late_night","late_night_eatery"],"atmosphere":["cozy","quiet","lively","spacious","view","trendy","traditional","clean","work_study","rainy_mood"]},"aliases":{"recommended_for":{"회식":"group_dining","혼밥":"solo_dining","상견례":"formal_gathering"},"atmosphere":{"조용한":"quiet","뷰맛집":"view"},"parking_type":{"발렛":"valet"},"foreign_languages":{"영어":"en","일본어":"ja"},"subtype":{"삼겹살":"korean_bbq","국밥":"gukbap_soup","칵테일바":"cocktail_bar"},"bbq_meat":{"삼겹살":"pork","한우":"beef","오리":"duck"},"view":{"바다뷰":"ocean","한강뷰":"river","야경":"night"},"dietary":{"비건":"vegan_options","글루텐프리":"gluten_free"}}},"fields":{"tiers":{"core":1,"contact_hours":2,"quality":2,"edge":4,"media":8},"byField":{"name":"core","temporaryClosures":"contact_hours","reviewCount":"quality","serviceAttributes":"edge","influencerFeatures":"edge","photos":"media"}},"coverage":{"supported":["서울","경기","부산","제주","인천","대전","세종","충북","충남"],"note":"현재 서울·경기·부산·제주·인천·대전·세종·충남·충북 9개 시/도를 공식 제공(coverage 확대 중). 그 밖 지역(대구·광주·강원 등)은 결과가 비면 '아직 미지원'으로 안내."}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/reservations":{"post":{"operationId":"create-reservation","summary":"Request a reservation","description":"Request a table reservation at any venue that takes requests (detail shows yumiBooking.canRequest=true — Yumi Partners plus most other venues). No prepayment. The request goes straight to the venue and the response starts as status='pending' (not yet confirmed). The owner accepting → confirmed, declining → cancelled, no response (~5 min) → expired. Poll the status endpoint (GET) for the outcome. The guest is texted progress via KakaoTalk/SMS. Non-partner venues (yumiBooking.partner=false) take requests during their own request hours (yumiBooking.requestHours, e.g. 16:30-20:00 KST — from 30 minutes before the venue opens that day, never before 10:00). Outside those hours you get 422 reservation_requests_closed (retryAfter = next start, requestHoursKst = that venue's hours), unless you send deferIfClosed:true: then the request is held and the venue reviews it from that start time (response reviewStartsAt; the reservation time must be at least an hour after that; the guest gets the result by text or email). if the venue is closed at the requested time, 422 venue_closed_at_requested_time (pick another time); if the time is later than 2 hours before closing, 422 reservation_too_close_to_closing (latestReservation = the latest time accepted); if the venue only seats walk-ins on that weekday (detail yumiBooking.walkInOnlyDays), 422 walk_in_only_day (pick another day); when a non-partner venue is on its day off (closed today, or closed days fall before it next takes requests; detail yumiBooking.requestsResumeAt), the request isn't held even with deferIfClosed and you get 422 venue_day_off (retryAfter = when it takes requests again; ask the guest to send it then); partner venues that are closed today also return 422 venue_day_off for any date (closedToday:true, no retryAfter — ask the guest to send it on a day the venue is open; detail yumiBooking.closedToday shows this ahead of time); venues that can't take requests return 422 reservation_not_available (do not retry — tell the user this venue can't be booked through HeyYumi yet). Pass idempotencyKey to safely retry the same request without creating duplicates. To test an integration, send the `X-Map3-Sandbox: 1` header: validation and the partner check run for real, but nothing is stored and no owner push or guest text goes out. You get a simulated reservation (reservationId starts with sbx_r_, sandbox:true) that settles after about 8 seconds (confirmed by default, change it with sandboxOutcome). The playground always runs in sandbox mode.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["placeId","reservationTime","guestCount","guestPhone","idempotencyKey"],"properties":{"placeId":{"type":"string","description":"Canonical place id. Get it from a search first. The example is a Yumi Partner venue.","example":"1726507251"},"reservationTime":{"type":"string","description":"Requested date & time in ISO 8601 with timezone offset (future). Korea is +09:00.","example":"2026-12-01T19:00:00+09:00"},"guestCount":{"type":"integer","description":"Party size (at least 1).","example":"2"},"guestPhone":{"type":"string","description":"Guest phone (required) — for status texts (KakaoTalk/SMS) and no-show contact. Missing → guest_phone_required.","example":"010-1234-5678"},"guestName":{"type":"string","description":"Guest name (recommended) so the owner knows who's coming.","example":"홍길동"},"guestEmail":{"type":"string","description":"Guest email. Required when the phone is not a Korean number — we can't text international numbers, so status updates and the view/cancel link go by email. Missing → guest_email_required.","example":"guest@example.com"},"guestLanguage":{"type":"string","description":"Language the guest reads (ISO 639-1, e.g. en, ja, zh). Guest notices go out in this language. If omitted we guess from the note and phone number.","example":"en"},"note":{"type":"string","description":"Optional note to the owner (seating, occasion, allergies)."},"idempotencyKey":{"type":"string","description":"Stable key (e.g. a UUID) to safely retry the same reservation. Required on REST; the MCP request_reservation tool generates one if omitted, and so does the playground on each run."},"deferIfClosed":{"type":"boolean","description":"If true, a non-partner request outside that venue's request hours (yumiBooking.requestHours, from 30 minutes before it opens that day until 20:00 KST) is held and the venue reviews it from the next start time. The response carries reviewStartsAt, and you don't need to keep polling meanwhile (the guest is told by text or email). Omit it to get 422 reservation_requests_closed.","example":"true"},"sandboxOutcome":{"type":"string","description":"Sandbox only: the outcome to simulate, confirmed (default), cancelled, or expired (after 5 min). Ignored in live mode.","example":"confirmed"}}}}}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"success":true,"data":{"reservationId":"b1f2c3d4-0000-0000-0000-000000000000","status":"pending","placeId":"1726507251","expiresAt":"2026-12-01T10:05:00.000Z"}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"404":{"description":"Reservation or venue not found (venue_not_found / reservation_not_found)"},"422":{"description":"Venue cannot take this request: reservation_not_available (this venue can't be booked through HeyYumi yet), reservation_requests_closed (non-partner venues take requests 10:00–20:00 KST; see retryAfter, or send deferIfClosed:true to have it held and reviewed from the next 10:00, response reviewStartsAt), venue_closed_at_requested_time, or reservation_too_close_to_closing (reservation times are taken only up to 2 hours before closing; see latestReservation), walk_in_only_day (the venue only seats walk-ins on that weekday; see walkInOnlyDays), or venue_day_off (the venue is on its day off and isn't taking or holding requests; non-partner: see retryAfter; any venue closed today: closedToday:true)"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/reservations/{id}":{"get":{"operationId":"get-reservation","summary":"Reservation status (long-poll)","description":"Check a reservation's current status. status: pending, confirmed, cancelled, expired, no_show. Pass ?wait=<sec> (max 25) to long-poll — it returns the moment the reservation settles (confirmed/cancelled/expired); if still pending, call again to fill the ~5-minute window, then report the final settled outcome. Sandbox ids (sbx_r_…) are polled the same way.","parameters":[{"name":"id","in":"path","required":true,"description":"The reservationId returned by the create call.","schema":{"type":"string"},"example":"b1f2c3d4-0000-0000-0000-000000000000"},{"name":"wait","in":"query","required":false,"description":"Long-poll seconds (0-25). Omit for a one-shot check.","schema":{"type":"integer"},"example":"25"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"success":true,"data":{"reservationId":"b1f2c3d4-0000-0000-0000-000000000000","placeId":"11782345","status":"confirmed","settled":true,"reservationTime":"2026-09-01T19:00:00+09:00","guestCount":2,"approvedAt":"2026-09-01T10:02:11.000Z","createdAt":"2026-09-01T10:00:00.000Z","expiresAt":"2026-09-01T10:05:00.000Z"}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"404":{"description":"Reservation or venue not found (venue_not_found / reservation_not_found)"},"422":{"description":"Venue cannot take this request: reservation_not_available (this venue can't be booked through HeyYumi yet), reservation_requests_closed (non-partner venues take requests 10:00–20:00 KST; see retryAfter, or send deferIfClosed:true to have it held and reviewed from the next 10:00, response reviewStartsAt), venue_closed_at_requested_time, or reservation_too_close_to_closing (reservation times are taken only up to 2 hours before closing; see latestReservation), walk_in_only_day (the venue only seats walk-ins on that weekday; see walkInOnlyDays), or venue_day_off (the venue is on its day off and isn't taking or holding requests; non-partner: see retryAfter; any venue closed today: closedToday:true)"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/live-status":{"post":{"operationId":"create-live-status","summary":"Live status (ask the venue right now)","description":"Send the owner a time-sensitive question that map/review/static data can't answer and that changes through the day — (A) is this menu item available now / today's fresh stock / sold out (kind=item), (D) how long is the wait right now (kind=wait), (E) can a party of N get in right now (kind=seats, headcount required). Same rail as reservations: at a venue with an active owner (on the Yumi Partners app) the app gets an instant push and the response starts as status='pending' (5-minute answer window). The owner answers with one tap → available, limited, unavailable, soon, or not_offered; poll GET /api/v1/live-status/{queryId} (long-poll) for the outcome. To avoid re-bothering the owner, if a fresh answer already exists for the same venue+topic it's reused instantly (reused=true), and a pending identical question is joined. If 'now' is outside confirmed opening hours the owner is not disturbed and you get blocked='closed_now' immediately (do not retry — surface the hours). Venues without an active owner return 422 live_status_not_available. Do not use this for static info like hours, parking, or pet policy — answer those from search. With the `X-Map3-Sandbox: 1` header, the venue check and opening-hours guard run for real, nothing is sent to the owner, and a simulated answer arrives after about 8 seconds (queryId starts with sbx_l_, sandbox:true). The playground always runs in sandbox mode.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["placeId","kind","topic"],"properties":{"placeId":{"type":"string","description":"Canonical place id. Get it from a search first. The example is a Yumi Partner venue.","example":"1726507251"},"kind":{"type":"string","description":"Question kind: item (menu/stock) · wait (queue) · seats (immediate seating, include headcount).","example":"item"},"topic":{"type":"string","description":"The subject as a bare token, not a sentence. e.g. '두바이 쫀득 쿠키', 'yellowtail', 'wait', 'party of 10'. For item, use the venue's actual menu name.","example":"두바이 쫀득 쿠키"},"question":{"type":"string","description":"The guest's original wording (optional), for owner context.","example":"지금 두바이 쫀득 쿠키 있어요?"},"sandboxOutcome":{"type":"string","description":"Sandbox only: the answer to simulate, available, limited, unavailable, soon, not_offered, or no_response (after 5 min). Omit for a default answer by kind. Ignored in live mode."}}}}}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"success":true,"data":{"queryId":"c2e4f6a8-0000-0000-0000-000000000000","placeId":"11782345","kind":"item","topic":"두바이 쫀득 쿠키","status":"pending","note":null,"settled":false,"fresh":false,"interestedCount":1,"expiresAt":"2026-09-04T00:05:00.000Z"}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"404":{"description":"Live status query not found (not_found)"},"422":{"description":"Venue can't take live questions yet (live_status_not_available) — no active owner on the Yumi Partners app"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}},"get":{"operationId":"search-live-status","summary":"Fresh live answer (optional)","description":"If a still-valid owner-confirmed answer exists for placeId + topic, it's returned without asking (found:true + status, note, verifiedAt, validUntil). Otherwise found:false — then POST to ask fresh. You usually only need POST (it reuses on its own); use this only to peek at 'just-confirmed' info without triggering anything.","parameters":[{"name":"placeId","in":"query","required":true,"description":"Canonical place id.","schema":{"type":"string"},"example":"11782345"},{"name":"topic","in":"query","required":true,"description":"The subject token (same as POST's topic).","schema":{"type":"string"},"example":"두바이 쫀득 쿠키"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"success":true,"data":{"found":true,"queryId":"c2e4f6a8-0000-0000-0000-000000000000","placeId":"11782345","kind":"item","topic":"두바이 쫀득 쿠키","status":"available","note":null,"verifiedAt":"2026-09-04T00:02:30.000Z","verifiedBy":"merchant","validUntil":"2026-09-04T00:32:30.000Z","fresh":true,"interestedCount":4}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"404":{"description":"Live status query not found (not_found)"},"422":{"description":"Venue can't take live questions yet (live_status_not_available) — no active owner on the Yumi Partners app"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}},"/api/v1/live-status/{queryId}":{"get":{"operationId":"get-live-status","summary":"Live status result (long-poll)","description":"Check a live question's current status. status: pending, available, limited, unavailable, soon, not_offered, no_response (owner didn't answer in 5 min). Pass ?wait=<sec> (max 25) to long-poll — it returns the moment the owner answers or the 5-minute window lapses (settled); if still pending, call again to fill the ~5-minute window, then report the result with the verified time. note may carry the owner's extra memo (e.g. wait '20분', 'we can seat you separately'). verifiedAt = when it was confirmed; validUntil = how long the answer stays reusable for other guests (varies by kind).","parameters":[{"name":"queryId","in":"path","required":true,"description":"The queryId returned by the create call.","schema":{"type":"string"},"example":"c2e4f6a8-0000-0000-0000-000000000000"},{"name":"wait","in":"query","required":false,"description":"Long-poll seconds (0-25). Omit for a one-shot check.","schema":{"type":"integer"},"example":"25"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"OK","headers":{"X-Map3-Units":{"description":"Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).","schema":{"type":"integer"}},"X-Map3-Ignored-Fields":{"description":"Comma-separated unknown field tokens that were ignored (present only when some were dropped).","schema":{"type":"string"}}},"content":{"application/json":{"example":{"success":true,"data":{"queryId":"c2e4f6a8-0000-0000-0000-000000000000","placeId":"11782345","kind":"wait","topic":"웨이팅","status":"limited","note":"20분","settled":true,"verifiedAt":"2026-09-04T00:02:30.000Z","verifiedBy":"merchant","validUntil":"2026-09-04T00:12:30.000Z","fresh":true,"interestedCount":3,"createdAt":"2026-09-04T00:00:00.000Z","expiresAt":"2026-09-04T00:05:00.000Z"}}}}},"400":{"description":"Invalid parameters / bulk_export_required (result window too large)"},"401":{"description":"API key required or invalid"},"404":{"description":"Live status query not found (not_found)"},"422":{"description":"Venue can't take live questions yet (live_status_not_available) — no active owner on the Yumi Partners app"},"429":{"description":"Rate limit, daily quota, or monthly quota exceeded (see Retry-After)"}}}}}}