The Program Mappings endpoint delivers mapping information for customers using Gracenote's VOD Program Services. The endpoint provides up-to-date information for asset mapping requests received, mappings completed, and assets unable to be mapped. On API can be configured to deliver mapping and program information for one or more customer catalogs.
The ProgramMappings endpoint works in conjunction with the Programs endpoint. While the ProgramMappings endpoint includes links between TMSIds and customer asset IDs, the Programs endpoint includes the metadata for all referenced TMSIds, including Series records for any referenced Episodes.
Program Mappings endpoint includes a full customer asset catalog, regardless of availability window. Mapping updates reflect changes to any asset mappings, including out-of-window assets if updated due to Gracenote's receipt of new metadata or request for remapping.
The schema provides mapping information, including:
- TmsId, for linking to Programs API
- ProviderId, for linking to customer assets
- Status, for information on mapping stage
- Availability window provided by the customer dataset
- Catalog name, useful for customers providing multiple catalogs for mappings
API Reference
Base URL:
Code
Parameters:
updateId=<updateId value>limit=<limit value>api_key=<your-api-key>
Request Parameters
| Parameter | Required? | Description |
|---|---|---|
| api_key | Yes | Your API key |
| updateId | No | Program mappings modified at or after updateId |
| limit | No | Batch size. Maximum number of program mappings to be returned, to be used in conjunction with updateId to specify batch size |
| programMappingId | No | For non-batch lookups. Accepts comma-separated list of programMapping IDs |
| tmsId | No | For non-batch lookups. 44-char tmsId format. Accepts comma-separated list of TMSIds |
| providerId | No | For non-batch lookups. Customer-specific providerId for mappings assets. Accepts comma-separated list of providerIds |
Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
Example Requests
Return mapping updates in batches of 1000:
Code
Return current mapping data for set of programMappingIds:
Code
Example Response
See Program Mapping XML examples
Data Structure and Relationships
XML Schema URL: http://files.api.gracenote.com/xsd/on_update_programmappings_3.24.xsd
The XPATH in the tables below is relative to: on/programMappings/programMapping
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| @programMappingId | Identifier for the program mapping, uniquely representing customer asset identifier and catalog pair | 63940301 |
| catalogName | Name of the catalog containing the program mapping | Disney Plus US |
| creationDate | Program mapping ingestion/creation date | 2020-02-17 08:08:22 |
| status | Mapping status: ToBeMapped, Mapped, Unmappable | Mapped |
| id@type | GN identifier of a given type: TMSId, rootId, versionId | EP030880640072 (TMSId) |
| link@idType | Customer asset identifier of a given type: ProviderId, PID (provider id), PAID (provider asset id) | 35bb26dd-2f0b-43c1-87e7-486caff60948 (ProviderId) |
| availability/start | Content provider availability start date and time | 2020-03-01T03:00:00Z |
| availability/end | Content provider availability end date and time | 2022-11-12T03:00:00Z |
| message/@reason | The reason for Unmappable status | Insufficient Metadata, Metadata Discrepancy, Not Included in Current Agreement, Not in Scope for Gracenote Database, … |
The Supplemental Controlled Vocabulary (auto-download) provides descriptions and examples for Mapping-related lists.
Entity Relationship Diagram
The ProgramMappings endpoint works in conjunction with the Programs endpoint. The ProgramMappings endpoint contains the links between TMSIds and customer asset identifiers, the Programs endpoint includes the actual metadata for all referenced TMSIds, including Series records for any referenced Episode.
