GET
/api/v1/places매장 검색
키워드·지역·카테고리·신뢰도로 정제된 매장(원셋)을 검색합니다. 기본 정렬은 discovery(질의 적합·최신성·교차검증·완성도를 함께 보는 추천 정렬)이며 페이지네이션됩니다. fields로 받을 필드를 고르세요.
인증 필요 (Bearer / X-API-Key 헤더 권장)
체험존에서 실행 →파라미터
keywordstring선택상호·주소·메뉴명 부분검색. 영문 상호(Starbucks)와 외국어 요리명(bibimbap·ビビンバ·拌饭)도 그대로 넣으면 찾고, 요리명을 한글로 바꿨으면 meta.keywordTranslated로 알려줍니다. · 예시:버거킹region_codestring선택행정동 코드business_categorystring선택업종(restaurant/cafe/bar, 그리고 유미 제휴 비식당 salon/gym/esthetic/nail). 비식당은 승인된 제휴 매장만 나오고, 업종 없는 맛집 검색엔 섞이지 않습니다. 값 목록은 GET /api/v1/meta의 filters.businessCategory · 예시:restaurantmin_confidencenumber선택최소 신뢰도(0~1) · 예시:0.6sortstring선택discovery(기본·유일) — 추천 정렬. 좌표가 없어 distance는 쓸 수 없습니다. 응답 meta.sort는 '실제로 적용된' 정렬이라 넓은 검색에서는 reviews로 낮아질 수 있습니다. · 예시:discoveryrecommended_forstring선택상황으로 좁히기(콤마, 모두 포함). 자연어도 해석됨: 회식→group_dining, 혼밥→solo_dining, 상견례→formal_gathering. 값: solo_dining·date·group_dining·family·business_meeting·formal_gathering·late_night 등. 전체·별칭은 /api/v1/meta. · 예시:group_diningatmospherestring선택분위기(콤마). quiet·lively·view·cozy·trendy·spacious·traditional·clean·work_study·rainy_mood. 조용한→quiet 같은 자연어도 해석. · 예시:quietparkingboolean선택주차 확인된 곳만. 세부 유형은 parking_type. · 예시:trueparking_typestring선택주차 유형: onsite·valet·partner·nearby·none. 발렛→valet 등 자연어 해석. · 예시:onsitereservableboolean선택예약 가능한 곳만(크롤 확인 + 유미 파트너 매장 포함). · 예시:truepayment_methodsstring선택결제수단 모두 포함(콤마). cash·card·naver_pay·kakao_pay·toss_pay·zero_pay·alipay·wechat_pay·unionpay·apple_pay·samsung_pay 등. apple_pay·samsung_pay·unionpay는 사장님 확인값. 애플페이는 '해외카드 될 가능성' 신호로만 쓰고 단정하지 않는다. · 예시:alipayservesstring선택제공 품목(콤마). coffee·alcohol·dessert·vegetarian·vegan. · 예시:alcoholdietarystring선택식단(콤마). vegan_options·vegetarian_options·fully_vegan·mixed_group_suitable·vegetarian_mixed_group_suitable·gluten_free. 자연어도 해석(비건/vegan/plant-based→vegan_options, 채식/vegetarian→vegetarian_options, 혼합식단/mixed→mixed_group_suitable, 글루텐프리/gf→gluten_free). '비건 친구랑 같이 먹을 곳'은 mixed_group_suitable(비건 '식사'가 확인된 곳만, 음료뿐인 카페 제외). gluten_free는 사장님 확인값만 쓰고, 지역에 확인 매장이 10곳 미만이면 결과를 채우지 않고 meta.dietaryCoverage로 '아직 확인 부족'을 알린다. · 예시:vegan_optionsforeign_languagesstring선택외국어 응대 가능 언어(ISO 639-1, 콤마·모두 포함). en·zh·ja·es·de·fr. 사장님이 확인한 값. '영어→en, 일본어→ja' 같은 자연어도 해석. 예: 외국인 손님용 '영어 되는 곳'. · 예시:ensubtypestring선택정규화 세부업종(콤마=OR, 40+종). 음식점 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 등. 삼겹살→korean_bbq, 국밥→gukbap_soup 같은 자연어도 해석. '업종 종류' 의도는 broad business_category보다 subtype 우선. 전체는 /api/v1/meta. · 예시:korean_bbqbbq_meatstring선택고깃집(korean_bbq)이 파는 고기 종류(콤마=OR): pork·beef·duck·lamb. subtype과 독립축 — subtype=korean_bbq가 업종을, bbq_meat=pork가 그 안의 고기를 좁힌다. 삼겹살→pork, 한우→beef 자연어 해석. 혼합집(삼겹+한우)은 양쪽에 다 잡힌다. · 예시:porkviewstring선택전망 종류(콤마=OR): ocean·sunset·river·mountain·night·city·garden. 한 매장이 바다뷰+노을뷰면 둘 다 잡힌다. 바다뷰→ocean, 한강뷰→river, 야경→night 자연어 해석. 근거 없으면 미부착(부재=모름). · 예시:oceanmax_dish_priceinteger선택메뉴 하나가 이 값(원) 이하인 곳만. '1만원 이하 식사'는 max_dish_price=10000. 곁들임(공깃밥·사리·추가)을 뺀 가장 싼 실제 메뉴로 판정하고, 가격을 모르는 매장은 포함하지 않습니다. 가격 숫자 없이 '가성비 좋은 곳'만 원하면 good_value=true. · 예시:10000foreigner_friendlyboolean선택한국어를 몰라도 되는 곳. 영어(외국어) 메뉴판이 있거나 외국어 응대가 확인된 매장(둘 중 하나). 메뉴판만 보려면 english_menu=true, 특정 언어 응대는 foreign_languages. · 예시:truelegacyboolean선택공식 노포만. 백년가게·서울 오래가게·서울미래유산으로 지정된 매장. '노포 추천'은 keyword=노포 대신 이걸 쓰세요(상호·주소 문자열 오탐 방지). · 예시:truelocal_foodstring선택그 지역 향토음식을 상호나 대표메뉴로 미는 곳만(부산=돼지국밥·밀면 등). 값은 지역명(local_food=부산)이나 시도코드, 또는 region_code와 함께 true. 전국 17개 시도. · 예시:부산excludestring선택'~말고/빼고'. 그 음식이 상호나 대표메뉴인 전문점을 뺍니다(콤마=전부 제외). 곁다리 메뉴로만 파는 곳은 빼지 않습니다. · 예시:돼지국밥muslim_friendlyboolean선택무슬림 손님을 받는다고 알려진 곳(상호·메뉴의 할랄 표기 또는 사장님 확인). 공식 할랄 인증이 아닙니다. 응답 meta에 '인증·돼지고기 없는 주방·주류는 매장에 확인' 안내가 함께 실립니다. · 예시:truefeatured_bystring선택서면 동의한 앰버서더(인플루언서)가 소개한 매장만. 이름·핸들·채널명 부분일치. 맞는 사람이 없으면 0건과 함께 meta.featuredBy로 지금 등록된 사람들을 알려줍니다. · 예시:성시경associated_withstring선택연예인·그룹·드라마 같은 작품과 연결됐다고 공개 보도된 매장만('BTS가 간 곳', '도깨비 촬영지'). 맞는 대상이 없으면 0건과 함께 meta.associatedWith로 지금 있는 대상을 알려줍니다. · 예시:BTSpet_friendlyboolean선택그 밖의 boolean presence 필터의 예. 파라미터만 붙이면 =true(있다고 확인된 곳만). 지금 지원하는 boolean 54개: 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. 특수 필터(muslim_friendly·legacy(백년가게)·local_food·exclude·featured_by·associated_with)는 /api/v1/meta. · 예시:trueopen_atstring선택그 시각(또는 그 시간대)에 영업하는 곳만(한국시간). 한 시각: 2026-08-26T19:00 · '2026-08-26 19:00' · '19:00'(오늘) · 'now'. 식사 시간대: 'lunch'·'점심'(11:00~14:00) · 'dinner'·'저녁'(17:30~21:00) · breakfast · brunch · late_night, 직접 범위 '11:00-14:00', 날짜와 조합 '2026-08-29 lunch'. 상대 날짜는 오늘·내일·모레(today/tomorrow)만 해석합니다(그 밖은 절대 날짜로 보내세요). 시간대는 그 구간에 **일부라도** 영업하면 통과하며 응답 meta.openAt.window로 해석한 범위를 돌려줍니다. 정기 영업시간·라스트오더·브레이크타임 기준이며 자정 넘김 영업도 처리합니다. 임시휴무·만석은 알 수 없습니다. 영업시간이 확인되지 않은 매장은 기본 제외되고 meta.openAt.unknownHoursExcluded로 알립니다. · 예시:2026-08-26T19:00include_unknown_hoursboolean선택open_at 전용 탈출구. true면 영업시간이 확인되지 않은 매장도 함께 반환합니다(그 매장은 '그 시각에 영업한다'가 아니라 '모름'입니다). · 예시:truereservation_channelstring선택예약 경로(콤마 = OR): yumi(유미 API로 바로 예약 — POST /api/v1/reservations) · phone(전화). '예약을 받는다'와 '그 시각에 자리가 있다'는 다른 문제입니다 — 실제 좌석 가능 여부는 예약 요청으로만 확인됩니다. · 예시:yumifieldsstring선택받을 필드 선택(Field Mask). 콤마 구분 · 등급명(core/contact_hours/quality/edge/media)·all·개별 필드명. 미지정 시 core. 호출 토큰 = 요청 필드 중 최고 등급(요청당 과금, page_size 무관). 사장님 업로드 사진은 photos(media, 최상위 단가 8 — 매장·메뉴 이미지 URL)로 받고, 목록에선 photoCount(quality)로 개수만 싸게 볼 수 있습니다. recommendedFor에는 solo_dining, late_night, late_night_eatery 같은 상황 태그가 포함될 수 있습니다. · 예시:core,reviewCount,accessHintspageinteger선택페이지(기본 1) · 예시:1page_sizeinteger선택페이지당 개수(최대 100). 토큰에 영향 없음(요청당 과금). 일반 API는 플랜별 결과창(무료 100 · Starter 1,000 · Pro·Scale 5,000)까지만 접근하며, 그 이상은 Bulk Export. · 예시:20
응답 예시
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
}
}