The Program Availabilities endpoint provides access to programming information for various online streaming providers like Amazon, Hulu etc., including their pricing and availability information. This dataset is also called Online Video Data (OVD).
Once licensed, the programs (TMSIds) referenced in the catalogs will be available in the Programs endpoint as well. And information about the streaming provider will be available on the Stations endpoint.
Program Availabilities provide the most up-to-date information on online video availability and enables universal search along with other compelling consumer applications more quickly and reliably with one data feed rather than dealing with the complexity of accessing and validating data from multiple partners. The Gracenote consolidated video data is synchronized with the Gracenote Unique ID for ease of integration with most major industry datasets.
Future Availability
For some video assets, Gracenote provides availability information in advance of the actual availability date. Use the <availableFromDateTime> field to determine when a video will be available in the future. In the example below, the actual availability date is 2025-04-15T00:50:00Z, but the information was provided several days before (2025-04-12T00:00:00Z).
Code
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 availabilities modified at or after updateId |
| limit | No | Batch size. Maximum number of program availabilities to be returned, to be used in conjunction with updateId to specify batch size |
| tmsId | No | For non-batch lookups. 14-char format tmsId. Accepts comma-separated list of TMSIds |
Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
Example Request
Return Program Availabilities for programAvailabilityId GNBBPAPA5BR8XF7. Using the providerId 1356240784 will return the same results.
Code
Example Response
See Program Availability XML examples
Data Structure and Relationships
XML Schema URL: http://files.api.gracenote.com/xsd/on_update_programAvailabilities_3.24.xsd
The XPATH in the tables below is relative to: on/programAvailabilities/programAvailability
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| @availabilityId | Identifier for the program availability | GN3DGTJ7BCV2WPD |
| catalogName | Name of the streaming catalog | Amazon PV US |
| availableFromDateTime | Optional availability window start date | 2022-11-11T00:00:00Z |
| expiresAtDateTime | Optional availability window expiration date | 3333-01-01T00:00:00Z |
The availabilityId uniquely identifies a catalog + Gracenote TMSId + videoQuality (see Viewing Options below). Availability window dates/times may or may not be present, depending on the catalog and specific assets. Assets with availability window are only present in the API during the availability window - with the exception of programs typed Sports event, which can be present ahead of the stated availability window.
Identifiers and Deeplinks
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| ids/id | Identifier associated with the asset | EP013898090001, 8553064, amzn1.dv.gti.a1b50383-d60a-4296-a6bd-ae3013ca6c82 |
| ids/id/@type | Identifier type | tmsId, rootId, prgSvcId, providerId |
| urls/url | URL associated with the asset | http://www.amazon.com/gp/product/B0B8NBP1WV |
| urls/url/@type | URL type | web, ios, android, android_tv, stb, tizen, webos |
The identifier section includes Gracenote and provider identifiers. Gracenote identifiers are: Program TMSId and rootId, as well as Source prgSvcId (identifies a catalog). For additional information on Gracenote identifiers, please refer to the corresponding section - Programs Endpoint or Sources Endpoint. Provider identifiers consist of at least an asset providerId but can also include other (e.g. season or series level) identifiers.
Multiple assets can be assigned the same Gracenote TMSId - but not vice versa i.e. each asset will only have one assigned TMSId.
Deep links of the type web are included for all catalogs. Deep links for other device types may or may not be included depending on the provider.
Viewing Options
The XPATH in the table below is relative to: on/programAvailabilities/programAvailability/viewingOptions/viewingOption
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| license | Video asset acquisition/payment method | purchase, subscription, rental, authentication, free |
| price | Video asset purchase/rental price | 3.99 |
| price/@currency | Video asset price currency | USD, CAD, EUR, GBP, ... |
| videoQuality | Video asset video quality | SD, HD, HD+, UHD |
The Viewing Options are available for watchable assets (movies, episodes), but not for series.
Provider Data
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| providerData/datum/key | Video asset provider specific data key | createdAtDate, p_rating, colorspace, show_id, season_id, airtime, ovd_image_url |
| providerData/datum/value | Video asset provider specific data value | 2022-12-28 06:51:06 UTC, 18+, SDR, ... |
The provider data key/values are optional passthrough data from the provider, not edited by Gracenote except for keys being normalized against a CV. The availability and coverage of specific keys is provider-dependent and varies greatly - some keys are only available for single catalogs. For the list of provider data keys, please refer to the below Referenced CV Lists table.
Referenced CV Lists
| Key | Values (description) |
|---|---|
| id@type | tmsId, rootId, prgSvcId, (Gracenote identifiers) providerId, providerSeriesId, providerSeasonId (provider identifiers) |
| url@type | web, ios, android, … |
| license | free, rental, purchase, subscription, authentication (via cable provider) |
| videoQuality | SD, HD, HD+, UHD |
| providerData keys | createdAtDate (Gracenote asset record creation timestamp), airtime (event/video start time according to provider), p_rating (parental rating according to provider, w/o rating body), show_id, season_id (provider identifiers for series/season parent),original_content (boolean flag, according to provider) ovd_image_url (single provider image, passthrough - not curated by GN), colorSpace (color dynamic range from provider - SDR |
The Supplemental Controlled Vocabulary (auto-download) provides more comprehensive descriptions and examples for Availability-related lists.
Data Attributes in the Program Availabilities Dataset
Consistent with audience popularity, the majority of content covered by the Program Availabilities dataset is comprised of high-quality long form content available on major streaming provider catalogs.
Short-form content (such as, previews, interviews, movie trailers, etc.), music videos, sports, instructional, and user-generated content are not currently covered by the Program Availabilities dataset.
Online videos can be available on a number of platforms and devices for end viewer consumption. Gracenote understands that partners use Gracenote data to power experiences on a wide variety of devices and provides links for the following platforms for available catalogs:
- Standard Web URL
- iOS
- Android
- Dedicated Set Top Box
- Connected Device/SmartTV
Playability by platform is subject to change. Mobile playability may vary by device.
Host Logo Types
The Program Availabilities delivers image references for individual host logos. Host logos are available in four types. You should download the host logos and resize them as needed for your specific application.
| Type | Description |
|---|---|
| Alpha Light | 1076x720 pixels, PNG, transparent background, suitable for light backgrounds |
| Alpha Dark | 1076x720 pixels, PNG, transparent background, suitable for dark backgrounds |
| Solid Light | 1076x720 pixels, PNG, solid white background, suitable for light backgrounds |
| Solid Dark | 1076x720 pixels, PNG, solid black background, suitable for dark backgrounds |
Alpha Light
Alpha Dark
Solid Light
Solid Dark
Entity Relationship Diagram
The ProgramAvailabilities endpoint works in conjunction with the Programs endpoint. The ProgramAvailabilities endpoint contains the links between TMSIds and provider asset identifiers, the Programs endpoint includes the actual metadata for all referenced TMSIds, including Series records for any referenced Episodes.
