Referenz

API-Referenz

Alle öffentlichen v1-Endpunkte. Reservierungsanfragen und Live-Anfragen laufen über POST, alles andere über GET. Außer /meta brauchen alle Endpunkte einen Bearer-Schlüssel.

OpenAPI JSON ↓
GET/api/v1/places

Search 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.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

  • keywordstringoptionalPartial 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. · Beispiel: 버거킹
  • region_codestringoptionalRegion 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_categorystringoptionalOne 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. · Beispiel: restaurant
  • min_confidencenumberoptionalMinimum confidence, 0 to 1, compared with each venue's confidence field. Venues below it are left out, and this filter is never dropped. · Beispiel: 0.6
  • sortstringoptionaldiscovery 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. · Beispiel: discovery
  • recommended_forstringoptionalOccasion 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. · Beispiel: group_dining
  • atmospherestringoptionalAtmosphere 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). · Beispiel: quiet
  • parkingbooleanoptionalOnly venues with confirmed parking. If nothing matches, this filter is dropped and listed in meta.relaxedFilters. Use parking_type for the kind of parking. · Beispiel: true
  • parking_typestringoptionalKind of parking: onsite, valet, partner (a partner lot), nearby, none. Korean words work too (발렛 → valet). · Beispiel: onsite
  • reservablebooleanoptionalOnly 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. · Beispiel: true
  • payment_methodsstringoptionalPayment 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. · Beispiel: alipay
  • servesstringoptionalWhat 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. · Beispiel: alcohol
  • dietarystringoptionalDietary 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. · Beispiel: vegan_options
  • foreign_languagesstringoptionalLanguages 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). · Beispiel: en
  • subtypestringoptionalVenue 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. · Beispiel: korean_bbq
  • bbq_meatstringoptionalMeat 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). · Beispiel: pork
  • viewstringoptionalView 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. · Beispiel: ocean
  • max_dish_priceintegeroptionalOnly 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. · Beispiel: 10000
  • foreigner_friendlybooleanoptionalVenues 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. · Beispiel: true
  • legacybooleanoptionalOfficially 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. · Beispiel: true
  • local_foodstringoptionalVenues 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. · Beispiel: 부산
  • excludestringoptionalLeaves 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. · Beispiel: 돼지국밥
  • muslim_friendlybooleanoptionalVenues 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. · Beispiel: true
  • featured_bystringoptionalOnly 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. · Beispiel: 성시경
  • associated_withstringoptionalOnly 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. · Beispiel: BTS
  • pet_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. · Beispiel: true
  • open_atstringoptionalOnly 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. · Beispiel: 2026-08-26T19:00
  • include_unknown_hoursbooleanoptionalOnly 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. · Beispiel: true
  • reservation_channelstringoptionalHow 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. · Beispiel: yumi
  • fieldsstringoptionalFields 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. · Beispiel: core,reviewCount,accessHints
  • pageintegeroptionalPage (default 1) · Beispiel: 1
  • page_sizeintegeroptionalResults 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. · Beispiel: 20

Antwortbeispiel

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
  }
}
GET/api/v1/places/nearby

Nearby search

Find venues within a radius of a coordinate, nearest first. Each result has distanceM, the distance from the center in meters, and total counts the matches inside the radius. sort=discovery ranks them by recommendation instead. Filters, fields, and token cost work as in Search places. If the radius holds more venues than can be checked, meta.truncated is true.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

  • latnumbererforderlichLatitude · Beispiel: 37.5704
  • lngnumbererforderlichLongitude · Beispiel: 126.9921
  • radiusintegeroptionalSearch radius in meters. Default 1000, max 5000; larger values are capped at 5000. · Beispiel: 500
  • business_categorystringoptionalBusiness type, same values as Search places. Fitness types return Yumi Partner venues only. · Beispiel: cafe
  • keywordstringoptionalPartial 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.
  • min_confidencenumberoptionalMinimum confidence, 0 to 1, same as Search places. · Beispiel: 0.6
  • sortstringoptionaldistance (default, nearest first) or discovery (ranked by recommendation within the radius). Use distance for 'closest to me' and discovery for 'somewhere good around here'. meta.sort reports the sort actually used: discovery falls back to distance when page × page_size goes past 500 or ranking times out. When the radius holds more than 500 matches, discovery ranks the nearest 500 and sets meta.truncated. · Beispiel: discovery
  • recommended_forstringoptionalOccasion 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. · Beispiel: group_dining
  • atmospherestringoptionalAtmosphere 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). · Beispiel: quiet
  • parkingbooleanoptionalOnly venues with confirmed parking. If nothing matches, this filter is dropped and listed in meta.relaxedFilters. Use parking_type for the kind of parking. · Beispiel: true
  • parking_typestringoptionalKind of parking: onsite, valet, partner (a partner lot), nearby, none. Korean words work too (발렛 → valet). · Beispiel: onsite
  • reservablebooleanoptionalOnly 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. · Beispiel: true
  • payment_methodsstringoptionalPayment 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. · Beispiel: alipay
  • servesstringoptionalWhat 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. · Beispiel: alcohol
  • dietarystringoptionalDietary 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. · Beispiel: vegan_options
  • foreign_languagesstringoptionalLanguages 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). · Beispiel: en
  • subtypestringoptionalVenue 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. · Beispiel: korean_bbq
  • bbq_meatstringoptionalMeat 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). · Beispiel: pork
  • viewstringoptionalView 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. · Beispiel: ocean
  • max_dish_priceintegeroptionalOnly 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. · Beispiel: 10000
  • foreigner_friendlybooleanoptionalVenues 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. · Beispiel: true
  • legacybooleanoptionalOfficially 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. · Beispiel: true
  • local_foodstringoptionalVenues 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. · Beispiel: 부산
  • excludestringoptionalLeaves 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. · Beispiel: 돼지국밥
  • muslim_friendlybooleanoptionalVenues 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. · Beispiel: true
  • featured_bystringoptionalOnly 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. · Beispiel: 성시경
  • associated_withstringoptionalOnly 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. · Beispiel: BTS
  • pet_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. · Beispiel: true
  • open_atstringoptionalOnly 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. · Beispiel: 2026-08-26T19:00
  • include_unknown_hoursbooleanoptionalOnly 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. · Beispiel: true
  • reservation_channelstringoptionalHow 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. · Beispiel: yumi
  • fieldsstringoptionalFields 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. · Beispiel: core,reviewCount,accessHints
  • pageintegeroptionalPage (default 1) · Beispiel: 1
  • page_sizeintegeroptionalResults 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. · Beispiel: 20

Antwortbeispiel

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",
      "distanceM": 0
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "center": {
      "lat": 37.5704,
      "lng": 126.9921
    },
    "radius": 500
  }
}
GET/api/v1/places/{id}

Place detail

Get one venue. Request only the tiers you need with fields; fields=all returns hours, menu, access hints, occasions, photos, and more, and costs 8 tokens (media tier). yumiBooking, influencerFeatures, legacy, and culturalAssociations are included whenever they apply, whatever fields you choose. A merged venue returns 404 place_merged with mergedInto, the id to use instead. Closed or hidden venues return 404.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

  • idstringerforderlichVenue id (the id field from search results). · Beispiel: 11782345
  • fieldsstringoptionalFields 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. · Beispiel: core,reviewCount,accessHints

Antwortbeispiel

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",
    "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)"
          }
        ]
      }
    ]
  }
}
GET/api/v1/places/{id}/history

Place history

Daily snapshots, recorded only on days when the review count, latest review date, or number of sources changed. Updated nightly (KST), newest first, up to 365 rows. A gap between two dates means nothing changed in between. Use it to judge whether a venue is getting more or less active. Star ratings aren't provided, so rating is always null. Costs 1 token.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

  • idstringerforderlichVenue id (the id field from search results). · Beispiel: 11782345

Antwortbeispiel

json

{
  "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."
  }
}
GET/api/v1/regions

Regions and place-name lookup

Turns a place name into region codes and coordinates, for when you don't have GPS. Dong names repeat (Hongje-dong exists in Seoul Seodaemun-gu and in Gangwon Gangneung), so each candidate comes with its sido, sigungu, venue count, and a center point. Pass the chosen center to /places/nearby to cover neighboring dongs too. Commercial areas and landmarks (명동, 강남, 코엑스), and stations when no dong matches, return one candidate with an empty regionCode plus kind and radiusM; search those with /places/nearby using center and radiusM. Romanized names (Gangnam) work, and machine translation is reported in meta.nameTranslated. Without dong you get every region that has venues, narrowed by sigungu or sido when given. Costs 1 token.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

  • dongstringoptionalPlace name to resolve: a dong (홍제동), a commercial area or landmark (명동, 코엑스), or a station. Returns candidates. · Beispiel: 홍제동
  • sigungustringoptionalSigungu (e.g. 서대문구). Narrows dong candidates, or lists the regions in that sigungu when sent without dong.
  • sidostringoptionalSido (e.g. 서울특별시). Narrows dong candidates, or lists the regions in that sido when sent without dong.
  • region_codestringoptionalLook up a single region code
  • include_emptybooleanoptionalAlso list regions with no venues yet (default false). Applies to the full list; a dong or region_code lookup returns matches either way.

Antwortbeispiel

json

{
  "success": true,
  "data": [
    {
      "regionCode": "1141011100",
      "sido": "서울특별시",
      "sigungu": "서대문구",
      "dong": "홍제동",
      "fullName": "서울특별시 서대문구 홍제동",
      "center": {
        "lat": 37.577976,
        "lng": 126.938483
      },
      "placeCount": 280
    }
  ]
}
GET/api/v1/categories

Categories

Venue counts per business type. Fitness types appear only where Yumi Partners exist, and their count is null. Cached for 10 minutes. Costs 1 token.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

Keine Parameter

Antwortbeispiel

json

{
  "success": true,
  "data": [
    {
      "category": "restaurant",
      "count": 354029
    }
  ]
}
GET/api/v1/stats

Dataset stats

Dataset totals: venues, regions, venues confirmed by more than one source (multiSourcePlaces), average confidence, and counts by business type. Refreshed every 30 minutes; updatedAt shows when. Fitness types are not included. Costs 1 token.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

Keine Parameter

Antwortbeispiel

json

{
  "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
      }
    ]
  }
}
GET/api/v1/meta

Filter & field vocabulary

No API key needed and no tokens used; cached for 1 hour. Returns the supported filters and their values, natural-language aliases, sort options per endpoint, field tiers, and supported regions. It is the reference list for filter vocabulary, and the MCP server and this reference read it to stay in sync.

Kein Schlüssel nötig · kostet keine Tokens

Im Playground ausführen →

Parameter

Keine Parameter

Antwortbeispiel

json

{
  "success": true,
  "data": {
    "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",
        "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"
      ],
      "enum": {
        "parking_type": [
          "onsite",
          "valet",
          "partner",
          "nearby",
          "none"
        ]
      },
      "subtype": [
        "korean",
        "korean_bbq",
        "gukbap_soup",
        "noodles",
        "chinese",
        "japanese",
        "sushi_sashimi",
        "italian",
        "seafood",
        "coffee",
        "dessert",
        "bakery",
        "brunch",
        "traditional_tea",
        "cocktail_bar",
        "wine_bar",
        "izakaya",
        "pocha",
        "hof_beer"
      ],
      "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 확대 중). 그 밖 지역(대구·광주·강원 등)은 결과가 비면 '아직 미지원'으로 안내."
    }
  },
  "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"
      ]
    }
  }
}
POST/api/v1/reservations

Request a reservation

Request a table at a venue that takes requests (yumiBooking.canRequest=true in place detail: Yumi Partners and most other venues). No prepayment. Each call costs 1 token. The request goes straight to the venue and starts as status='pending'. The owner accepting makes it confirmed, declining makes it cancelled, and no answer in about 5 minutes makes it expired. Poll GET /api/v1/reservations/{id} for the result. The guest gets progress by KakaoTalk or SMS, or by email for non-Korean numbers. Non-partner venues (yumiBooking.partner=false) take requests only during their request hours (yumiBooking.requestHours, e.g. 16:30-20:00 KST: from 30 minutes before the venue opens that day, never before 10:00, until 20:00). Outside them you get 422 reservation_requests_closed with retryAfter (the next start) and requestHoursKst. Send deferIfClosed:true to have the request held instead: the venue reviews it from reviewStartsAt, the reservation time must be at least 1 hour after that (otherwise you get reservation_requests_closed with earliestReservation), and the guest gets the result by text or email. Other 422 errors: venue_closed_at_requested_time means the venue isn't open then, so try another time. reservation_too_close_to_closing means the time is less than 2 hours before closing; latestReservation is the latest time accepted. walk_in_only_day means the venue only takes walk-ins that weekday (yumiBooking.walkInOnlyDays), so try another day. venue_day_off means the venue is closed today. For a non-partner venue this also covers closed days before it next takes requests; the request isn't held even with deferIfClosed, and retryAfter (and yumiBooking.requestsResumeAt) says when to send it again. For a partner venue it applies to every requested date, with closedToday:true and no retryAfter; ask the guest to send it on a day the venue is open (yumiBooking.closedToday shows this ahead of time). booking_details_required means a beauty or fitness venue needs the service and details in note; askBefore and required in the error say what to ask. reservation_not_available means the venue can't take requests through HeyYumi, so don't retry. If it comes with depositRequired:true, the venue needs a deposit paid in advance, which HeyYumi doesn't handle yet (place detail shows depositRequired:true ahead of time); tell the user that reason. Resending with the same idempotencyKey returns the original reservation instead of creating a new one. 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.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

Keine Parameter

Anfrage-Body (JSON)

  • placeIdstringerforderlichVenue id. Find it with a search first. The example is a Yumi Partner venue. · Beispiel: 1726507251
  • reservationTimestringerforderlichRequested date and time in ISO 8601 with a timezone offset; Korea is +09:00. A time in the past returns 400 reservation_time_past. · Beispiel: 2026-12-01T19:00:00+09:00
  • guestCountintegererforderlichParty size (at least 1). · Beispiel: 2
  • guestPhonestringerforderlichGuest phone number (required). Used for status texts (KakaoTalk or SMS) and for the venue to reach the guest about a no-show. Missing → 400 guest_phone_required. · Beispiel: 010-1234-5678
  • guestNamestringoptionalGuest name (recommended) so the owner knows who's coming. · Beispiel: 홍길동
  • guestEmailstringoptionalGuest email. Required when the phone isn't a Korean number: we can't text international numbers, so status updates and the view/cancel link go by email. Missing → 400 guest_email_required. · Beispiel: guest@example.com
  • guestLanguagestringoptionalLanguage 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. · Beispiel: en
  • notestringoptionalNote to the owner: seating, occasion, allergies, and so on. Required for beauty and fitness venues: say which service or class and any details, or the request fails with 422 booking_details_required. yumiBooking.askBefore in place detail lists what to ask.
  • idempotencyKeystringerforderlichA stable key, such as a UUID, for safely retrying the same request. Sending the same key again returns the original reservation instead of creating a new one. Required on REST; the MCP request_reservation tool and the playground create one for you. Even with a different key, an identical request (same venue, time, party size, guest, and note) within 2 minutes returns the existing reservation.
  • deferIfClosedbooleanoptionalIf true, a request to a non-partner venue outside its request hours (yumiBooking.requestHours: from 30 minutes before it opens that day, never before 10:00, until 20:00 KST) is held, and the venue reviews it from reviewStartsAt in the response. The reservation time must be at least 1 hour after reviewStartsAt, or you get 422 reservation_requests_closed with earliestReservation. You don't need to poll while it waits; the guest is told the result by text or email. Without it, you get 422 reservation_requests_closed. Partner venues take requests at any time, so it has no effect there. · Beispiel: true
  • sandboxOutcomestringoptionalSandbox only. The outcome to simulate: confirmed (default), cancelled, or expired (after 5 minutes). Ignored in live mode. · Beispiel: confirmed

Antwortbeispiel

json

{
  "success": true,
  "data": {
    "reservationId": "b1f2c3d4-0000-0000-0000-000000000000",
    "status": "pending",
    "placeId": "1726507251",
    "expiresAt": "2026-12-01T10:05:00.000Z"
  }
}
GET/api/v1/reservations/{id}

Reservation status (long-poll)

Get a reservation's current status: pending, confirmed, cancelled (declined), expired (no answer in time), or no_show. Pass ?wait=<seconds> (max 25) to long-poll; the call returns as soon as the reservation settles. If it is still pending, call again until settled=true, for about 5 minutes in total. Each call costs 1 token. On a decline, declineReason may carry the venue's message; on approval, venueNote may. Pass them on to the user. Sandbox ids (sbx_r_…) work the same way.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

  • idstringerforderlichThe reservationId returned by the create call. · Beispiel: b1f2c3d4-0000-0000-0000-000000000000
  • waitintegeroptionalSeconds to wait for a final status, 0-25; larger values are capped at 25. Omit it to get the current status right away. · Beispiel: 25

Antwortbeispiel

json

{
  "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"
  }
}
POST/api/v1/live-status

Live status (ask the venue right now)

Ask the venue a question that changes through the day and that map, review, or listing data can't answer: is a menu item available or sold out today (kind=item), how long is the wait right now (kind=wait), or can a party of N sit down right now (kind=seats; put the party size in topic). Each call costs 1 token. The venue needs an owner on the Yumi Partners app; otherwise you get 422 live_status_not_available. The owner gets a push and the response starts as status='pending' with a 5-minute answer window. The owner answers with one tap: available, limited, unavailable, soon, or not_offered. Poll GET /api/v1/live-status/{queryId} for the result. Some questions are answered at once from what Yumi reads on the store's POS or delivery-app screen; those have verifiedBy='screen' and a verifiedByNote. If a still-valid answer exists for the same venue and topic, it comes back right away (reused=true), and an identical pending question is joined instead of sending another push. Owner pushes are capped at 40 per venue per day (KST); past that the question is still created but no push goes out (pushSuppressed=true). If the venue's confirmed hours show it closed now, nothing is sent and you get blocked='closed_now' at once; don't retry, tell the user the hours. Venues with unknown hours are still asked. Don't use this for fixed facts like hours, parking, or pets; answer those from search. With the `X-Map3-Sandbox: 1` header, the venue check and opening-hours check run for real, nothing goes 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.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

Keine Parameter

Anfrage-Body (JSON)

  • placeIdstringerforderlichVenue id. Find it with a search first. The example is a Yumi Partner venue. · Beispiel: 1726507251
  • kindstringoptionalQuestion type: item (a menu item or stock), wait (the current queue), or seats (sitting down right now; put the party size in topic). Defaults to item if omitted. · Beispiel: item
  • topicstringerforderlichThe subject as a short phrase, not a sentence, e.g. '두바이 쫀득 쿠키', 'yellowtail', 'wait', 'party of 10'. For item, use the venue's own menu name. Answers are reused by venue and topic, so send the same topic for the same question. · Beispiel: 두바이 쫀득 쿠키
  • questionstringoptionalThe guest's own words (optional), shown to the owner for context. · Beispiel: 지금 두바이 쫀득 쿠키 있어요?
  • sandboxOutcomestringoptionalSandbox only. The answer to simulate: available, limited, unavailable, soon, not_offered, or no_response (after 5 minutes). Omit it for a default answer for the kind. Ignored in live mode.

Antwortbeispiel

json

{
  "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"
  }
}
GET/api/v1/live-status/{queryId}

Live status result (long-poll)

Get a live question's current status: pending, available (yes, in stock), limited (some left, or a short wait), unavailable (no, sold out), soon, not_offered (not on the menu), or no_response (no answer within 5 minutes). Pass ?wait=<seconds> (max 25) to long-poll; the call returns as soon as the question settles. If it is still pending, call again until settled=true, for about 5 minutes in total. Each call costs 1 token. Then tell the guest the answer and when it was checked. note may carry the owner's extra words (e.g. wait '20분', 'we can seat you separately'). verifiedAt is when the answer was given. verifiedBy is merchant (the owner answered) or screen (read from the store's screen; see verifiedByNote). validUntil is how long the answer is reused for other guests: an owner answer lasts 30 minutes for item, 10 for wait, and 15 for seats; a screen answer lasts 15, 5, and 5.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

  • queryIdstringerforderlichThe queryId returned by the create call. · Beispiel: c2e4f6a8-0000-0000-0000-000000000000
  • waitintegeroptionalSeconds to wait for a final status, 0-25; larger values are capped at 25. Omit it to get the current status right away. · Beispiel: 25

Antwortbeispiel

json

{
  "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"
  }
}
GET/api/v1/live-status

Fresh live answer (optional)

Returns a still-valid answer for placeId and topic without asking anyone (found:true with status, note, verifiedAt, verifiedBy, validUntil). If there isn't one, you get found:false; then POST to ask. POST already reuses fresh answers, so you usually need only POST. Use this to check for a fresh answer without sending anything. Costs 1 token.

Authentifizierung nötig (Header Bearer oder X-API-Key)

Im Playground ausführen →

Parameter

  • placeIdstringerforderlichVenue id. · Beispiel: 11782345
  • topicstringerforderlichThe subject token (same as POST's topic). · Beispiel: 두바이 쫀득 쿠키

Antwortbeispiel

json

{
  "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
  }
}