Connect

API reference

v1 public endpoints. All read-only (GET); every endpoint except /meta requires a Bearer key.

GET/api/v1/places

Search places

Search refined places (the oneset) by keyword, region, category, and confidence. Sorted by review count and confidence, paginated. Use fields to shape the response.

Auth required (Bearer / X-API-Key header preferred)

Run in playground →

Parameters

keywordstringoptionalPartial match on name/address · example: 버거킹
region_codestringoptionalRegion (admin-dong) code
business_categorystringoptionalCategory (restaurant/cafe…) · example: restaurant
min_confidencenumberoptionalMinimum confidence (0-1) · example: 0.6
recommended_forstringoptionalNarrow by occasion (comma, all must match). Natural language resolves too. Values: solo_dining, date, group_dining, family, business_meeting, formal_gathering, late_night… Full list & aliases at /api/v1/meta. · example: group_dining
atmospherestringoptionalAtmosphere (comma). quiet, lively, view, cozy, trendy, spacious, traditional, clean, work_study, rainy_mood. · example: quiet
parkingbooleanoptionalOnly places with confirmed parking. See parking_type for the kind. · example: true
parking_typestringoptionalParking type: onsite, valet, partner, nearby, none. Natural language (e.g. 발렛→valet) resolves. · example: onsite
reservablebooleanoptionalOnly reservable places (crawl-confirmed plus Yumi Partner venues). · example: true
payment_methodsstringoptionalRequire payment methods (comma, all must match). cash, card, naver_pay, kakao_pay, toss_pay, alipay, wechat_pay… · example: alipay
servesstringoptionalServes (comma). coffee, alcohol, dessert, vegetarian, vegan. · example: alcohol
dietarystringoptionalDietary (comma). vegan_options, vegetarian_options, fully_vegan, mixed_group_suitable. · example: vegan_options
pet_friendlybooleanoptionalExample boolean presence filter. Attach the param to require =true (only confirmed places). Full list (wifi, private_room, outdoor_seating, group_friendly, takeout, delivery, corkage_free, has_promotion…) at /api/v1/meta filters.boolean. · example: true
fieldsstringoptionalPick fields (Field Mask). Comma-separated tier names (core/contact_hours/quality/edge/media), 'all', or individual field names. Defaults to core. Call tokens = the highest field tier requested (per-request; page_size does not affect tokens). Owner-uploaded photos come via photos (media tier, highest cost 8 — venue & menu image URLs); in lists use photoCount (quality) for a cheap count. recommendedFor may include occasion tags such as solo_dining, late_night, and late_night_eatery. · example: core,rating,accessHints
pageintegeroptionalPage (default 1) · example: 1
page_sizeintegeroptionalItems per page (max 100). Does not affect tokens (per-request billing). Live API keys can access up to a 5,000-result window; beyond that use Bulk Export. · example: 20

Response example

json

{
  "success": true,
  "data": [
    {
      "id": "11892345",
      "name": "콩부자 홍제점",
      "category": "restaurant",
      "categoryLabel": "국밥",
      "location": {
        "lat": 37.5891,
        "lng": 126.9436
      },
      "address": {
        "road": "서울 서대문구 통일로 450",
        "jibun": "서울 서대문구 홍제동 330"
      },
      "regionCode": "1141011100",
      "confidence": 0.64,
      "sourceCount": 2,
      "lastSeenAt": "2026-06-18T03:00:00.000Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1
  }
}

GET/api/v1/places/nearby

Nearby search

Find places around a coordinate (lat·lng) within a radius (m), nearest first. Each result includes distanceM (meters from center). fields/tokens behave like Search places.

Auth required (Bearer / X-API-Key header preferred)

Run in playground →

Parameters

latnumberrequiredLatitude · example: 37.5704
lngnumberrequiredLongitude · example: 126.9921
radiusintegeroptionalRadius in meters (default 1000, max 5000) · example: 500
business_categorystringoptionalCategory filter · example: cafe
keywordstringoptionalPartial match on name/address
recommended_forstringoptionalNarrow by occasion (comma, all must match). Natural language resolves too. Values: solo_dining, date, group_dining, family, business_meeting, formal_gathering, late_night… Full list & aliases at /api/v1/meta. · example: group_dining
atmospherestringoptionalAtmosphere (comma). quiet, lively, view, cozy, trendy, spacious, traditional, clean, work_study, rainy_mood. · example: quiet
parkingbooleanoptionalOnly places with confirmed parking. See parking_type for the kind. · example: true
parking_typestringoptionalParking type: onsite, valet, partner, nearby, none. Natural language (e.g. 발렛→valet) resolves. · example: onsite
reservablebooleanoptionalOnly reservable places (crawl-confirmed plus Yumi Partner venues). · example: true
payment_methodsstringoptionalRequire payment methods (comma, all must match). cash, card, naver_pay, kakao_pay, toss_pay, alipay, wechat_pay… · example: alipay
servesstringoptionalServes (comma). coffee, alcohol, dessert, vegetarian, vegan. · example: alcohol
dietarystringoptionalDietary (comma). vegan_options, vegetarian_options, fully_vegan, mixed_group_suitable. · example: vegan_options
pet_friendlybooleanoptionalExample boolean presence filter. Attach the param to require =true (only confirmed places). Full list (wifi, private_room, outdoor_seating, group_friendly, takeout, delivery, corkage_free, has_promotion…) at /api/v1/meta filters.boolean. · example: true
fieldsstringoptionalPick fields (Field Mask). Comma-separated tier names (core/contact_hours/quality/edge/media), 'all', or individual field names. Defaults to core. Call tokens = the highest field tier requested (per-request; page_size does not affect tokens). Owner-uploaded photos come via photos (media tier, highest cost 8 — venue & menu image URLs); in lists use photoCount (quality) for a cheap count. recommendedFor may include occasion tags such as solo_dining, late_night, and late_night_eatery. · example: core,rating,accessHints
pageintegeroptionalPage (default 1) · example: 1
page_sizeintegeroptionalItems per page (max 100). Does not affect tokens (per-request billing). Live API keys can access up to a 5,000-result window; beyond that use Bulk Export. · example: 20

Response example

json

{
  "success": true,
  "data": [
    {
      "id": "11892345",
      "name": "콩부자 홍제점",
      "category": "restaurant",
      "categoryLabel": "국밥",
      "location": {
        "lat": 37.5891,
        "lng": 126.9436
      },
      "address": {
        "road": "서울 서대문구 통일로 450",
        "jibun": "서울 서대문구 홍제동 330"
      },
      "regionCode": "1141011100",
      "confidence": 0.64,
      "sourceCount": 2,
      "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}

Place detail

A single place. Use fields to fetch only the tiers you need (fields=all returns hours, menu, access hints, recommendation context, and more).

Auth required (Bearer / X-API-Key header preferred)

Run in playground →

Parameters

idstringrequiredPlace id (canonical) · example: 11782345
fieldsstringoptionalPick fields (Field Mask). Comma-separated tier names (core/contact_hours/quality/edge/media), 'all', or individual field names. Defaults to core. Call tokens = the highest field tier requested (per-request; page_size does not affect tokens). Owner-uploaded photos come via photos (media tier, highest cost 8 — venue & menu image URLs); in lists use photoCount (quality) for a cheap count. recommendedFor may include occasion tags such as solo_dining, late_night, and late_night_eatery. · example: core,rating,accessHints

Response example

json

{
  "success": true,
  "data": {
    "id": "11892345",
    "name": "콩부자 홍제점",
    "category": "restaurant",
    "categoryLabel": "국밥",
    "location": {
      "lat": 37.5891,
      "lng": 126.9436
    },
    "address": {
      "road": "서울 서대문구 통일로 450",
      "jibun": "서울 서대문구 홍제동 330"
    },
    "regionCode": "1141011100",
    "confidence": 0.64,
    "sourceCount": 2,
    "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

Place history

Daily rating and activity-freshness (freshnessScore) trend (accumulated snapshots). A signal you can use to judge changes in a place's activity yourself.

Auth required (Bearer / X-API-Key header preferred)

Run in playground →

Parameters

idstringrequiredPlace id (canonical) · example: 11782345

Response example

json

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

GET/api/v1/regions

Regions · resolve dong name

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.

Auth required (Bearer / X-API-Key header preferred)

Run in playground →

Parameters

dongstringoptionalDong name (e.g. 홍제동) — returns candidates · example: 홍제동
sigungustringoptionalNarrow by sigungu (e.g. 서대문구)
sidostringoptionalNarrow by sido (e.g. 서울특별시)
region_codestringoptionalLook up a single region code
include_emptybooleanoptionalInclude regions with no places yet (default false)

Response example

json

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

GET/api/v1/categories

Dataset stats

Total places, regions, multi-source share, average confidence, category breakdown.

Auth required (Bearer / X-API-Key header preferred)

Run in playground →

Parameters

No parameters

Response example

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

Filter & field vocabulary

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.

Key-free · no billing

Run in playground →

Parameters

No parameters

Response example

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

API reference

Search places

Nearby search

Place detail

Place history

Regions · resolve dong name

Categories

Dataset stats

Filter & field vocabulary