Gracenote Collections API

openapi: 3.2.0
info:
  title: Nexus API v1.1.5 Collections 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: Collections
  description: API endpoints related to curated content collections.
paths:
  /collections:
    get:
      tags:
      - Collections
      description: Fetch curated collections for the specified contentMarket. The video program collections will be filtered based on the apiKey's entitled streaming catalogs and optional parameter `omitCatalogIDs`.
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/collectionCategoryParam'
      - $ref: '#/components/parameters/collectionItemTypesParam'
      - $ref: '#/components/parameters/omitCatalogsParam'
      - $ref: '#/components/parameters/languageParam'
      - $ref: '#/components/parameters/contentMarketParam'
      - $ref: '#/components/parameters/encodingParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionsResponse'
        '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 collections
      x-summary-source: derived
      operationId: getCollections
      x-operation-id-source: derived
  /collections/{collectionID}:
    get:
      tags:
      - Collections
      description: 'Fetch collections identified by the _collectionID_.


        Note that for sports entity collections like teams and leagues, you should use the _teamID_, _leagueID_ and _conferenceID_ as the _collectionID_.'
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - name: collectionID
        in: path
        required: true
        description: The unique identifier of the collection.
        schema:
          type: string
      - $ref: '#/components/parameters/collectionItemTypesParam'
      - $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/CollectionsResponse'
        '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 collections by collection id
      x-summary-source: derived
      operationId: getCollectionsByCollectionID
      x-operation-id-source: derived
components:
  schemas:
    CollectionCategory:
      type: string
      description: note that GENERAL has been deprecated. Please use CATEGORY for radio station collections organized by Radio Station Category like 'Adult Pop' or 'Local & Community' and TOPIC for podcast collections organized by topics like 'Health & Living' and 'News & Politics'. GENRE is used for VIDEOPROGRAMS (program bundle) collections.
      enum:
      - NEWS
      - CATEGORY
      - TOPIC
      - GENRE
      - TEAM
      - LEAGUE
      - CONFERENCE
      - SPORT
      - CITY
      - STATE
      - COUNTRY
      - GENERAL
    URLObject:
      type: object
      additionalProperties: false
      required:
      - URL
      - type
      - content
      - contentType
      properties:
        URL:
          type: string
        type:
          type: string
          enum:
          - web
          - mobile
          - desktop
        content:
          type:
          - string
          - 'null'
          enum:
          - MEDIA
          - FEED
          - WEBSITE
          - STREAM
        contentType:
          type:
          - string
          - 'null'
          examples:
          - audio/mpeg
    CollectionTag:
      type: object
      additionalProperties: false
      description: Tag object for collection metadata. Populated for VIDEOPROGRAMS collections (genreType, programType); unused for other itemTypes.
      required:
      - genreType
      - programType
      properties:
        genreType:
          type: string
          description: Video collection genre (e.g. COMEDY, SCIENCE-FICTION). Empty string when not applicable.
        programType:
          type: string
          description: Whether the collection contains movies or series. Empty string when not applicable.
          enum:
          - MOVIES
          - SERIES
    DabData:
      type:
      - object
      - 'null'
      properties:
        eid:
          type:
          - string
          - 'null'
        sid:
          type:
          - string
          - 'null'
        scids:
          type:
          - string
          - 'null'
        serviceLabel:
          type:
          - string
          - 'null'
        serviceLabelShort:
          type:
          - string
          - 'null'
    PodcastEpisodeLink:
      type: object
      additionalProperties: false
      required:
      - URL
      - contentType
      - sizeBytes
      properties:
        URL:
          type: string
        contentType:
          type:
          - string
          - 'null'
          examples:
          - audio/mpeg
        sizeBytes:
          type:
          - integer
          - 'null'
    RadioStationTeam:
      type: object
      additionalProperties: false
      required:
      - teamID
      - teamName
      - language
      - flagship
      properties:
        teamID:
          type: string
          description: Gracenote sports team ID.
        teamName:
          type: string
          description: Name of the sports team.
        language:
          type: string
          description: Language of the broadcast affiliation.
        flagship:
          type: boolean
          description: Indicates if this station is a flagship station for the team.
    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'
    StreamObject:
      type: object
      additionalProperties: false
      required:
      - URL
      - contentType
      properties:
        URL:
          type: string
        contentType:
          type:
          - string
          - 'null'
          examples:
          - audio/mpeg
        bitRate:
          type:
          - integer
          - 'null'
        channels:
          type:
          - integer
          - 'null'
        sampleRate:
          type:
          - integer
          - 'null'
    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
    Collection:
      type: object
      additionalProperties: false
      required:
      - collectionID
      - name
      - collectionCategory
      - itemType
      - lastUpdatedUTC
      - contentMarket
      - tags
      - items
      properties:
        collectionID:
          type: string
        name:
          type: string
        collectionCategory:
          $ref: '#/components/schemas/CollectionCategory'
        itemType:
          $ref: '#/components/schemas/CollectionItemType'
        lastUpdatedUTC:
          type: string
          format: date-time
          examples:
          - '2026-01-02T15:42:22.000Z'
        contentMarket:
          type: string
          description: ISO 3166-1 alpha-3 content market for the collection (e.g. USA, DEU).
        tags:
          type: array
          description: Required. May be empty for PODCASTS and RADIOSTATIONS collections. For VIDEOPROGRAMS, contains a tag object with genreType and programType.
          items:
            $ref: '#/components/schemas/CollectionTag'
        items:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Program'
            - $ref: '#/components/schemas/Podcast'
            - $ref: '#/components/schemas/RadioStation'
    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'
    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
    RadioStation:
      type: object
      additionalProperties: false
      required:
      - radioStationID
      - name
      - nameShort
      - flagship
      - slogans
      - publicValues
      - broadcasts
      - descriptors
      - images
      - streams
      properties:
        radioStationID:
          type: string
        name:
          type: string
        nameShort:
          type: string
        flagship:
          type:
          - boolean
          - 'null'
          description: Indicates if this station is a flagship station for the team.
        slogans:
          type: array
          items:
            $ref: '#/components/schemas/RadioStationSlogan'
        publicValues:
          type: array
          items:
            $ref: '#/components/schemas/RadioStationPublicValue'
        broadcasts:
          type: array
          items:
            $ref: '#/components/schemas/Broadcast'
        descriptors:
          type: object
          properties:
            categories:
              type: array
              items:
                $ref: '#/components/schemas/Descriptor'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        streams:
          type: array
          items:
            $ref: '#/components/schemas/StreamObject'
        teams:
          type: array
          description: Sports team affiliations for this station. Present when the station is associated with one or more sports teams via the teamID filter.
          items:
            $ref: '#/components/schemas/RadioStationTeam'
    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
    RadioStationSlogan:
      type: object
      additionalProperties: false
      required:
      - display
      properties:
        display:
          type: string
          description: The station slogan text.
    ColorPalette:
      type:
      - object
      - 'null'
      additionalProperties: false
      required:
      - muted
      - vibrant
      - darkMuted
      - lightMuted
      - darkVibrant
      - lightVibrant
      properties:
        muted:
          type:
          - string
          - 'null'
        vibrant:
          type:
          - string
          - 'null'
        darkMuted:
          type:
          - string
          - 'null'
        lightMuted:
          type:
          - string
          - 'null'
        darkVibrant:
          type:
          - string
          - 'null'
        lightVibrant:
          type:
          - string
          - 'null'
    CrewMember:
      type: object
      additionalProperties: false
      required:
      - role
      - name
      properties:
        role:
          type: string
        name:
          type: string
    CastMember:
      type: object
      additionalProperties: false
      required:
      - role
      - characterName
      - actorName
      properties:
        role:
          type: string
        characterName:
          type: string
        actorName:
          type: string
    Descriptor:
      type: object
      additionalProperties: false
      required:
      - name
      - descriptorID
      properties:
        name:
          type: string
        descriptorID:
          type: string
    CollectionShort:
      type: object
      additionalProperties: false
      required:
      - collectionID
      - name
      - collectionCategory
      - itemType
      - lastUpdatedUTC
      - contentMarket
      - tags
      properties:
        collectionID:
          type: string
        name:
          type: string
        collectionCategory:
          $ref: '#/components/schemas/CollectionCategory'
        itemType:
          $ref: '#/components/schemas/CollectionItemType'
        lastUpdatedUTC:
          type: string
          format: date-time
          examples:
          - '2026-01-02T15:42:22.000Z'
        contentMarket:
          type: string
          description: ISO 3166-1 alpha-3 content market for the collection (e.g. USA, DEU).
        tags:
          type: array
          description: Required. May be empty for PODCASTS and RADIOSTATIONS collections. For VIDEOPROGRAMS, contains a tag object with genreType and programType.
          items:
            $ref: '#/components/schemas/CollectionTag'
    Broadcast:
      type:
      - object
      - 'null'
      required:
      - frequency
      - band
      - callSign
      - signalType
      properties:
        frequency:
          type:
          - string
          - 'null'
        band:
          type: string
          enum:
          - FM
          - AM
          - DAB
        callSign:
          type:
          - string
          - 'null'
        signalType:
          type:
          - string
          - 'null'
        hdMulticast:
          type:
          - string
          - 'null'
        piCodes:
          type: array
          items:
            type: string
        ecc:
          type:
          - string
          - 'null'
        dabData:
          $ref: '#/components/schemas/DabData'
    Podcast:
      type: object
      additionalProperties: false
      required:
      - podcastID
      - name
      - description
      - seriesType
      - explicitLanguage
      - language
      - owner
      - author
      - images
      - colorPalette
      - relatedCollections
      - episodes
      properties:
        podcastID:
          type: string
        name:
          type: string
        description:
          type: string
        contentType:
          deprecated: true
          description: Deprecated - use seriesType instead.
          type:
          - string
          - 'null'
          enum:
          - EPISODIC
          - SERIAL
        seriesType:
          type:
          - string
          - 'null'
          enum:
          - EPISODIC
          - SERIAL
        explicitLanguage:
          type:
          - boolean
          - 'null'
        language:
          type:
          - string
          - 'null'
        author:
          type:
          - string
          - 'null'
        owner:
          type:
          - string
          - 'null'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        colorPalette:
          $ref: '#/components/schemas/ColorPalette'
        relatedCollections:
          type: array
          items:
            $ref: '#/components/schemas/CollectionShort'
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/PodcastEpisode'
    CollectionItemType:
      type: string
      description: This specifies what kind of items are in a collection.
      enum:
      - PODCASTS
      - RADIOSTATIONS
      - VIDEOPROGRAMS
    PodcastEpisode:
      type: object
      additionalProperties: false
      required:
      - podcastEpisodeID
      - podcastID
      - name
      - description
      - links
      - publicationDateUTC
      - seasonNumber
      - episodeType
      - explicitLanguage
      - durationMilliseconds
      - webPage
      - images
      - colorPalette
      properties:
        podcastEpisodeID:
          type: string
        podcastID:
          type: string
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        URLs:
          deprecated: true
          description: Deprecated - replaced by links and wePage.
          type: array
          items:
            $ref: '#/components/schemas/URLObject'
        links:
          type: array
          items:
            $ref: '#/components/schemas/PodcastEpisodeLink'
        publicationDateUTC:
          type: string
          format: date-time
          examples:
          - '2026-01-04T22:30:00.000Z'
        webPage:
          type:
          - string
          - 'null'
        seasonNumber:
          type:
          - integer
          - 'null'
        episodeType:
          type:
          - string
          - 'null'
          description: todo enum? [FULL, TRAILER, BONUS, null]
        explicitLanguage:
          type:
          - boolean
          - 'null'
        durationMilliseconds:
          type:
          - integer
          - 'null'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        colorPalette:
          $ref: '#/components/schemas/ColorPalette'
        sizeBytes:
          deprecated: true
          description: Deprecated - use the sizeBytes in the episode link instead.
          type:
          - integer
          - 'null'
    RadioStationPublicValue:
      type: object
      additionalProperties: false
      required:
      - container
      - region
      - state
      properties:
        container:
          type: string
          description: Public-value container identifier.
        region:
          type:
          - string
          - 'null'
          description: Region associated with the public value, or null when not available.
        state:
          type: string
          description: State or province associated with the public value.
    CollectionsResponse:
      type: object
      additionalProperties: false
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
    Program:
      type: object
      additionalProperties: false
      required:
      - programID
      - name
      - nameShort
      - description
      - programType
      - programSubType
      - rating
      - country
      - releaseYear
      - cast
      - crew
      - durationMilliseconds
      - descriptors
      - availableOn
      - images
      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.
        description:
          type: string
        programType:
          type: string
          description: The type of the program, examples include "Feature Film", "TV Movie", "Short Film", "Series", "Miniseries" and "Special"
          examples:
          - Feature Film
        programSubType:
          type: string
          description: Additional program categorization, denoting how a program was originally produced and/or distributed. Examples include "Compilation", "Episode", "Feature Film", "Highlights", "Miniseries", "Music Video", "Off Air", "Paid Program", "Preview", "Series", "Short Film", "Special", "Sport", "Sport Event", "Sport-Related Episode", "TBA", "Team Event", "Trailer" and "TV Movie"
          examples:
          - Miniseries
        rating:
          type: string
          description: The rating in the ratings system associated with the content market.
        country:
          type: string
          description: Country of origin of the program.
        releaseYear:
          type:
          - number
          - 'null'
          description: Year of release.
        cast:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CastMember'
        crew:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CrewMember'
        durationMilliseconds:
          type:
          - number
          - 'null'
          description: Running time of the program.
        descriptors:
          type: object
          additionalProperties: false
          required:
          - genres
          properties:
            genres:
              type: array
              items:
                $ref: '#/components/schemas/Descriptor'
        availableOn:
          type: array
          items:
            $ref: '#/components/schemas/Availability'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
  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.
    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.
    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.
  parameters:
    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
    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
    collectionCategoryParam:
      name: collectionCategory
      in: query
      required: true
      description: 'Filter collections by collection category. Currently these collectionCategory mappings are supported:


        PODCASTS collections exist for: _NEWS_, _TOPIC_, _TEAM_, _LEAGUE_, _CONFERENCE_ and _SPORT_


        RADIOSTATIONS collections exist for: _NEWS_, _CATEGORY_, _TEAM_, _CITY_, _STATE_, _COUNTRY_ and _SPORT_


        VIDEOPROGRAMS: responses use _GENRE_ for curated program-bundle collections.


        Note that a `Sports` entitlement is needed for collections with these categories: _SPORT_, _LEAGUE_, _TEAM_ and _CONFERENCE_


        A `News & Talk` entitlement is needed for collections with these categories: _NEWS_, _CATEGORY_ and _TOPIC_


        A `RadioStationID` entitlement is needed for collections with these categories: _CITY_, _STATE_ and _COUNTRY_

        '
      schema:
        $ref: '#/components/schemas/CollectionCategory'
    collectionItemTypesParam:
      name: itemTypes
      in: query
      required: true
      description: 'Filter collections by the type of items they contain. Comma-separate multiple values.

        '
      schema:
        type: array
        items:
          $ref: '#/components/schemas/CollectionItemType'
      explode: false
    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