openapi: 3.0.3
info:
  title: ThemeParks.wiki Destinations Entities API
  description: An ever-growing database of real-time data for the world's best theme parks. Access live wait times, ride operational status, park schedules, and entity metadata for 75+ theme park destinations worldwide including Disney, Universal, Cedar Fair, Six Flags, and Merlin Entertainment parks. No authentication required.
  version: 1.0.0
  contact:
    url: https://themeparks.wiki/
  x-generated-from: documentation
servers:
- url: https://api.themeparks.wiki/v1
  description: Production API server
security: []
tags:
- name: Entities
  description: Park entities including rides, shows, restaurants, and parks
paths:
  /entity/{entityID}:
    get:
      operationId: getEntity
      summary: ThemeParks.wiki Get Entity Details
      description: Get the entity document for a specific park, ride, show, restaurant, or other entity. Returns metadata including name, type, coordinates, and parent entity relationships.
      tags:
      - Entities
      parameters:
      - name: entityID
        in: path
        description: Unique entity UUID identifier
        required: true
        schema:
          type: string
          format: uuid
          example: 75ea578a-adc8-4116-a54d-dccb60765ef9
      responses:
        '200':
          description: Entity details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
              examples:
                GetEntity200Example:
                  summary: Default getEntity 200 response
                  x-microcks-default: true
                  value:
                    id: 75ea578a-adc8-4116-a54d-dccb60765ef9
                    name: Magic Kingdom Park
                    entityType: PARK
                    slug: magickingdom
                    location:
                      latitude: 28.4177
                      longitude: -81.5812
        '404':
          description: Entity not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /entity/{entityID}/children:
    get:
      operationId: getEntityChildren
      summary: ThemeParks.wiki Get Entity Children
      description: Get all child entities for a given entity. For a destination, returns its parks. For a park, returns its attractions, shows, and restaurants.
      tags:
      - Entities
      parameters:
      - name: entityID
        in: path
        description: Unique entity UUID identifier
        required: true
        schema:
          type: string
          format: uuid
          example: 75ea578a-adc8-4116-a54d-dccb60765ef9
      responses:
        '200':
          description: List of child entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChildrenResponse'
              examples:
                GetEntityChildren200Example:
                  summary: Default getEntityChildren 200 response
                  x-microcks-default: true
                  value:
                    id: 75ea578a-adc8-4116-a54d-dccb60765ef9
                    name: Magic Kingdom Park
                    entityType: PARK
                    children:
                    - id: a8a5b7e4-1234-5678-abcd-ef0123456789
                      name: Space Mountain
                      entityType: ATTRACTION
                      externalId: spacemountain
        '404':
          description: Entity not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /entity/{entityID}/live:
    get:
      operationId: getEntityLiveData
      summary: ThemeParks.wiki Get Live Entity Data
      description: Get live data for a specific entity and all its child entities. Returns current wait times, queue lengths, operational status, return times for virtual queues, and showtimes.
      tags:
      - Entities
      parameters:
      - name: entityID
        in: path
        description: Unique entity UUID identifier
        required: true
        schema:
          type: string
          format: uuid
          example: 75ea578a-adc8-4116-a54d-dccb60765ef9
      responses:
        '200':
          description: Live wait times and status data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveDataResponse'
              examples:
                GetEntityLiveData200Example:
                  summary: Default getEntityLiveData 200 response
                  x-microcks-default: true
                  value:
                    id: 75ea578a-adc8-4116-a54d-dccb60765ef9
                    name: Magic Kingdom Park
                    entityType: PARK
                    liveData:
                    - entityId: a8a5b7e4-1234-5678-abcd-ef0123456789
                      name: Space Mountain
                      entityType: ATTRACTION
                      status: OPERATING
                      queue:
                        STANDBY:
                          waitTime: 45
                      lastUpdated: '2025-03-15T14:30:00Z'
        '404':
          description: Entity not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /entity/{entityID}/schedule:
    get:
      operationId: getEntitySchedule
      summary: ThemeParks.wiki Get Entity Schedule
      description: Get the operating schedule for a specific entity (typically a park). Returns upcoming park hours, special event hours, and holiday schedules.
      tags:
      - Entities
      parameters:
      - name: entityID
        in: path
        description: Unique entity UUID identifier
        required: true
        schema:
          type: string
          format: uuid
          example: 75ea578a-adc8-4116-a54d-dccb60765ef9
      responses:
        '200':
          description: Park operating schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
              examples:
                GetEntitySchedule200Example:
                  summary: Default getEntitySchedule 200 response
                  x-microcks-default: true
                  value:
                    id: 75ea578a-adc8-4116-a54d-dccb60765ef9
                    name: Magic Kingdom Park
                    entityType: PARK
                    schedule:
                    - date: '2025-03-15'
                      openingTime: '2025-03-15T09:00:00-05:00'
                      closingTime: '2025-03-15T23:00:00-05:00'
                      type: OPERATING
        '404':
          description: Entity not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /entity/{entityID}/schedule/{year}/{month}:
    get:
      operationId: getEntityScheduleByMonth
      summary: ThemeParks.wiki Get Entity Schedule for Specific Month
      description: Get the operating schedule for a specific entity for a specific month and year. Useful for trip planning and advance schedule lookups.
      tags:
      - Entities
      parameters:
      - name: entityID
        in: path
        description: Unique entity UUID identifier
        required: true
        schema:
          type: string
          format: uuid
          example: 75ea578a-adc8-4116-a54d-dccb60765ef9
      - name: year
        in: path
        description: Four-digit year
        required: true
        schema:
          type: integer
          example: 2025
      - name: month
        in: path
        description: Month number (1-12)
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 12
          example: 3
      responses:
        '200':
          description: Park operating schedule for the specified month
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
              examples:
                GetEntityScheduleByMonth200Example:
                  summary: Default getEntityScheduleByMonth 200 response
                  x-microcks-default: true
                  value:
                    id: 75ea578a-adc8-4116-a54d-dccb60765ef9
                    name: Magic Kingdom Park
                    schedule:
                    - date: '2025-03-01'
                      openingTime: '2025-03-01T09:00:00-05:00'
                      closingTime: '2025-03-01T23:00:00-05:00'
                      type: OPERATING
        '404':
          description: Entity not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Location:
      type: object
      description: Geographic coordinates
      properties:
        latitude:
          type: number
          description: Latitude
          example: 28.4177
        longitude:
          type: number
          description: Longitude
          example: -81.5812
    LiveEntityData:
      type: object
      description: Live operational data for a single entity
      properties:
        entityId:
          type: string
          description: Entity UUID
        name:
          type: string
          description: Entity name
        entityType:
          type: string
          description: Entity type
        status:
          type: string
          description: Current operational status
          enum:
          - OPERATING
          - DOWN
          - CLOSED
          - REFURBISHMENT
          example: OPERATING
        queue:
          type: object
          description: Queue data by queue type
          properties:
            STANDBY:
              $ref: '#/components/schemas/QueueData'
            SINGLE_RIDER:
              $ref: '#/components/schemas/QueueData'
            RETURN_TIME:
              type: object
              description: Lightning Lane / virtual queue return time
              properties:
                returnStart:
                  type: string
                  description: Return window start time
                returnEnd:
                  type: string
                  description: Return window end time
                state:
                  type: string
                  description: Return time availability state
        lastUpdated:
          type: string
          description: ISO 8601 timestamp of last data update
          example: '2025-03-15T14:30:00Z'
        showtimes:
          type: array
          description: Showtime data (for shows)
          nullable: true
          items:
            type: object
            properties:
              startTime:
                type: string
                description: Show start time
              endTime:
                type: string
                description: Show end time
                nullable: true
              type:
                type: string
                description: Show type
    ChildrenResponse:
      type: object
      description: Entity with its children
      properties:
        id:
          type: string
          description: Parent entity UUID
        name:
          type: string
          description: Parent entity name
        entityType:
          type: string
          description: Parent entity type
        children:
          type: array
          description: Child entities
          items:
            $ref: '#/components/schemas/Entity'
    ScheduleEntry:
      type: object
      description: A single schedule entry for a park operating day
      properties:
        date:
          type: string
          description: Date in YYYY-MM-DD format
          example: '2025-03-15'
        openingTime:
          type: string
          description: Park opening time as ISO 8601 datetime
          example: '2025-03-15T09:00:00-05:00'
        closingTime:
          type: string
          description: Park closing time as ISO 8601 datetime
          example: '2025-03-15T23:00:00-05:00'
        type:
          type: string
          description: Schedule entry type
          enum:
          - OPERATING
          - TICKETED_EVENT
          - PRIVATE_EVENT
          - EXTRA_HOURS
          example: OPERATING
        specialHours:
          type: boolean
          description: Whether this is special event hours
          nullable: true
    Entity:
      type: object
      description: Theme park entity (park, attraction, show, restaurant, or destination)
      properties:
        id:
          type: string
          description: Unique entity UUID
          example: 75ea578a-adc8-4116-a54d-dccb60765ef9
        name:
          type: string
          description: Entity name
          example: Space Mountain
        entityType:
          type: string
          description: Type of entity
          enum:
          - DESTINATION
          - PARK
          - ATTRACTION
          - SHOW
          - RESTAURANT
          example: ATTRACTION
        slug:
          type: string
          description: URL-friendly identifier
          nullable: true
        externalId:
          type: string
          description: External system reference ID
          nullable: true
        parentId:
          type: string
          description: Parent entity UUID
          nullable: true
        location:
          $ref: '#/components/schemas/Location'
    ScheduleResponse:
      type: object
      description: Schedule for an entity
      properties:
        id:
          type: string
          description: Entity UUID
        name:
          type: string
          description: Entity name
        entityType:
          type: string
          description: Entity type
        schedule:
          type: array
          description: Array of schedule entries
          items:
            $ref: '#/components/schemas/ScheduleEntry'
    QueueData:
      type: object
      description: Queue wait time data for an attraction
      properties:
        waitTime:
          type: integer
          description: Current wait time in minutes
          nullable: true
          example: 45
    LiveDataResponse:
      type: object
      description: Live data for an entity and all its children
      properties:
        id:
          type: string
          description: Entity UUID
        name:
          type: string
          description: Entity name
        entityType:
          type: string
          description: Entity type
        liveData:
          type: array
          description: Live data for child entities
          items:
            $ref: '#/components/schemas/LiveEntityData'