openapi: 3.1.0
info:
  title: Thai Take-away Schweiz API
  description: >
    API for the largest open directory of Thai restaurants with take-away
    in Switzerland and Liechtenstein. 499 restaurants across 25 cantons + Liechtenstein,
    available in 4 languages (DE, EN, FR, IT).
  version: 1.0.0
  contact:
    email: hello@thai-take-away.com
    url: https://thai-take-away.com
  license:
    name: Attribution Required
    url: https://thai-take-away.com/ai.txt

servers:
  - url: https://thai-take-away.com
    description: Production

paths:
  /api/pageviews:
    get:
      operationId: getPageviews
      summary: Get total page view count
      description: Returns the cumulative page view counter stored in Cloudflare KV. Bot requests are counted but not incremented.
      responses:
        "200":
          description: Current page view count
          content:
            application/json:
              schema:
                type: object
                properties:
                  views:
                    type: integer
                    example: 12450
                required:
                  - views
        "503":
          description: KV storage unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  views:
                    type: "null"
                  error:
                    type: string
                    example: KV unavailable

  /api/search:
    get:
      operationId: searchRestaurants
      summary: Search Thai restaurants by name or location
      description: >
        Full-text search across all 499 restaurant names and municipalities.
        Returns matching restaurants with name, address, take-away status, and detail page URL.
      parameters:
        - name: q
          in: query
          required: true
          description: Search query (matched against restaurant name and municipality)
          schema:
            type: string
            example: Pad Thai
        - name: lang
          in: query
          required: false
          description: Language for detail page URLs (de, en, fr, it). Defaults to de.
          schema:
            type: string
            enum: [de, en, fr, it]
            default: de
        - name: canton
          in: query
          required: false
          description: Filter by canton slug (e.g. zurich, bern, basel)
          schema:
            type: string
            example: zurich
        - name: limit
          in: query
          required: false
          description: Maximum number of results (1–50). Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"

  /api/nearby:
    get:
      operationId: findNearbyRestaurants
      summary: Find Thai restaurants near a GPS location
      description: >
        Returns restaurants within a given radius of a GPS coordinate,
        sorted by distance (nearest first). Uses Haversine formula for distance calculation.
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude (WGS84)
          schema:
            type: number
            format: double
            example: 47.3769
        - name: lon
          in: query
          required: true
          description: Longitude (WGS84)
          schema:
            type: number
            format: double
            example: 8.5417
        - name: radius
          in: query
          required: false
          description: Search radius in kilometers. Defaults to 5.
          schema:
            type: number
            default: 5
            minimum: 0.5
            maximum: 50
        - name: lang
          in: query
          required: false
          description: Language for detail page URLs (de, en, fr, it). Defaults to de.
          schema:
            type: string
            enum: [de, en, fr, it]
            default: de
        - name: limit
          in: query
          required: false
          description: Maximum number of results (1–50). Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      responses:
        "200":
          description: Nearby restaurants sorted by distance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NearbyResponse"

  /go/{slug}:
    get:
      operationId: redirectToRestaurant
      summary: Redirect to a restaurant's external website
      description: >
        Resolves a restaurant slug to its external website URL and returns a 302 redirect.
        Over 400 restaurants have mapped external URLs.
      parameters:
        - name: slug
          in: path
          required: true
          description: URL-friendly restaurant identifier (e.g. tab-tim-thai-ii, pad-thai-dietikon)
          schema:
            type: string
            example: tab-tim-thai-ii
      responses:
        "302":
          description: Redirect to the restaurant's external website
          headers:
            Location:
              schema:
                type: string
                format: uri
        "404":
          description: Unknown slug

  /llms.txt:
    get:
      operationId: getLlmsSummary
      summary: AI-readable site summary
      description: >
        Markdown file with structured information about the directory for AI assistants.
        Contains URL structure, data schema, canton statistics, and usage examples.
      responses:
        "200":
          description: Markdown summary
          content:
            text/markdown:
              schema:
                type: string

  /llms-full.txt:
    get:
      operationId: getLlmsFullData
      summary: Complete restaurant inventory for AI systems
      description: >
        Full listing of all 499 restaurants with name, address, municipality,
        take-away status, and detail page URL path. Pipe-separated format.
      responses:
        "200":
          description: Complete restaurant directory in Markdown format
          content:
            text/markdown:
              schema:
                type: string

  /ai.txt:
    get:
      operationId: getAiPolicy
      summary: AI usage policy
      description: >
        Machine-readable usage guidelines for AI systems. Defines allowed
        and disallowed uses, attribution requirements, and data source links.
      responses:
        "200":
          description: AI usage policy
          content:
            text/plain:
              schema:
                type: string

components:
  schemas:
    Restaurant:
      type: object
      properties:
        name:
          type: string
          example: Tab Tim Thai II
        slug:
          type: string
          example: tab-tim-thai-ii
        address:
          type: string
          example: "Münstergasse 57, 3011 Bern"
        municipality:
          type: string
          example: Bern
        canton:
          type: string
          example: bern
        takeaway:
          type: string
          enum: [confirmed, unconfirmed]
          example: confirmed
        url:
          type: string
          format: uri
          example: https://thai-take-away.com/de/ch/bern/tab-tim-thai-ii.html
        latitude:
          type: number
          format: double
          example: 46.954559
        longitude:
          type: number
          format: double
          example: 7.420685
      required:
        - name
        - slug
        - address
        - municipality
        - canton
        - takeaway
        - url

    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/Restaurant"
        total:
          type: integer
          example: 3
        query:
          type: string
          example: Pad Thai
      required:
        - results
        - total
        - query

    NearbyResponse:
      type: object
      properties:
        results:
          type: array
          items:
            allOf:
              - $ref: "#/components/schemas/Restaurant"
              - type: object
                properties:
                  distance_km:
                    type: number
                    format: double
                    description: Distance from the query point in kilometers
                    example: 1.23
        total:
          type: integer
          example: 5
        center:
          type: object
          properties:
            lat:
              type: number
              format: double
            lon:
              type: number
              format: double
        radius_km:
          type: number
          example: 5
      required:
        - results
        - total
        - center
        - radius_km
