Heyyumi AI Stats API

openapi: 3.2.0
info:
  title: HeyYumi Stats 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: Stats
paths:
  /api/v1/stats:
    get:
      operationId: stats
      summary: Dataset stats
      description: Total places, regions, multi-source share, average confidence, category breakdown.
      parameters: []
      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:
                  totalPlaces: 523685
                  totalRegions: 2453
                  multiSourcePlaces: 414650
                  avgConfidence: 0.869
                  byCategory:
                  - category: restaurant
                    count: 354029
                  - category: cafe
                    count: 134241
                  - category: bar
                    count: 35239
        '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:
      - Stats
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.