openapi: 3.0.3
info:
  title: SeatGeek Platform Events Venues API
  description: The SeatGeek Platform API provides access to SeatGeek's comprehensive dataset of live events in the United States and Canada. Search events, performers, venues, taxonomies, and get personalized recommendations. The API supports JSON, JSONP, and XML response formats with pagination and geolocation filtering.
  version: '2'
  contact:
    url: https://seatgeek.com/build
  termsOfService: https://seatgeek.com/api-terms
servers:
- url: https://api.seatgeek.com/2
  description: SeatGeek Platform API v2
security:
- clientId: []
tags:
- name: Venues
paths:
  /venues:
    get:
      operationId: listVenues
      summary: List Venues
      description: Returns a paginated list of venues. Filter by city, state, country, postal code, geolocation, or text search.
      tags:
      - Venues
      parameters:
      - name: city
        in: query
        description: Filter by city name
        schema:
          type: string
      - name: state
        in: query
        description: Filter by US state abbreviation
        schema:
          type: string
      - name: country
        in: query
        description: Filter by country code
        schema:
          type: string
      - name: postal_code
        in: query
        description: Filter by postal code
        schema:
          type: string
      - name: q
        in: query
        description: Text search query
        schema:
          type: string
      - name: id
        in: query
        description: Venue ID (comma-separated for multiple)
        schema:
          type: string
      - name: geoip
        in: query
        schema:
          type: boolean
      - name: lat
        in: query
        schema:
          type: number
      - name: lon
        in: query
        schema:
          type: number
      - name: range
        in: query
        schema:
          type: string
      - name: per_page
        in: query
        schema:
          type: integer
          default: 10
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: sort
        in: query
        schema:
          type: string
      responses:
        '200':
          description: List of venues
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VenuesResponse'
  /venues/{venue_id}:
    get:
      operationId: getVenue
      summary: Get Venue
      description: Returns a single venue document with full details.
      tags:
      - Venues
      parameters:
      - name: venue_id
        in: path
        required: true
        description: SeatGeek venue ID
        schema:
          type: integer
      responses:
        '200':
          description: Venue details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Venue'
        '404':
          description: Venue not found
components:
  schemas:
    Venue:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postal_code:
          type: string
        location:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
        url:
          type: string
          format: uri
        score:
          type: number
        capacity:
          type: integer
        timezone:
          type: string
        has_upcoming_events:
          type: boolean
    Meta:
      type: object
      properties:
        total:
          type: integer
        took:
          type: number
          description: Query execution time in milliseconds
        page:
          type: integer
        per_page:
          type: integer
        geolocation:
          type: object
          nullable: true
    VenuesResponse:
      type: object
      properties:
        venues:
          type: array
          items:
            $ref: '#/components/schemas/Venue'
        meta:
          $ref: '#/components/schemas/Meta'
  securitySchemes:
    clientId:
      type: apiKey
      in: query
      name: client_id
      description: SeatGeek client ID obtained from the developer portal