GN IDs API

Asset Information and Status

This section describes the general process of getting information about existing assets.

Get ID Mapping Information

To get additional information about the ID mapping of a presentation, look for the mappingInfo object in the response. This object includes:

• The ID associated with this program
• The type of ID (tmsID)
• The origin (assigner) of the ID. Origin will be "gracenote" when assigned by GN IDS. If you assign an ID, origin will be the sourceProvided.

For additional information, see the Data Dictionary and Controlled Vocabulary.

Request

Code
 
curl --request \
 GET --url \
 https://gnids.gracenote.com/api/v1/movies/versions/presentations/GNLZZXW000000G3 --header 'Content-Type: application/json' \
 --header 'GN-APIKEY: your-api-key' 

Example Response (Partial)

In the response, MappingInfo contains information about how the tmsID was assigned for the presentation.

• id: Contains the tmsID that the presentation is mapped to. This can be either user-provided ID or a gracenote-mapped ID.
• origin: Possible values are sourceProvided and gracenote. If the ID you provided is used, the origin is sourceProvided. If a gracenote-provided ID is used, or if gracenote replaces the ID you provided, gracenote is used.
• type: Describes the type of ID that was used for self-mapping. Currently, this is tmsID only.

Code
 
{
   "meta":{
      "count":1,
      "rayID":"f7f6dd69-5481-4bee-bf8c-b0d503c3a04b"
   },
   "data":[
      {
         "gnID":"GNLZZZ600000001",
         "type":"movie",
         "...""version":{
            "gnID":"GNLZZXX00000001",
            "type":"movie",
            "...""presentation":{
               "gnID":"GNLZZXW00000001",
               "type":"movie",
               "mappingInfo":{
                  "id":"MV00000000001",
                  "origin":"sourceProvided",
                  "type":"tmsID"
               },
               "publishExceptions":null,
               "publishingStatus":"published",
               "tmsID":"MV00000000001"
            }
         }
      }
   ]
}

Filter programSummaries Based on IDs

Program summaries are paginated collections of summaries for programs in a source's catalog. You can filter programSummaries based on tmsIDs and ExternalIDs. For example, to return only results that include MyID within the presentation's externalIDs

Code
 
curl --request \
 GET --url \
 https://gnids.gracenote.com/api/v1/programSummaries?limit=20&page=1&externalIDs=MyID \
 --header 'GN-APIKEY: your-api-key'

To return only programs that have been mapped to the tmsID MV000000000001.

Code
 
curl --request \
 GET --url \
 https://gnids.gracenote.com/api/v1/programSummaries?limit=20&page=1&tmsIDs=MV000000000001 \
 --header 'GN-APIKEY: your-api-key'

Get Batch Status

To see the status of all batches, use the batches endpoint.

Example

Code
 
curl --location 'https://gnids.gracenote.com/api/v1/bulk/movies/batches?limit=20&page=1 \ 
--header 'GN-APIKEY: your-api-key'

Use the batch GnID to check the status of a specific batch.

Example

Code
 
curl --location 'https://gnids.gracenote.com/api/v1/bulk/movies/batches/GNLZZJ300000001' \
 --header 'GN-APIKEY: your-api-key' 

Get Publishing Status

GN IDS provides a status for each registered program to indicate its state in the publishing process (see the table below). Registered data remains private until it is published.

Status	Description
Registered	This is the default state after successful registration. You can add the program to other Catalogs you create for data delivery to select Gracenote licensees.
Publish Requested	The program is queued for publishing. This is the default state after a valid Publish request has been accepted.
Publishing	The system is now acting upon the program successfully submitted for publishing.
Publish Exception	We were not able to publish or associate the program. Details are provided.
Published	The program is successfully published and mapped and is available in the Gracenote dataset.

To get the status of all published programs, use the GET api/v1/publications method.

Request

Code
 
curl --location 'https://gnids.gracenote.com/api/v1/publications?limit=10&page=1' \
  --header 'GN-APIKEY: your-api-key' 

Response

Code
 
{
   "meta":{
      "count":10,
      "rayID":"1258b82f-4d15-4807-9094-f7f53b99a00c",
      "limit":10,
      "page":1,
      "total":53
   },
   "data":[
      {
         "gnID":"GNLZZXW0000006G",
         "type":"movie",
         "title":{
            "value":"Soul",
            "language":"en"
         },
         "publishingStatus":"publishing",
         "tmsID":null,
         "updated":"2023-06-13T16:06:15.016Z"
      },
      {
         "gnID":"GNLZZXZ00000W15",
         "type":"episode",
         "title":{
            "value":"Dogs to a Gunfight",
            "language":"en"
         },
         "publishingStatus":"published",
         "tmsID":"EP021381820015",
         "updated":"2023-03-23T01:05:49.026Z"
      }
   ]
}