openapi: 3.2.0 info: title: Nexus API v1.1.5 Experimental 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: Experimental description: API endpoints related to forthcoming features. paths: /teams/resolution: get: tags: - Experimental description: Resolve a team name to a Nexus teamID. parameters: - $ref: '#/components/parameters/apiKeyParam' - $ref: '#/components/parameters/nameParam' - $ref: '#/components/parameters/sportTypeParam' - $ref: '#/components/parameters/leagueNameParam' - $ref: '#/components/parameters/genderParam' - $ref: '#/components/parameters/nationalityParam' - $ref: '#/components/parameters/limitParam' - $ref: '#/components/parameters/languageParam' - $ref: '#/components/parameters/contentMarketParam' - $ref: '#/components/parameters/encodingParam' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/EntityResolutionResponse' '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 teams resolution x-summary-source: derived operationId: getTeamsResolution x-operation-id-source: derived /leagues/resolution: get: tags: - Experimental description: Resolve a league name to a Nexus leagueID. parameters: - $ref: '#/components/parameters/apiKeyParam' - $ref: '#/components/parameters/nameParam' - $ref: '#/components/parameters/sportTypeParam' - $ref: '#/components/parameters/genderParam' - $ref: '#/components/parameters/nationalityParam' - $ref: '#/components/parameters/limitParam' - $ref: '#/components/parameters/languageParam' - $ref: '#/components/parameters/contentMarketParam' - $ref: '#/components/parameters/encodingParam' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/EntityResolutionResponse' '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 leagues resolution x-summary-source: derived operationId: getLeaguesResolution x-operation-id-source: derived /conferences/resolution: get: tags: - Experimental description: Resolve a conference name to a Nexus conferenceID. parameters: - $ref: '#/components/parameters/apiKeyParam' - $ref: '#/components/parameters/nameParam' - $ref: '#/components/parameters/leagueNameParam' - $ref: '#/components/parameters/sportTypeParam' - $ref: '#/components/parameters/genderParam' - $ref: '#/components/parameters/nationalityParam' - $ref: '#/components/parameters/limitParam' - $ref: '#/components/parameters/languageParam' - $ref: '#/components/parameters/contentMarketParam' - $ref: '#/components/parameters/encodingParam' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/EntityResolutionResponse' '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 conferences resolution x-summary-source: derived operationId: getConferencesResolution x-operation-id-source: derived /divisions/resolution: get: tags: - Experimental description: Resolve a division name to a Nexus divisionID. parameters: - $ref: '#/components/parameters/apiKeyParam' - $ref: '#/components/parameters/nameParam' - $ref: '#/components/parameters/leagueNameParam' - $ref: '#/components/parameters/sportTypeParam' - $ref: '#/components/parameters/genderParam' - $ref: '#/components/parameters/nationalityParam' - $ref: '#/components/parameters/limitParam' - $ref: '#/components/parameters/languageParam' - $ref: '#/components/parameters/contentMarketParam' - $ref: '#/components/parameters/encodingParam' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/EntityResolutionResponse' '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 divisions resolution x-summary-source: derived operationId: getDivisionsResolution x-operation-id-source: derived /albumeditions: get: tags: - Experimental description: Retrieve AlbumEditions matching given albumEditionName and artistName parameters. If (optional) recordingName is provided, it will only return AlbumEditions that include the track with the given recordingName. 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 albumeditions x-summary-source: derived operationId: getAlbumeditions x-operation-id-source: derived /recordings: get: tags: - Experimental description: Retrieve Recordings matching given recordingName and artistName parameters. If (optional) albumEditionName is provided, it will return the best Recording that is on the given AlbumEdition name. parameters: - $ref: '#/components/parameters/apiKeyParam' - $ref: '#/components/parameters/languageParam' - $ref: '#/components/parameters/contentMarketParam' - $ref: '#/components/parameters/encodingParam' - $ref: '#/components/parameters/artistName' - $ref: '#/components/parameters/albumEditionNameOptional' - $ref: '#/components/parameters/recordingName' 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 x-summary-source: derived operationId: getRecordings 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 nationalityParam: name: nationality in: query required: false description: Optional nationality to improve accuracy. (e.g., "England", "USA", "World"). This currently works as a hard filter, not a hint. schema: type: string 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 nameParam: name: name in: query required: true description: Natural language name for the entity needing resolving to a Gracenote ID (e.g., "Los Angeles Lakers", "English Premier League") schema: type: string recordingName: name: recordingName in: query description: Recording name required: true schema: type: string examples: default: value: Help! sportTypeParam: name: sportType in: query required: false description: Optional sport type context to improve accuracy schema: $ref: '#/components/schemas/SportType' 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 leagueNameParam: name: leagueName in: query required: false description: Optional league context to improve accuracy (e.g., "NBA", "Premier League"). This currently works as a hard filter, not a hint. schema: type: string limitParam: name: limit in: query required: false description: Maximum number of results to return (default 10, max 100) schema: type: integer minimum: 1 maximum: 100 default: 10 genderParam: name: gender in: query required: false description: Optional gender to improve accuracy. This currently works as a hard filter, not a hint. schema: $ref: '#/components/schemas/SportGender' 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 albumEditionNameOptional: name: albumEditionName in: query description: Album Edition name required: false schema: type: string examples: default: value: Love 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: 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' 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' ResolvedEntity: type: object additionalProperties: false required: - ID - type - name - confidence properties: ID: type: string description: The Nexus ID for use in other API calls (teamID, leagueID, conferenceID, divisionID) name: type: string description: Canonical name in Nexus type: $ref: '#/components/schemas/EntityType' confidence: type: number minimum: 0 maximum: 1 description: Confidence score for the match (0.0 to 1.0) sportType: $ref: '#/components/schemas/SportType' gender: $ref: '#/components/schemas/SportGender' nationality: type: string typeDetail: type: string description: Additional detail about the entity type. For example, an F1 team could have a typeDetail of TEAM_CONSTRUCTOR. contexts: type: array items: type: object description: Context information for the match to save on follow-up queries. For example, conference responses will include the ID for their parent league. Unlike other Nexus objects, context will be omitted when there isn't one for the response. additionalProperties: false required: - ID - type - name properties: ID: type: - string - 'null' name: type: - string - 'null' type: $ref: '#/components/schemas/EntityType' SportGender: type: string enum: - MALE - FEMALE - MIXED - OPEN - UNKNOWN SportType: type: string enum: - FOOTBALL - AMERICAN_FOOTBALL - BASKETBALL - BASEBALL - ICE_HOCKEY - TENNIS - GOLF - AUTO_RACING - RUGBY_UNION - UNKNOWN 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' EntityResolutionResponse: type: array items: $ref: '#/components/schemas/ResolvedEntity' 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' EntityType: type: string enum: - TEAM - LEAGUE - CONFERENCE - DIVISION