Heyyumi AI Regions API

openapi: 3.2.0
info:
  title: HeyYumi Regions API
  version: 1.0.0
  description: 'Refined food & drink venue data (the ''oneset''): identity, location, standardized hours, menu, price band, review count, freshness, confidence, plus reservation endpoints so AI can find, recommend, and book. One curator''s notebook, served as an API.


    ## Field Mask & tiered billing

    Use the `fields` query param (comma-separated) to choose what you receive. Tokens can be tier names, `all`, or individual field names. Unknown tokens are ignored and reported via the `X-Map3-Ignored-Fields` response header. When `fields` is omitted, the default is `core`.


    ## Authentication

    Use `Authorization: Bearer ` or the `X-API-Key` header. Do not put API keys in URLs. `?api_key=` is deprecated and scheduled for removal (it will be rejected with `401 query_auth_disabled`) because URLs are commonly stored in browser, proxy, server, and error logs.


    Billing is per request: each call is billed at the highest field tier you request (returned in the `X-Map3-Units` header). `page_size` does not change tokens.

    - `core` (= 1 token/request): id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt, placeUrl

    - `contact_hours` (= 2 tokens/request): phone, homepage, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h

    - `quality` (= 2 tokens/request): reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation

    - `edge` (= 4 tokens/request): accessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, ownerStory, influencerFeatures, culturalAssociations, legacy, reputation

    - `media` (= 8 tokens/request): photos


    Abuse is controlled by limits, not price: per-key rate limit (requests/min) and a token cap by plan (daily on the free tier, monthly on paid plans; 429 with `Retry-After`), and a result window for the live API (100 results on the free tier, 1,000 on Starter, 5,000 on Pro and Scale). Larger or full-dataset extraction requires Bulk Export / data licensing, not paginated API calls (see Acceptable Use in the Terms).'
  contact:
    name: heyyumi
    url: https://heyyumi.ai
servers:
- url: https://api.heyyumi.ai
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Regions
paths:
  /api/v1/regions:
    get:
      operationId: list-regions
      summary: Regions · resolve dong name
      description: Resolves a dong (neighborhood) name into codes & coordinates (location lookup when you have no GPS). Dong names are not unique (e.g. Hongje-dong = Seoul Seodaemun-gu + Gangwon Gangneung), so candidates are returned disambiguated by sido/sigungu, with place counts and a representative center. Feed a chosen center into /places/nearby to also cover adjacent dongs. Without dong, lists all regions that have places.
      parameters:
      - name: dong
        in: query
        required: false
        description: Dong name (e.g. 홍제동) — returns candidates
        schema:
          type: string
        example: 홍제동
      - name: sigungu
        in: query
        required: false
        description: Narrow by sigungu (e.g. 서대문구)
        schema:
          type: string
      - name: sido
        in: query
        required: false
        description: Narrow by sido (e.g. 서울특별시)
        schema:
          type: string
      - name: region_code
        in: query
        required: false
        description: Look up a single region code
        schema:
          type: string
      - name: include_empty
        in: query
        required: false
        description: Include regions with no places yet (default false)
        schema:
          type: boolean
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      responses:
        '200':
          description: OK
          headers:
            X-Map3-Units:
              description: Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).
              schema:
                type: integer
            X-Map3-Ignored-Fields:
              description: Comma-separated unknown field tokens that were ignored (present only when some were dropped).
              schema:
                type: string
          content:
            application/json:
              example:
                success: true
                data:
                - regionCode: '1141011100'
                  sido: 서울특별시
                  sigungu: 서대문구
                  dong: 홍제동
                  fullName: 서울특별시 서대문구 홍제동
                  center:
                    lat: 37.577976
                    lng: 126.938483
                  placeCount: 280
        '400':
          description: Invalid parameters / bulk_export_required (result window too large)
        '401':
          description: API key required or invalid
        '429':
          description: Rate limit, daily quota, or monthly quota exceeded (see Retry-After)
      tags:
      - Regions
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Preferred: Authorization: Bearer <API_KEY>. Do not pass keys in URLs.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative header auth. Query-string api_key is deprecated.