openapi: 3.1.0
info:
  title: Daremeet Lieux city snapshot API
  version: 1.0.0
  description: |
    Crawlable JSON snapshot for a Lieux city: geo, POI (OSM), editorial challenge ideas, HowTo copy, nearby cities.
    Pretty URL (rewrite): `/lieux/{country}/{region}/{city}.json`
    API: `/api/lieux-place?country=&region=&city=&snapshot=1&locale=fr`
servers:
  - url: https://www.daremeet.com
paths:
  /lieux/{country}/{region}/{city}.json:
    get:
      summary: City snapshot (crawlable alias)
      operationId: daremeetLieuxCitySnapshot
      tags: [lieux]
      parameters:
        - name: country
          in: path
          required: true
          schema: { type: string }
        - name: region
          in: path
          required: true
          schema: { type: string }
        - name: city
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Full city snapshot JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LieuxCitySnapshot'
        '404':
          description: City not found
  /api/lieux-place:
    get:
      summary: Lieux city metadata and snapshot
      operationId: daremeetLieuxPlaceApi
      tags: [lieux]
      parameters:
        - name: key
          in: query
          schema: { type: string }
          description: Canonical key `country/region/city`
        - name: country
          in: query
          schema: { type: string }
        - name: region
          in: query
          schema: { type: string }
        - name: city
          in: query
          schema: { type: string }
        - name: locale
          in: query
          schema: { type: string, default: fr }
        - name: snapshot
          in: query
          schema: { type: string, enum: ['1'] }
          description: Full snapshot (ideas, HowTo copy, nearby, POI)
        - name: items
          in: query
          schema: { type: string, enum: ['0', '1'] }
          description: Include POI list (default 1)
      responses:
        '200':
          description: Compact or full snapshot
components:
  schemas:
    LieuxCitySnapshot:
      type: object
      required: [schema_version, key, locale, city_name, geo, urls, challenge_ideas, poi, nearby_cities, live_challenges]
      properties:
        schema_version: { type: string, example: '1.0.0' }
        key: { type: string, example: france/ile-de-france/paris }
        locale: { type: string }
        city_name: { type: string }
        geo:
          type: object
          properties:
            lat: { type: number }
            lng: { type: number }
        urls:
          type: object
          properties:
            snapshot: { type: string, format: uri }
            lieux_city_page: { type: string, format: uri }
            go_map: { type: string, format: uri, nullable: true }
        challenge_ideas:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              key: { type: string }
              name: { type: string }
              howto_schema_id: { type: string }
        poi:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              category: { type: string, enum: [eat, park, culture] }
              lat: { type: number }
              lng: { type: number }
        live_challenges:
          type: array
          description: Reserved for public live challenges (empty until Supabase RPC wired)
          items: { type: object }
