Gracenote Deprecated API

openapi: 3.2.0
info:
  title: Nexus API v1.1.5 Deprecated API
  description: This is the OpenAPI spec for Gracenote's Nexus API.
  contact:
    email: nexusengineering@nielsen.com
  version: v1.1.5
servers:
- url: /proxy/nexus/v1
tags:
- name: Deprecated
  description: API endpoints to be removed in a future release.
paths:
  /programbundles:
    get:
      tags:
      - Deprecated
      description: __Deprecated. Use the /collections endpoint with VIDEOPROGRAMS as the item type instead.__
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/languageParam'
      - $ref: '#/components/parameters/contentMarketParam'
      - $ref: '#/components/parameters/omitCatalogsParam'
      - $ref: '#/components/parameters/encodingParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramBundlesResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '429':
          $ref: '#/components/responses/errorResponse429'
        4XX:
          $ref: '#/components/responses/errorResponse4XX'
        5XX:
          $ref: '#/components/responses/errorResponse5XX'
      summary: Get programbundles
      x-summary-source: derived
      operationId: getProgrambundles
      x-operation-id-source: derived
  /programBundles:
    get:
      tags:
      - Deprecated
      description: __Deprecated. Use the /collections endpoint with VIDEOPROGRAMS as the item type instead.__
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/languageParam'
      - $ref: '#/components/parameters/contentMarketParam'
      - $ref: '#/components/parameters/omitCatalogsParam'
      - $ref: '#/components/parameters/encodingParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramBundlesResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '429':
          $ref: '#/components/responses/errorResponse429'
        4XX:
          $ref: '#/components/responses/errorResponse4XX'
        5XX:
          $ref: '#/components/responses/errorResponse5XX'
      summary: Get program bundles
      x-summary-source: derived
      operationId: getProgramBundles
      x-operation-id-source: derived
  /albumEditions:
    get:
      tags:
      - Deprecated
      description: __Deprecated. Use the lower case /albumeditions endpoint instead.__
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/languageParam'
      - $ref: '#/components/parameters/contentMarketParam'
      - $ref: '#/components/parameters/encodingParam'
      - $ref: '#/components/parameters/artistName'
      - $ref: '#/components/parameters/albumEditionName'
      - $ref: '#/components/parameters/recordingNameOptional'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlbumEditionsResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '429':
          $ref: '#/components/responses/errorResponse429'
        4XX:
          $ref: '#/components/responses/errorResponse4XX'
        5XX:
          $ref: '#/components/responses/errorResponse5XX'
      summary: Get album editions
      x-summary-source: derived
      operationId: getAlbumEditions
      x-operation-id-source: derived
  /albumEditions/{albumEditionID}:
    get:
      tags:
      - Deprecated
      description: __Deprecated. Use the lower case /albumeditions/{albumEditionID} endpoint instead.__
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - name: albumEditionID
        in: path
        required: true
        description: The unique identifier of the album edition.
        schema:
          type: string
      - $ref: '#/components/parameters/languageParam'
      - $ref: '#/components/parameters/contentMarketParam'
      - $ref: '#/components/parameters/encodingParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlbumEditionsResponse'
        '400':
          $ref: '#/components/responses/errorResponse400'
        '401':
          $ref: '#/components/responses/errorResponse401'
        '403':
          $ref: '#/components/responses/errorResponse403'
        '404':
          $ref: '#/components/responses/errorResponse404'
        '429':
          $ref: '#/components/responses/errorResponse429'
        4XX:
          $ref: '#/components/responses/errorResponse4XX'
        5XX:
          $ref: '#/components/responses/errorResponse5XX'
      summary: Get album editions by album edition id
      x-summary-source: derived
      operationId: getAlbumEditionsByAlbumEditionID
      x-operation-id-source: derived
components:
  parameters:
    albumEditionName:
      name: albumEditionName
      in: query
      description: Album Edition name
      required: true
      schema:
        type: string
      examples:
        default:
          value: Love
    omitCatalogsParam:
      name: omitCatalogIDs
      in: query
      required: false
      allowEmptyValue: true
      description: 'Comma separated list of streaming catalogIDs used to exclude content from particular streaming catalogs.

        This is honored for `/collections`, `/programs`, and `/programbundles` when itemTypes includes VIDEOPROGRAMS,

        and for `/search` when itemTypes includes VIDEOMOVIES and/or VIDEOSHOWS.

        '
      schema:
        type: string
        examples:
        - 111777,81277
    artistName:
      name: artistName
      in: query
      description: Artist name
      required: true
      schema:
        type: string
      examples:
        default:
          value: The Beatles
    recordingNameOptional:
      name: recordingName
      in: query
      description: Recording name
      required: false
      schema:
        type: string
      examples:
        default:
          value: Help!
    contentMarketParam:
      in: query
      name: contentMarket
      description: The market for the content. This parameter is used to tailor the content based on the target market as set by the manufacturer.
      required: true
      schema:
        type: string
        enum:
        - AUS
        - CAN
        - DEU
        - ESP
        - FRA
        - GBR
        - IND
        - ITA
        - JPN
        - KOR
        - USA
      examples:
        default:
          value: USA
    encodingParam:
      description: Optional header to specify the encoding type that the client is hoping to receive.
      name: Accept-Encoding
      in: header
      required: false
      schema:
        type: string
        examples:
        - gzip
    apiKeyParam:
      name: GN-APIKEY
      in: header
      description: API key to authorize the request.
      required: true
      schema:
        type: string
        examples:
        - your-api-key
    languageParam:
      name: preferredLanguage
      in: query
      description: The preferred language for the content is a two-letter country and two-letter language code, such as en-US. The API returns localized strings in the specified language if available. Otherwise, the API will default to the primary language of the contentMarket.
      required: true
      schema:
        pattern: ^[a-z]{2}-[A-Z]{2}$
        examples:
        - en-GB
  schemas:
    ProgramBundlesResponse:
      type: object
      additionalProperties: false
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProgramBundle'
    ProgramBundle:
      type: object
      additionalProperties: false
      required:
      - bundleID
      - name
      - lastUpdatedUTC
      - programs
      - bundleType
      properties:
        bundleID:
          type: string
          examples:
          - DEU-Comedy-Movies
        name:
          type: string
          description: Display name.
        lastUpdatedUTC:
          type: string
        bundleType:
          type: string
          enum:
          - MOVIES
          - SERIES
        programs:
          type: array
          items:
            $ref: '#/components/schemas/ProgramShort'
    ArtistShort:
      type: object
      additionalProperties: false
      description: There is a known issue where sometimes artistID will be null.
      required:
      - name
      - artistID
      - images
      properties:
        name:
          type: string
        artistID:
          type:
          - string
          - 'null'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
    AlbumEdition:
      type: object
      additionalProperties: false
      required:
      - name
      - albumEditionID
      - images
      - artist
      - descriptors
      - tracks
      properties:
        albumEditionID:
          type: string
        name:
          type: string
        artist:
          $ref: '#/components/schemas/ArtistShort'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        descriptors:
          type: object
          additionalProperties: false
          properties:
            genres:
              type: array
              items:
                $ref: '#/components/schemas/Descriptor'
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/Track'
    Image:
      type: object
      additionalProperties: false
      required:
      - orientation
      - type
      - URL
      - contentType
      properties:
        orientation:
          type: string
          description: Orientation of the image.
          enum:
          - LANDSCAPE
          - PORTRAIT
          - SQUARE
        type:
          type: string
          enum:
          - ARTWORK
          - LOGO
          - HEADSHOT
          - FLAG
          - ARTIST
          - JERSEY
          - POSTER
          - BANNER
          - IMAGE_3_4
          - IMAGE_4_3
          - IMAGE_16_9
          - BRAND_LOGO
        URL:
          type: string
          description: Note that some image hosting platforms require a user-agent header to be specified when fetching images.
        contentType:
          type:
          - string
          - 'null'
    StreamingCatalog:
      type: object
      additionalProperties: false
      required:
      - name
      - catalogID
      - images
      - catalogType
      description: Streaming provider.
      properties:
        name:
          type: string
        catalogID:
          type: string
        catalogType:
          type: string
          enum:
          - AUDIO
          - VIDEO
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
    AvailabilityURL:
      type: object
      additionalProperties: false
      description: URLs for streaming the related content.
      required:
      - type
      - URL
      properties:
        URL:
          type: string
        type:
          type: string
          enum:
          - web
          - android
          - aaos
    Availability:
      type: object
      additionalProperties: false
      description: The information necessary to link media to streaming catalogs. In some cases Nexus provides a direct URL to the media on the streaming services while other times Nexus provides the ID for the media on the service. You will need to work with the streaming services themselves to decide how to best link to their content.
      required:
      - externalID
      - catalog
      - URLs
      properties:
        URLs:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityURL'
        externalID:
          type: string
          description: 3rd party ID for the content.
        catalog:
          $ref: '#/components/schemas/StreamingCatalog'
    ProgramShort:
      type: object
      additionalProperties: false
      required:
      - programID
      - name
      - nameShort
      - durationMilliseconds
      - images
      - availableOn
      properties:
        programID:
          type: string
        name:
          type: string
        nameShort:
          type:
          - string
          - 'null'
          description: When available, a shortened version of the name that is 20 characters or less.
        durationMilliseconds:
          type:
          - number
          - 'null'
        availableOn:
          type: array
          items:
            $ref: '#/components/schemas/Availability'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
      - status
      - error
      - description
      properties:
        status:
          type: integer
          description: HTTP status code
        error:
          type: string
          enum:
          - internal_server_error
          - invalid_query_method
          - missing_query_parameter
          - invalid_query_parameter_value
          - resource_not_found
          - invalid_request
          - resource_type_error
          - forbidden
          - unauthorized_missing_api_key
          - unauthorized_invalid_api_key
          - quota_limit_exceeded
          - content_too_large
          - unexpected_eof_at_target
          - service_unavailable
        description:
          type: string
    AlbumEditionsResponse:
      type: object
      additionalProperties: false
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/AlbumEdition'
    Meta:
      type: object
      additionalProperties: false
      required:
      - total
      - version
      - references
      properties:
        total:
          type: integer
          description: Total number of data objects available.
        version:
          type: string
          description: The API version
        references:
          type: object
          additionalProperties: false
          properties:
            preferredLanguage:
              type: string
            contentMarket:
              type: string
            leagueID:
              type: string
            teamID:
              type: string
            personID:
              type: string
            divisionID:
              type: string
            conferenceID:
              type: string
            overallID:
              type: string
            matchID:
              type: string
            omitCatalogIDs:
              type: string
            minDuration:
              type: string
            maxDuration:
              type: string
            bundleID:
              type: string
            programID:
              type: string
            catalogID:
              type: string
            phaseID:
              type: string
            artistID:
              type: string
            albumEditionID:
              type: string
            recordingID:
              type: string
            artistName:
              type: string
            albumEditionName:
              type: string
            recordingName:
              type: string
            podcastID:
              type: string
            podcastEpisodeID:
              type: string
            radioStationID:
              type: string
            collectionID:
              type: string
            collectionCategory:
              type: string
            itemTypes:
              type: string
            text:
              type: string
            topOnly:
              type: string
    Descriptor:
      type: object
      additionalProperties: false
      required:
      - name
      - descriptorID
      properties:
        name:
          type: string
        descriptorID:
          type: string
    Track:
      type: object
      additionalProperties: false
      description: There is a known issue where sometimes artistID and/or recordingID will be null.
      required:
      - name
      - recordingID
      - artist
      properties:
        name:
          type: string
        recordingID:
          type:
          - string
          - 'null'
        artist:
          $ref: '#/components/schemas/ArtistShortNoImage'
    ArtistShortNoImage:
      type: object
      additionalProperties: false
      description: There is a known issue where sometimes artistID will be null.
      required:
      - name
      - artistID
      properties:
        name:
          type: string
        artistID:
          type:
          - string
          - 'null'
  responses:
    errorResponse403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 403
                error: forbidden
                description: GN-APIKEY is not entitled for this request.
    errorResponse4XX:
      description: Other 4XX may occur. Please read the error description for more information.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 405
                error: invalid_query_method
                description: Only GET is supported for this endpoint.
    errorResponse400:
      description: Bad Request. Please see the error description for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 400
                error: invalid_query_parameter_value
                description: Unsupported contentMarket values
    errorResponse429:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 429
                error: quota_limit_exceeded
                description: Too many requests. Client exceeded their allocated rate limit.
    errorResponse404:
      description: The specified object was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 404
                error: resource_not_found
                description: Resource not found.
    errorResponse5XX:
      description: An unexpected error occurred on the server. Please see the error description for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 500
                error: internal_server_error
                description: Server encountered an unexpected condition that prevented it from fulfilling the request.
    errorResponse401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 401
                error: unauthorized_missing_api_key
                description: GN-APIKEY header must be provided.