openapi: 3.2.0
info:
  title: Nexus API v1.1.5 Music 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: Music
  description: API endpoints related to music content.
paths:
  /artists/{artistID}:
    get:
      tags:
      - Music
      description: Fetch the details of a specific artist identified by the artistID.
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - name: artistID
        in: path
        required: true
        description: The unique identifier of the artist. Some sample artist IDs include GMGZZX80000332M (Taylor Swift), GMGZZX80000WDH2 (Peso Pluma) and GMGZZX800009DXC (ROSALÍA).
        schema:
          type: string
        examples:
          default:
            value: GMGZZX80000332M
      - $ref: '#/components/parameters/languageParam'
      - $ref: '#/components/parameters/contentMarketParam'
      - $ref: '#/components/parameters/encodingParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistsResponse'
        '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 artists by artist id
      x-summary-source: derived
      operationId: getArtistsByArtistID
      x-operation-id-source: derived
  /albumeditions/{albumEditionID}:
    get:
      tags:
      - Music
      description: Fetch the details of a specific album edition identified by the albumEditionID. AlbumEdition IDs can be found via recording fetches or album edition text identifications.
      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 albumeditions by album edition id
      x-summary-source: derived
      operationId: getAlbumeditionsByAlbumEditionID
      x-operation-id-source: derived
  /recordings/{recordingID}:
    get:
      tags:
      - Music
      description: Fetch the details of a specific recording identified by the recordingID. Recording IDs can be found via artist fetches or radio song identifications.
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - name: recordingID
        in: path
        required: true
        description: The unique identifier of the recording.
        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/RecordingsResponse'
        '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 recordings by recording id
      x-summary-source: derived
      operationId: getRecordingsByRecordingID
      x-operation-id-source: derived
components:
  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.
  schemas:
    RecordingShort:
      type: object
      additionalProperties: false
      required:
      - name
      - recordingID
      - images
      - artist
      - availableOn
      properties:
        recordingID:
          type: string
        name:
          type: string
        artist:
          $ref: '#/components/schemas/ArtistShort'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        availableOn:
          type: array
          items:
            $ref: '#/components/schemas/Availability'
    Artist:
      type: object
      additionalProperties: false
      required:
      - name
      - artistID
      - images
      - descriptors
      - similarArtists
      - popularRecordings
      properties:
        name:
          type: string
        artistID:
          type: string
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        descriptors:
          type: object
          additionalProperties: false
          properties:
            genres:
              type: array
              items:
                $ref: '#/components/schemas/Descriptor'
        similarArtists:
          type: array
          items:
            $ref: '#/components/schemas/ArtistShort'
        popularRecordings:
          type: array
          items:
            $ref: '#/components/schemas/RecordingShort'
    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
    RecordingsResponse:
      type: object
      additionalProperties: false
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Recording'
    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'
    ArtistsResponse:
      type: object
      additionalProperties: false
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Artist'
    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
    AlbumEditionShort:
      type: object
      additionalProperties: false
      required:
      - name
      - albumEditionID
      - images
      properties:
        albumEditionID:
          type: string
        name:
          type: string
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
    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'
    Recording:
      type: object
      additionalProperties: false
      required:
      - name
      - recordingID
      - images
      - selectedAlbumEdition
      - artist
      - descriptors
      - durationMilliseconds
      - releaseYear
      - availableOn
      properties:
        recordingID:
          type: string
        name:
          type: string
        artist:
          $ref: '#/components/schemas/ArtistShort'
        selectedAlbumEdition:
          $ref: '#/components/schemas/AlbumEditionShort'
        durationMilliseconds:
          type: number
        releaseYear:
          type: number
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        descriptors:
          type: object
          additionalProperties: false
          properties:
            genres:
              type: array
              items:
                $ref: '#/components/schemas/Descriptor'
        availableOn:
          type: array
          items:
            $ref: '#/components/schemas/Availability'
    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'
  parameters:
    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