Program Annotations Endpoint

The Program Annotations endpoint supports the Program Video Descriptors feature. Typically, most programs are annotated with 20-30 video descriptors, but this can vary depending on the content. For example, a documentary movie may be lightly tagged compared to a live-action franchise movie based on a comic book. Within each Video Descriptor type, there can be anywhere from 1-5 video descriptors each. Specifically for Series, tagging is done at a show level covering over-arching descriptors across seasons and episodes.

For certain genres of programs, some types may not be relevant. In such cases, video descriptors from that type will not be present. See Video Descriptor Coverage.

Each Program, identified by its TmsId, is annotated with Video Descriptors. The Program Annotations API provides the ID of the video descriptor. For each program object, Video Descriptors are grouped by video descriptor type. Within each video descriptor type, the video descriptors are sorted by descending order of importance. That is, the most important video descriptor for a given type appears first with ordinal number 1, followed by the next important video descriptor with ordinal number 2, and so on.

API Reference

Base URL:

Code
 
http://on-api.gracenote.com/v3/ProgramAnnotations

Parameters:

• updateId=<updateId value>
• limit=<limit value>
• api_key=<your-api-key>

Request Parameters

Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.

Example Requests

Return full program annotation set in batches of 1000 programs:

Code
 
http://on-api.gracenote.com/v3/ProgramAnnotations?updateId=0&limit=1000&api_key=

Return Program Annotations data for set of TMSIds:

Code
 
http://on-api.gracenote.com/v3/ProgramAnnotations?tmsId=MV010087880000,MV010021180981&api_key=123456789

Example Response

See Program Annotation XML examples

Identifying a Deleted Program Annotation

When a Program Annotation contains "deleted=true", it indicates that this annotation is no longer valid and can be deleted from your databases. For more information see Removals (Object Deletion / Inactivation).

Data Structure and Relationships

XML Schema URL: http://files.api.gracenote.com/xsd/on_update_programAnnotations_3.24.xsd

Unless stated otherwise, the XPATH in the tables below is relative to: on/programAnnotations/programAnnotation

The order of descriptor assignments to the program is arbitrary and does not imply importance.

Entity Relationship Diagram

The ProgramAnnotations endpoint works in conjunction with the Programs endpoint and VideoDescriptorsTaxonomy endpoint.