연동하기

API 레퍼런스

v1 공개 엔드포인트. 모두 읽기전용(GET)이고, /meta를 뺀 나머지는 Bearer 키 인증이 필요해.

OpenAPI →

GET/api/v1/places

매장 검색

키워드·지역·카테고리·신뢰도로 정제된 매장(원셋)을 검색합니다. 리뷰수·신뢰도 순 정렬, 페이지네이션. fields로 받을 필드를 고르세요.

인증 필요 (Bearer / X-API-Key 헤더 권장)

체험존에서 실행 →

파라미터

keywordstring선택상호·주소 부분검색 · 예시: 버거킹
region_codestring선택행정동 코드
business_categorystring선택카테고리(restaurant/cafe…) · 예시: restaurant
min_confidencenumber선택최소 신뢰도(0~1) · 예시: 0.6
recommended_forstring선택상황으로 좁히기(콤마, 모두 포함). 자연어도 해석됨: 회식→group_dining, 혼밥→solo_dining, 상견례→formal_gathering. 값: solo_dining·date·group_dining·family·business_meeting·formal_gathering·late_night 등. 전체·별칭은 /api/v1/meta. · 예시: group_dining
atmospherestring선택분위기(콤마). quiet·lively·view·cozy·trendy·spacious·traditional·clean·work_study·rainy_mood. 조용한→quiet 같은 자연어도 해석. · 예시: quiet
parkingboolean선택주차 확인된 곳만. 세부 유형은 parking_type. · 예시: true
parking_typestring선택주차 유형: onsite·valet·partner·nearby·none. 발렛→valet 등 자연어 해석. · 예시: onsite
reservableboolean선택예약 가능한 곳만(크롤 확인 + 유미 파트너 매장 포함). · 예시: true
payment_methodsstring선택결제수단 모두 포함(콤마). cash·card·naver_pay·kakao_pay·toss_pay·zero_pay·alipay·wechat_pay 등. · 예시: alipay
servesstring선택제공 품목(콤마). coffee·alcohol·dessert·vegetarian·vegan. · 예시: alcohol
dietarystring선택식단(콤마). vegan_options·vegetarian_options·fully_vegan·mixed_group_suitable. · 예시: vegan_options
pet_friendlyboolean선택그 밖의 boolean presence 필터의 예. 파라미터만 붙이면 =true(있다고 확인된 곳만). 지원 목록 전체(wifi·private_room·outdoor_seating·group_friendly·takeout·delivery·corkage_free·has_promotion 등)는 /api/v1/meta의 filters.boolean. · 예시: true
fieldsstring선택받을 필드 선택(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,rating,accessHints
pageinteger선택페이지(기본 1) · 예시: 1
page_sizeinteger선택페이지당 개수(최대 100). 토큰에 영향 없음(요청당 과금). 일반 API는 최대 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,
      "lastSeenAt": "2026-06-18T03:00:00.000Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1
  }
}

GET/api/v1/places/nearby

주변 검색

좌표(lat·lng)와 반경(m)으로 주변 매장을 가까운 순으로 찾습니다. 각 결과에 distanceM(중심으로부터 거리)이 붙습니다. fields/토큰은 매장 검색과 동일.

인증 필요 (Bearer / X-API-Key 헤더 권장)

체험존에서 실행 →

파라미터

latnumber필수위도 · 예시: 37.5704
lngnumber필수경도 · 예시: 126.9921
radiusinteger선택반경 m(기본 1000, 최대 5000) · 예시: 500
business_categorystring선택카테고리 필터 · 예시: cafe
keywordstring선택상호·주소 부분검색
recommended_forstring선택상황으로 좁히기(콤마, 모두 포함). 자연어도 해석됨: 회식→group_dining, 혼밥→solo_dining, 상견례→formal_gathering. 값: solo_dining·date·group_dining·family·business_meeting·formal_gathering·late_night 등. 전체·별칭은 /api/v1/meta. · 예시: group_dining
atmospherestring선택분위기(콤마). quiet·lively·view·cozy·trendy·spacious·traditional·clean·work_study·rainy_mood. 조용한→quiet 같은 자연어도 해석. · 예시: quiet
parkingboolean선택주차 확인된 곳만. 세부 유형은 parking_type. · 예시: true
parking_typestring선택주차 유형: onsite·valet·partner·nearby·none. 발렛→valet 등 자연어 해석. · 예시: onsite
reservableboolean선택예약 가능한 곳만(크롤 확인 + 유미 파트너 매장 포함). · 예시: true
payment_methodsstring선택결제수단 모두 포함(콤마). cash·card·naver_pay·kakao_pay·toss_pay·zero_pay·alipay·wechat_pay 등. · 예시: alipay
servesstring선택제공 품목(콤마). coffee·alcohol·dessert·vegetarian·vegan. · 예시: alcohol
dietarystring선택식단(콤마). vegan_options·vegetarian_options·fully_vegan·mixed_group_suitable. · 예시: vegan_options
pet_friendlyboolean선택그 밖의 boolean presence 필터의 예. 파라미터만 붙이면 =true(있다고 확인된 곳만). 지원 목록 전체(wifi·private_room·outdoor_seating·group_friendly·takeout·delivery·corkage_free·has_promotion 등)는 /api/v1/meta의 filters.boolean. · 예시: true
fieldsstring선택받을 필드 선택(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,rating,accessHints
pageinteger선택페이지(기본 1) · 예시: 1
page_sizeinteger선택페이지당 개수(최대 100). 토큰에 영향 없음(요청당 과금). 일반 API는 최대 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,
      "lastSeenAt": "2026-06-18T03:00:00.000Z",
      "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}

매장 상세

단일 매장. fields로 필요한 등급만 받으세요(fields=all 시 영업시간·메뉴·접근성·추천맥락까지 전부).

인증 필요 (Bearer / X-API-Key 헤더 권장)

체험존에서 실행 →

파라미터

idstring필수매장 ID(canonical) · 예시: 11782345
fieldsstring선택받을 필드 선택(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,rating,accessHints

응답 예시

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,
    "lastSeenAt": "2026-06-18T03:00:00.000Z",
    "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
    },
    "menu": [
      {
        "name": "콩나물국밥",
        "price": 8000,
        "recommend": true
      }
    ],
    "openNow": {
      "open": true,
      "reason": "open",
      "lastOrderPassed": false
    },
    "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"
        }
      ]
    },
    "phone": "02-123-4567",
    "homepage": null,
    "bookingUrl": null,
    "snsLinks": null,
    "businessHours": [
      {
        "day": "mon",
        "closed": false,
        "open": "00:00",
        "close": "24:00",
        "endsNextDay": false,
        "breaks": [],
        "lastOrder": null
      }
    ],
    "is24h": true,
    "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": [
      "캐주얼",
      "빠른"
    ],
    "cautions": [
      "unkind_service"
    ],
    "serviceAttributes": {
      "parking": true,
      "parking_type": "onsite",
      "parking_fee": "paid",
      "parking_note": "매장 주차 가능(유료)",
      "dine_in": true,
      "reservable": true,
      "dietary": {
        "fully_vegan": false,
        "vegan_options": true,
        "vegetarian_options": true,
        "mixed_group_suitable": true,
        "vegan_menu_count": 3,
        "non_vegan_menu_count": 8,
        "confidence": 0.62,
        "note": "비건 메뉴와 일반 메뉴가 함께 있어 비건과 비(非)비건이 같이 가기 좋아요. 조리 분리는 확인이 필요해요."
      }
    },
    "atmosphereScores": {
      "late_night": 6,
      "late_night_eatery": 8,
      "quiet": 6.5,
      "lively": 4
    },
    "aiSummary": "홍제역 근처 캐주얼 국밥집, 혼밥·심야식당 수요에 적합."
  }
}

GET/api/v1/places/{id}/history

매장 시계열

일자별 평점·활동 최신성(freshnessScore) 추이(스냅샷 누적). 매장 활동량 변화를 직접 판단할 수 있는 재료입니다.

인증 필요 (Bearer / X-API-Key 헤더 권장)

체험존에서 실행 →

파라미터

idstring필수매장 ID(canonical) · 예시: 11782345

응답 예시

json

{
  "success": true,
  "data": [
    {
      "date": "2026-06-18",
      "reviewCount": 10731,
      "rating": null,
      "latestReviewDate": "2026-06-15",
      "freshnessScore": 0.82
    }
  ]
}

GET/api/v1/regions

지역 조회 · 동네 이름 해석

동네 이름을 코드·좌표로 풀어줍니다(좌표가 없을 때의 위치 해석). 동 이름은 유일하지 않아(예: 홍제동=서울 서대문구 + 강원 강릉) 후보 목록을 시도/시군구로 구분해 매장수·대표좌표(center)와 함께 돌려줍니다. 고른 후보의 center로 /places/nearby 반경검색을 돌리면 인접 동네까지 커버됩니다. dong 없이 호출하면 매장 보유 지역 전체.

인증 필요 (Bearer / X-API-Key 헤더 권장)

체험존에서 실행 →

파라미터

dongstring선택동네 이름(예: 홍제동) — 후보들을 반환 · 예시: 홍제동
sigungustring선택시군구로 후보 좁히기(예: 서대문구)
sidostring선택시도로 후보 좁히기(예: 서울특별시)
region_codestring선택특정 지역코드 단건 조회
include_emptyboolean선택매장 0인 미수집 지역도 포함(기본 false)

응답 예시

json

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

GET/api/v1/categories

카테고리 목록

원셋 보유 카테고리별 매장 수.

인증 필요 (Bearer / X-API-Key 헤더 권장)

체험존에서 실행 →

파라미터

파라미터 없음

응답 예시

json

{
  "success": true,
  "data": [
    {
      "category": "restaurant",
      "count": 82140
    }
  ]
}

GET/api/v1/stats

데이터 통계

전체 매장 수·지역 수·멀티소스 비율·평균 신뢰도·카테고리 분포.

인증 필요 (Bearer / X-API-Key 헤더 권장)

체험존에서 실행 →

파라미터

파라미터 없음

응답 예시

json

{
  "success": true,
  "data": {
    "totalPlaces": 143027,
    "totalRegions": 512,
    "multiSourcePlaces": 70118,
    "avgConfidence": 0.72,
    "byCategory": [
      {
        "category": "restaurant",
        "count": 82140
      },
      {
        "category": "cafe",
        "count": 51730
      },
      {
        "category": "bar",
        "count": 9157
      }
    ]
  }
}

GET/api/v1/meta

필터·필드 어휘

키 없이 호출(과금 없음, 1시간 캐시). 지원하는 속성 필터·값·자연어 별칭(aliases)과 필드 등급을 그대로 돌려줍니다. 필터 어휘의 단일 진실원천이라, MCP·SDK가 이걸 읽어 자동 동기화합니다.

키 없이 호출 · 과금 없음

체험존에서 실행 →

파라미터

파라미터 없음

응답 예시

json

{
  "version": 1,
  "filters": {
    "boolean": [
      "wifi",
      "parking",
      "outdoor_seating",
      "pet_friendly",
      "group_friendly",
      "kids_friendly",
      "reservable",
      "takeout",
      "delivery",
      "dine_in",
      "catering",
      "corkage_free",
      "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"
    ],
    "enum": {
      "parking_type": [
        "onsite",
        "valet",
        "partner",
        "nearby",
        "none"
      ]
    },
    "array": {
      "payment_methods": [
        "cash",
        "card",
        "toss_pay",
        "kakao_pay",
        "naver_pay",
        "zero_pay",
        "local_gift",
        "gov_support",
        "alipay",
        "wechat_pay"
      ],
      "serves": [
        "coffee",
        "alcohol",
        "dessert",
        "vegetarian",
        "vegan"
      ],
      "dietary": [
        "vegan_options",
        "vegetarian_options",
        "fully_vegan",
        "mixed_group_suitable"
      ],
      "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"
      }
    }
  },
  "fields": {
    "tiers": {
      "core": 1,
      "contact_hours": 2,
      "quality": 2,
      "edge": 4,
      "media": 8
    },
    "byField": {
      "name": "core",
      "rating": "quality",
      "serviceAttributes": "edge",
      "photos": "media"
    }
  }
}