AMC Entertainment Holdings Showtimes API

openapi: 3.2.0
info:
  title: AMC Theatres Showtimes API
  description: 'The AMC Theatres API is a public REST API published by AMC Entertainment Holdings

    that exposes data and transactional capabilities for AMC theatres, movies, showtimes,

    locations, loyalty, concessions, orders, refunds, media, and webhooks.'
  version: v2
  contact:
    name: AMC Theatres Developer Portal
    url: https://developers.amctheatres.com
  termsOfService: https://www.amctheatres.com/legal/terms-of-use
  license:
    name: AMC Theatres API Terms of Use
    url: https://www.amctheatres.com/legal/terms-of-use
servers:
- url: https://api.amctheatres.com
  description: AMC Theatres production API
security:
- VendorKey: []
tags:
- name: Showtimes
  description: Theatre showtimes for movies, including embargoed and proximity-based searches.
paths:
  /v2/theatres/{theatre-number}/showtimes:
    get:
      summary: List Showtimes for a Theatre
      description: Returns all future showtimes for the specified theatre.
      operationId: listTheatreShowtimes
      tags:
      - Showtimes
      parameters:
      - $ref: '#/components/parameters/TheatreNumber'
      - name: movie-id
        in: query
        schema:
          type: integer
        description: Filter to showtimes for a specific movie id.
      - $ref: '#/components/parameters/IncludeAttributes'
      - $ref: '#/components/parameters/ExcludeAttributes'
      - $ref: '#/components/parameters/AttributeOperator'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Showtimes collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowtimeCollection'
  /v2/theatres/{theatre-number}/showtimes/{date}:
    get:
      summary: List Showtimes for a Theatre on a Date
      description: Returns all showtimes for the specified theatre on the specified date that meet the supplied search criteria.
      operationId: listTheatreShowtimesByDate
      tags:
      - Showtimes
      parameters:
      - $ref: '#/components/parameters/TheatreNumber'
      - name: date
        in: path
        required: true
        schema:
          type: string
          format: date
        description: Date in ISO-8601 (YYYY-MM-DD) format.
      - $ref: '#/components/parameters/IncludeAttributes'
      - $ref: '#/components/parameters/ExcludeAttributes'
      - $ref: '#/components/parameters/AttributeOperator'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Showtimes collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowtimeCollection'
  /v2/theatres/{theatre-number}/showtimes/{date}/views/embargoed:
    get:
      summary: List Embargoed Showtimes for a Theatre on a Date
      description: Returns all embargoed showtimes for the specified theatre and date.
      operationId: listEmbargoedShowtimes
      tags:
      - Showtimes
      parameters:
      - $ref: '#/components/parameters/TheatreNumber'
      - name: date
        in: path
        required: true
        schema:
          type: string
          format: date
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Embargoed showtimes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowtimeCollection'
  /v2/theatres/{theatre-number}/movies/{movie-id}/earliest-showtime:
    get:
      summary: Get Earliest Showtime For Movie at Theatre
      description: Returns the earliest showtime for a specific movie id at the specified theatre.
      operationId: getEarliestShowtime
      tags:
      - Showtimes
      parameters:
      - $ref: '#/components/parameters/TheatreNumber'
      - name: movie-id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Showtime representation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Showtime'
  /v2/showtimes/{id}:
    get:
      summary: Get Showtime By Id
      description: Returns the showtime with the specified id.
      operationId: getShowtime
      tags:
      - Showtimes
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Showtime representation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Showtime'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/showtimes/views/current-location/{date}/{latitude}/{longitude}:
    get:
      summary: List Showtimes Near a Location
      description: Returns all showtimes in proximity to the supplied latitude and longitude on the specified date.
      operationId: listShowtimesByLocation
      tags:
      - Showtimes
      parameters:
      - name: date
        in: path
        required: true
        schema:
          type: string
          format: date
      - name: latitude
        in: path
        required: true
        schema:
          type: number
          format: double
      - name: longitude
        in: path
        required: true
        schema:
          type: number
          format: double
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Showtimes near the location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowtimeCollection'
components:
  parameters:
    PageNumber:
      name: page-number
      in: query
      description: Page number to retrieve. Defaults to 1.
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSize:
      name: page-size
      in: query
      description: Results per page (max 100). Defaults to 10.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    IncludeAttributes:
      name: include-attributes
      in: query
      description: Comma-delimited list of attributes that results must have.
      schema:
        type: string
    TheatreNumber:
      name: theatre-number
      in: path
      required: true
      description: The theatre number / id.
      schema:
        type: integer
    AttributeOperator:
      name: attribute-operator
      in: query
      description: Whether the include/exclude attribute filter is `and` (all) or `or` (any).
      schema:
        type: string
        enum:
        - and
        - or
    ExcludeAttributes:
      name: exclude-attributes
      in: query
      description: Comma-delimited list of attributes that results must not have.
      schema:
        type: string
  schemas:
    Attribute:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string
        name:
          type: string
        shortDescription:
          type: string
        longDescription:
          type: string
        url:
          type: string
          format: uri
        sort:
          type: integer
        appliesToMovie:
          type: boolean
        appliesToShowtime:
          type: boolean
        appliesToTheatre:
          type: boolean
        media:
          type: object
        _links:
          $ref: '#/components/schemas/HalLinks'
    ShowtimeCollection:
      allOf:
      - $ref: '#/components/schemas/PagedCollection'
      - type: object
        properties:
          _embedded:
            type: object
            properties:
              showtimes:
                type: array
                items:
                  $ref: '#/components/schemas/Showtime'
    HalLinks:
      type: object
      additionalProperties:
        type: object
        properties:
          href:
            type: string
          templated:
            type: boolean
    PagedCollection:
      type: object
      properties:
        pageSize:
          type: integer
        pageNumber:
          type: integer
        count:
          type: integer
        _links:
          $ref: '#/components/schemas/HalLinks'
    TicketPrice:
      type: object
      properties:
        priceType:
          type: string
        sku:
          type: string
        price:
          type: number
          format: double
        tax:
          type: number
          format: double
        formattedPrice:
          type: string
        formattedTax:
          type: string
    Showtime:
      type: object
      properties:
        id:
          type: integer
        movieId:
          type: integer
        movieName:
          type: string
        showDateTimeUtc:
          type: string
          format: date-time
        showDateTimeLocal:
          type: string
          format: date-time
        utcOffset:
          type: string
        theatreId:
          type: integer
        auditorium:
          type: integer
        layoutId:
          type: integer
        wamc:
          type: string
        sortableMovieName:
          type: string
        movieSlug:
          type: string
        runTime:
          type: integer
        mpaaRating:
          type: string
        genre:
          type: string
        purchaseUrl:
          type: string
          format: uri
        mobilePurchaseUrl:
          type: string
          format: uri
        ticketPrices:
          type: array
          items:
            $ref: '#/components/schemas/TicketPrice'
        utcSession:
          type: string
        isAlmostSoldOut:
          type: boolean
        isSoldOut:
          type: boolean
        isCanceled:
          type: boolean
        isPrivateRental:
          type: boolean
        isDiscountMatineePriced:
          type: boolean
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        media:
          type: object
        _links:
          $ref: '#/components/schemas/HalLinks'
    ApiError:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        errorCode:
          type: string
        moreInfo:
          type: string
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    VendorKey:
      type: apiKey
      in: header
      name: X-AMC-Vendor-Key
      description: AMC vendor API key issued via the AMC Theatres developer portal.
externalDocs:
  description: AMC Theatres Developer Portal
  url: https://developers.amctheatres.com