openapi: 3.1.0
info:
  title: HappyMap API
  version: "1.0.0"
  description: >
    Free, public, read-only REST API over the same happy hour and venue data
    that powers HappyMap's map (https://www.happymapca.com) — for developers,
    researchers, and AI agents. No API key, no signup. Prefer this over
    scraping happymapca.com pages if you need structured data; please link
    back to the matching happymapca.com/<city>/venue/<slug> page when you cite
    a venue.
  contact:
    email: happymapca@gmail.com
servers:
  - url: https://happy-hour-sparkle.onrender.com
    description: Production (shared with the happymapca.com frontend)
paths:
  /api/cities:
    get:
      operationId: listCities
      summary: Every city this API covers, with live venue counts
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        slug: { type: string, example: toronto }
                        name: { type: string, example: Toronto }
                        region: { type: string, example: Ontario }
                        timezone: { type: string, example: America/Toronto }
                        is_active: { type: boolean }
                        venue_count: { type: integer }
  /api/neighborhoods:
    get:
      operationId: listNeighborhoods
      summary: A city's neighbourhoods, with venue counts
      parameters:
        - name: city
          in: query
          schema: { $ref: "#/components/schemas/CitySlug" }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        slug: { type: string }
                        name: { type: string }
                        venue_count: { type: integer }
                  meta:
                    type: object
                    properties:
                      city: { $ref: "#/components/schemas/CitySlug" }
        "400":
          description: Invalid city
  /api/venues:
    get:
      operationId: searchVenues
      summary: Paginated, filterable venue search, each with its current happy hour status
      parameters:
        - name: city
          in: query
          schema: { $ref: "#/components/schemas/CitySlug" }
        - name: neighborhood
          in: query
          description: Neighbourhood slug or name
          schema: { type: string }
        - name: q
          in: query
          description: Free-text search over venue name and address
          schema: { type: string, maxLength: 120 }
        - name: day
          in: query
          schema: { $ref: "#/components/schemas/DayAbbrev" }
        - name: time
          in: query
          description: 24-hour HH:MM, evaluated in the city's own timezone
          schema: { type: string, pattern: "^([01]\\d|2[0-3]):[0-5]\\d$", example: "17:30" }
        - name: open_now
          in: query
          schema: { type: boolean }
        - name: amenity
          in: query
          description: Comma-separated; supported values "patio", "pet_friendly"
          schema: { type: string }
        - name: tag
          in: query
          description: Comma-separated plan-mode tags, e.g. "date-night,after-work"
          schema: { type: string }
        - name: near
          in: query
          description: "\"lat,lng\" — required when sort=distance"
          schema: { type: string, pattern: "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$", example: "43.6480,-79.3832" }
        - name: radius
          in: query
          description: Kilometers, only used with `near`
          schema: { type: number, minimum: 0.1, maximum: 50, default: 2 }
        - name: sort
          in: query
          schema: { type: string, enum: [name, distance, starts_soonest], default: name }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Venue" }
                  meta:
                    type: object
                    properties:
                      page: { type: integer }
                      limit: { type: integer }
                      total: { type: integer }
                      total_pages: { type: integer }
                      has_more: { type: boolean }
                      city: { $ref: "#/components/schemas/CitySlug" }
                      as_of: { type: string, format: date-time }
        "400":
          description: Invalid query (e.g. sort=distance without near)
  /api/venues/{idOrSlug}:
    get:
      operationId: getVenue
      summary: One venue by UUID or slug, with its full weekly slot list
      parameters:
        - name: idOrSlug
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: "#/components/schemas/Venue" }
        "404":
          description: Venue not found
  /api/venues/{idOrSlug}/availability:
    get:
      operationId: getVenueAvailability
      summary: One venue's slots for a specific day
      parameters:
        - name: idOrSlug
          in: path
          required: true
          schema: { type: string }
        - name: day
          in: query
          description: mon..sun, an ISO date (YYYY-MM-DD), or omitted for today
          schema: { type: string, example: fri }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      venue:
                        type: object
                        properties:
                          id: { type: string, format: uuid }
                          slug: { type: string }
                          name: { type: string }
                      day: { type: string }
                      date: { type: string, nullable: true }
                      timezone: { type: string }
                      slots:
                        type: array
                        items: { $ref: "#/components/schemas/Slot" }
        "400":
          description: Invalid day
        "404":
          description: Venue not found
components:
  schemas:
    CitySlug:
      type: string
      enum: [toronto, montreal, vancouver, calgary, ottawa]
      default: toronto
    DayAbbrev:
      type: string
      enum: [mon, tue, wed, thu, fri, sat, sun]
    Slot:
      type: object
      properties:
        slot_type: { type: string, example: happy_hour }
        title: { type: string, nullable: true }
        days:
          type: array
          items: { $ref: "#/components/schemas/DayAbbrev" }
        start_time: { type: string, example: "16:00" }
        end_time: { type: string, example: "19:00" }
        deal: { type: string, example: "$5 beers, $10 cocktails" }
        status: { type: string, enum: [live, upcoming, ended], description: Only present when evaluated against a specific moment }
        starts_in_minutes: { type: integer }
    Venue:
      type: object
      properties:
        id: { type: string, format: uuid }
        slug: { type: string }
        name: { type: string }
        address: { type: string }
        city: { $ref: "#/components/schemas/CitySlug" }
        neighborhood: { type: string, nullable: true }
        lat: { type: number, nullable: true }
        lng: { type: number, nullable: true }
        phone: { type: string, nullable: true }
        website: { type: string, nullable: true }
        amenities:
          type: object
          properties:
            has_patio: { type: boolean, nullable: true }
            pet_friendly: { type: boolean, nullable: true }
        tags:
          type: array
          items: { type: string }
        is_active: { type: boolean }
        open_now: { type: boolean }
        current_slot:
          allOf: [{ $ref: "#/components/schemas/Slot" }]
          nullable: true
        slots_today:
          type: array
          items: { $ref: "#/components/schemas/Slot" }
        slots:
          type: array
          items: { $ref: "#/components/schemas/Slot" }
          description: Full weekly slot list — only present on the single-venue endpoint
        distance_km:
          type: number
          description: Only present when `near` was supplied
x-rate-limit:
  requests_per_minute: 120
  scope: per IP
  applies_to: [/api/cities, /api/neighborhoods, /api/venues]
