### Organizations Endpoint Example Request (Full List)

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Organizations.htm

An example HTTP request to retrieve the full list of organizations from the legacy endpoint. This request omits optional parameters to fetch all available organizations.

```http
http://on-api.gracenote.com/v3/Organization?api_key=<your-api-key>
```

--------------------------------

### Example Request for Video Descriptor Taxonomy Data

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Video%20Descriptors%20Taxonomy%20Endpoint.htm

An example HTTP request to retrieve Video Descriptor Taxonomy data. This demonstrates how to use the `updateID` and `limit` parameters to fetch a specified batch of taxonomy data, along with the API key for authentication.

```HTTP
http://on-api.gracenote.com/v3/VideoDescriptorsTaxonomy?updateID=0&limit=7&api_key=<your-api-key>
```

--------------------------------

### XML Schema Example for Video Descriptors Taxonomy

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Video%20Descriptors%20Taxonomy%20Endpoint.htm

This snippet shows an example of the XML structure for a taxonomy item within the Video Descriptors Taxonomy endpoint. It includes details like videoDescriptorId, videoDescriptorName, and type information.

```xml
  <taxonomyItem updateId="0" updateDate="2024-03-14T22:10:40Z">
    <videoDescriptors>
        <videoDescriptor>
            <videoDescriptorId>GN7ZZYX4F3NN90Y</videoDescriptorId>
            <videoDescriptorName>ABBA</videoDescriptorName>
            <videoDescriptorParentId>GNB8TG1727QECG3</videoDescriptorParentId>
            <typeId>GN5K25Z6A1Y4TYJ</typeId>
            <typeName>Subject - Specific Being / Group</typeName>
        </videoDescriptor>
    </videoDescriptors>
  </taxonomyItem>
```

--------------------------------

### SourcePrograms Data Structure and Example Response

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/GN%20IDS%20SourcePrograms%20Endpoint.htm

This snippet provides an example XML response for the SourcePrograms endpoint and details on how to understand its data structure and relationships.

```APIDOC
## SourcePrograms API Endpoint

### Description
This endpoint provides information about source programs, including details like program ID, titles, descriptions, genres, and crew information. It is designed to return data in an XML format.

### Method
GET

### Endpoint
/websites/gracenote_on-api_html/sourcePrograms

### Parameters
#### Query Parameters
- **id** (string) - Required - The unique identifier for the program to retrieve.

### Request Example
```
GET /websites/gracenote_on-api_html/sourcePrograms?id=GNLZZXW0000004R
```

### Response
#### Success Response (200)
- **on** (object) - The root element containing program data.
  - **header** (object) - Contains metadata about the request and response.
  - **programs** (object) - Contains a list of program objects.
    - **program** (object) - Represents a single program.
      - **id** (string) - The Gracenote ID for the program.
      - **TMSId** (string) - The TMS ID for the program.
      - **updateId** (string) - The update identifier.
      - **updateDate** (string) - The date of the last update.
      - **deleted** (boolean) - Indicates if the program has been deleted.
      - **sourceDataProvider** (object) - Information about the data provider.
      - **externalIds** (object) - A list of external identifiers.
      - **versionInfo** (object) - Details about the program version.
      - **titles** (object) - A list of titles for the program.
      - **descriptions** (object) - A list of descriptions for the program.
      - **progType** (string) - The type of program.
      - **subType** (string) - The subtype of the program.
      - **genres** (object) - A list of genres associated with the program.
      - **yearOfRelease** (integer) - The year the program was released.
      - **releases** (object) - Information about program releases.
      - **countries** (object) - A list of countries associated with the program.
      - **productionStatus** (string) - The production status of the program.
      - **ratings** (object) - A list of ratings for the program.
      - **crew** (object) - A list of crew members involved in the program.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8" ?>
<on xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://files.api.gracenote.com/xsd/on_update_source_programs_3.26.xsd"
    schemaVersion="3.20">
    <header>
        <content>On - Updates: SourcePrograms</content>
        <created>2025-02-17T18:56:21Z</created>
        <copyright>Copyright 2025 Gracenote, a Nielsen Company. All rights reserved.</copyright>
        <requestParameters>
            <requestParameter name="id">GNLZZXW0000004R</requestParameter>
        </requestParameters>
    </header>
    <programs>
        <program id="GNLZZXW0000004R"
                 TMSId="MV016377830000"
                 updateId="5205415154"
                 updateDate="2023-05-02T22:15:15Z"
                 deleted="true">
            <sourceDataProvider>
                <id>GNLZZZ40000003Y</id>
                <name>Internal GN IDS Trial</name>
            </sourceDataProvider>
            <externalIds>
                <externalId primary="true"
                            provider="true"
                            label="MV016377830000">69274</externalId>
            </externalIds>
            <versionInfo>
                <labels>
                    <label>Original</label>
                </labels>
                <releaseDate>2022-02-09</releaseDate>
                <colorCode>color</colorCode>
                <duration>600000</duration>
                <presentationLabels>
                    <presentationLabel> Original ES</presentationLabel>
                </presentationLabels>
            </versionInfo>
            <titles>
                <title lang="en">Crescendo!</title>
            </titles>
            <descriptions>
                <desc size="250"
                      lang="en">From a young age, Michael Fabiano was told he wasn't good enough. Now, a global talent, Michael reflects on a journey that led him to find stardom, and love, inside New York City's Metropolitan Opera.</desc>
                <desc size="100"
                      lang="en">Michael Fabiano reflects on his journey as an operatic tenor.</desc>
                <desc size="60"
                      lang="en">Opera singer Michael Fabiano finds his voice.</desc>
            </descriptions>
            <progType>movie</progType>
            <subType>shortFilm</subType>
            <genres>
                <genre>DOCUMENTARY</genre>
                <genre>MUSIC</genre>
                <genre>GAY/LESBIAN</genre>
            </genres>
            <yearOfRelease>2020</yearOfRelease>
            <releases>
                <release>
                    <date>2022-02-09</date>
                </release>
            </releases>
            <countries>
                <country>US</country>
            </countries>
            <productionStatus>completed</productionStatus>
            <ratings>
                <rating code="TVPG"
                        ratingsBody="USA PARENTAL RATING">
                </rating>
            </ratings>
            <crew>
                <member ord="01">
                    <name>
                        <first>Alex</first>
                        <last>Mallis</last>
                    </name>
                </member>
                <member ord="02">
                    <name>
                        <first>Matt</first>
                        <last>O'Neill</last>
                    </name>
                </member>
                <member ord="03">
                    <name>
                        <first>Perri</first>
                        <last>Peltz</last>
                    </name>
                </member>
                <member ord="04">
                    <name>
                        <first>Eliot</first>
                        <last>Krimsky</last>
                    </name>
                </member>
            </crew>
        </program>
    </programs>
</on>
```

### Schema Information
For detailed information about the SourcePrograms data structure and its relationships, refer to the Gracenote ID Distribution System documentation and the provided XML Schema Definition (XSD) URL: http://files.api.gracenote.com/xsd/on_update_source_programs_3.26.xsd
```

--------------------------------

### On API Controlled Vocabulary Endpoint Request Example

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Data%20Dictionaries%20and%20Controlled.htm

This example demonstrates how to make a request to the On API's Controlled Vocabulary endpoint. It includes essential parameters such as the API key, updateId for incremental updates, and limit for batch size. The response is in XML format and contains header information and the controlled vocabulary data.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<on xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://files.api.gracenote.com/xsd/on_update_controlledVocabularies_3.26.xsd" schemaVersion="3.26">
  <header>
    <content>On - Updates: controlled vocabulary</content>
    <created>2026-02-18T19:32:07Z</created>
    <copyright>Copyright 2026 Gracenote, a Nielsen Company. All rights reserved.</copyright>
    <requestParameters>
      <requestParameter name="updateId">0</requestParameter>
      <requestParameter name="limit">1</requestParameter>
    </requestParameters>
    <streamData>
      <nextUpdateId>2802721390</nextUpdateId>
      <maxUpdateId>8095410870</maxUpdateId>
    </streamData>
  </header>
  <controlledVocabularies>
    <controlledVocabulary cvId="ADV1" objectType="RatingAdvisory" updateId="2802715600" updateDate="2020-12-29T10:15:11Z">
      <id>1</id>
      <lang>en</lang>
      <value>FV</value>
    </controlledVocabulary>
  </controlledVocabularies>
</on>
```

--------------------------------

### Video Popularity API Endpoint and Example Request

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Video%20Popularity%20Endpoint.htm

This snippet shows the base URL for the Video Popularity API and an example of a GET request. It includes parameters like api_key, limit, and tmsId for querying popularity scores. The API is used for program search and discovery.

```HTTP
http://on-api.gracenote.com/v3/VideoPopularity?limit=1&api_key=<your-api-key>&tmsId=SH014483860000
```

--------------------------------

### Exact Start and Duration Data

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Schedules%20Endpoint.htm

Explains the 'exactStart' and 'exactDuration' fields, their sources, and how Media Distillery data overwrites Broadcaster data.

```APIDOC
## Exact Start and Duration

### Description
Exact start time and exact duration values are exposed as available for entitled clients. These fields identify when a linear program truly aired and how long it aired. The values may be different from the published start time and duration of the program.

### Data Sources
The `exactSource` attribute can have two different values:

*   **Broadcaster**: These are the exact start and duration values provided by the source (broadcaster) to Gracenote.
*   **Media Distillery**: These are the exact start and duration values provided by an EPG correction service. This is an additional service available from Gracenote.

### Data Overwriting Rules
If you are entitled to Media Distillery data, Media Distillery data overwrites Broadcaster-provided data if both are available on a channel. The sample data below has both Broadcaster and Media Distillery data.

### Example Response Snippet (Illustrative)
```json
{
  "programs": [
    {
      "title": "Sample Program",
      "publishedStartTime": "2023-10-27T20:00:00Z",
      "publishedDurationMinutes": 60,
      "exactStart": "2023-10-27T20:01:30Z",
      "exactDurationMinutes": 58,
      "exactSource": "Media Distillery"
    }
  ]
}
```
```

--------------------------------

### Retrieve Lineups by Headend ID

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Lineups%20Endpoint.htm

Example of retrieving all lineups available for a single specific headend ID.

```APIDOC
## GET /v3/Lineups

### Description
Retrieve all lineups available for a single specific headend ID.

### Method
GET

### Endpoint
`http://on-api.gracenote.com/v3/Lineups?headend=USA-SC39419&api_key=123456`

### Parameters
#### Query Parameters
- **headend** (string) - Required - Gracenote unique ID of the headend.
- **api_key** (string) - Required - Your API key

### Best Practices
  * Use a headend value retired from your complete update method.
  * Be aware that your specific API key and entitlement will have constraints on the available headends/lineups.
```

--------------------------------

### GET /lineups

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Lineups%20Endpoint.htm

Retrieves channel lineup information including MSO details, headend locations, and market data.

```APIDOC
## GET /lineups

### Description
Retrieves a list of channel lineups available in the Gracenote database. This endpoint provides metadata about the lineup, including the MSO, headend, and geographic coverage.

### Method
GET

### Endpoint
/lineups

### Parameters
#### Query Parameters
- **country** (string) - Optional - ISO 3166-1 alpha-3 country code to filter lineups.
- **postalCode** (string) - Optional - Filter lineups by specific postal code.

### Request Example
GET /lineups?country=USA&postalCode=94014

### Response
#### Success Response (200)
- **lineupId** (string) - Gracenote unique identifier of a channel lineup.
- **lineupInfo/mso** (string) - MSO (multiple system operator) name.
- **lineupInfo/headend** (string) - Name of the headend serving the channel lineup.

#### Response Example
<on>
  <lineups>
    <lineup id="USA-CA00056-X">
      <lineupInfo>
        <mso msoId="8010">Comcast Corporation</mso>
        <headend headendId="USA-CA00056">Xfinity</headend>
      </lineupInfo>
    </lineup>
  </lineups>
</on>
```

--------------------------------

### Retrieve a Single Lineup by ID

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Lineups%20Endpoint.htm

Example of retrieving a single lineup for a specific lineup ID.

```APIDOC
## GET /v3/Lineups

### Description
Retrieve a single lineup for a specific lineup ID.

### Method
GET

### Endpoint
`http://on-api.gracenote.com/v3/Lineups?id=USA-NY31579-X&api_key=123456`

### Parameters
#### Query Parameters
- **id** (string) - Required - Gracenote unique ID of a channel lineup.
- **api_key** (string) - Required - Your API key

### Best Practices
  * Use a lineup ID value retired from your complete update method.
  * Be aware that your specific API key and entitlement will have constraints on the available lineups.
```

--------------------------------

### Retrieve Lineups by Country and Postal Code

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Lineups%20Endpoint.htm

Example of retrieving all lineups available for a single specific country and postal code.

```APIDOC
## GET /v3/Lineups

### Description
Retrieve all lineups available for a single specific country and postal code.

### Method
GET

### Endpoint
`http://on-api.gracenote.com/v3/Lineups?country=USA&postalCode=12804&api_key=123456`

### Parameters
#### Query Parameters
- **country** (string) - Required - Country in which the lineups are located. Use the three character country value as based on the IETF BCP 47 standard.
- **postalCode** (string) - Required - Individual, country specific postal code where this lineup is available.
- **api_key** (string) - Required - Your API key

### Best Practices
  * Use a proper 3-character country code from the IETF BCP 47 standard.
  * Use a properly formatted country postal code.
  * Be aware that your specific API key and entitlement will have constraints on the available countries/postal codes/lineups.
```

--------------------------------

### GET /v3/Sources

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Sources%20Endpoint.htm

Retrieves Gracenote programming service information, including station details and broadcast attributes.

```APIDOC
## GET /v3/Sources

### Description
Retrieves a list of programming services based on specified criteria such as updateId or service IDs. This endpoint is used to maintain local copies of station metadata and supports delta updates.

### Method
GET

### Endpoint
http://on-api.gracenote.com/v3/Sources

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your client assigned API key.
- **updateId** (string) - Optional - Returns programming services modified at or after this updateId.
- **limit** (integer) - Optional - Batch size; maximum number of programming services to return.
- **prgSvcId** (string) - Optional - Comma-separated list of programming service IDs for non-batch lookups.

### Request Example
GET http://on-api.gracenote.com/v3/Sources?api_key=YOUR_KEY&updateId=12345&limit=100

### Response
#### Success Response (200)
- **prgSvcId** (string) - Gracenote unique identifier for a programming service.
- **name** (string) - Name of the programming service.
- **callSign** (string) - Call sign of the programming service.
- **timeZone** (string) - Time zone that the station is edited in.
- **videoQuality** (string) - Transmission signal type used by the service.

#### Response Example
<on>
  <sources>
    <prgSvcs>
      <prgSvc prgSvcId="20459">
        <name>WNBC-DT</name>
        <callSign>WNBCDT</callSign>
      </prgSvc>
    </prgSvcs>
  </sources>
</on>
```

--------------------------------

### Program Record Structure for Derivative Content

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Programs%20Endpoint.htm

Example of the XML structure for a program record including the predecessorId attribute used for remapping during content migration.

```xml
<program TMSId="EP014661780001" rootId="8847163" connectorId="SH014661780000" seasonId="8838315" seriesId="8807210" updateId="6686055526" updateDate="2024-08-10T13:49:15Z">
  <predecessorId>EPxxxxxxxxxxx</predecessorId>
  <titles>
  ...
</program>
```

--------------------------------

### GET /seed-files

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Getting%20Seed%20Files.htm

Retrieves bulk data files for database seeding, including XML data, signature files, and manifest files.

```APIDOC
## GET /seed-files

### Description
Retrieves a batch of seed data files used for initial database seeding, disaster recovery, or periodic refreshing. Files are delivered via SFTP or S3.

### Method
GET

### Endpoint
/seed-files

### Parameters
#### Query Parameters
- **frequency** (string) - Optional - The requested frequency of the batch (e.g., weekly).

### Request Example
GET /seed-files?frequency=weekly

### Response
#### Success Response (200)
- **manifest.xml** (file) - Outlines files in the batch, maxUpdateIds, and record counts.
- **[endpoint].xml.gz** (file) - Gzipped XML data containing entitled endpoint data.
- **[endpoint].xml.gz.sig** (file) - MD5 checksum signature for file integrity verification.

#### Response Example
{
  "batch_id": "20231027_0000000001",
  "files": [
    "movies.xml.gz",
    "movies.xml.gz.sig",
    "manifest.xml"
  ]
}
```

--------------------------------

### GET /programs/metadata

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Programs%20Endpoint.htm

Retrieves detailed program metadata including video descriptors, air dates, and runtime information.

```APIDOC
## GET /programs/metadata

### Description
Retrieves the core metadata for a program, including video descriptors, original air dates, and duration information.

### Method
GET

### Endpoint
/programs/metadata

### Parameters
#### Query Parameters
- **tmsId** (string) - Required - The unique Gracenote identifier for the program.

### Request Example
GET /programs/metadata?tmsId=12345

### Response
#### Success Response (200)
- **videoDescriptors** (object) - List of assigned descriptors.
- **origAirDate** (string) - Original air date of the program.
- **runTime** (string) - ISO-8601 duration format.

#### Response Example
{
  "videoDescriptors": {
    "id": "GN5ME6XVY48S4HS",
    "weight": 9
  },
  "origAirDate": "1994-09-22",
  "runTime": "PT01H30M"
}
```

--------------------------------

### Define ContentType in XML

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Sports%20Endpoints.htm

Example of how to structure the ContentType metadata within an XML program element. This demonstrates the inclusion of titles, descriptions, and genre classifications.

```xml
<program TMSId="SH020913400000" rootId="11368193" …>
<titles lang="en">
<title size="120" type="full" subType="Main" lang="en">NHL in 30</title>
</titles>
<descriptions lang="en">
<desc size="250" type="generic" lang="en">Replays of NHL contests in a shortened duration.</desc>
</descriptions>
<progType>Sports non-event</progType>
<subType>Series</subType>
<contentType>Highlights</contentType>
<genres>
<genre genreId="122">Hockey</genre>
</genres>
```

--------------------------------

### Dynamic Image Resizing with Media Cloud API

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Media%20Cloud%20Images.htm

Demonstrates how to resize images on-the-fly using query parameters 'h' for height or 'w' for width. Only one parameter (either 'h' or 'w') should be used to maintain aspect ratio; providing both will result in only the first being used. This can introduce latency.

```text
https://demo.tmsimg.com/assets/p184852_i_h2_ag.jpg?h=300
```

```text
https://demo.tmsimg.com/assets/p184852_i_h2_ag.jpg?w=400
```

--------------------------------

### SportsEvents API Request Example

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/SportsEvents.htm

This snippet shows a basic GET request to the SportsEvents endpoint, demonstrating how to specify updateId, limit, and api_key parameters. It's used to retrieve a list of sports events.

```http
http://on-api.gracenote.com/v3/SportsEvents?updateId=0&limit=1000&api_key=<your-api-key>
```

--------------------------------

### Dynamic Image Resizing

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Media%20Cloud%20Images.htm

Details how to resize images on-the-fly by appending query parameters to the image URL.

```APIDOC
## Dynamic Image Resizing

### Description
Media Cloud supports dynamic resizing of images. You can specify either the desired width (w) or height (h) to obtain a resized image. Providing both parameters is not supported and only the first one will be considered. Note that dynamic resizing may introduce latency.

### Method
GET

### Endpoint
`https://<ClientSubdomain>.tmsimg.com/<image URI>?h=<height>` or `https://<ClientSubdomain>.tmsimg.com/<image URI>?w=<width>`

### Parameters
#### Query Parameters
- **h** (integer) - Optional - The desired height in pixels for the resized image.
- **w** (integer) - Optional - The desired width in pixels for the resized image.

### Request Example
```
https://demo.tmsimg.com/assets/p184852_i_h2_ag.jpg?h=300
https://demo.tmsimg.com/assets/p184852_i_h2_ag.jpg?w=400
```

### Response
#### Success Response (200)
Returns the resized image content.

#### Response Example
(Resized image binary data)
```

--------------------------------

### Lookup Specific Program Mappings

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Program%20Mappings%20Endpoint.htm

Demonstrates how to perform non-batch lookups for specific program mapping IDs. Note that these lookup calls are intended for QA and troubleshooting purposes only.

```HTTP
GET http://on-api.gracenote.com/v3/ProgramMappings?programMappingId=28732938,2398237&api_key=<your-api-key>
```

--------------------------------

### GET /series-hierarchy

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Programs%20Endpoint.htm

Retrieves the structural relationship between series, seasons, and episodes using Gracenote identifiers.

```APIDOC
## GET /series-hierarchy

### Description
Retrieves the hierarchy mapping for programs, showing how episodes link to series via connectorId, seriesId, and seasonId. This endpoint helps in reconstructing the show structure for specific language variants.

### Method
GET

### Endpoint
/series-hierarchy

### Parameters
#### Query Parameters
- **rootId** (string) - Optional - The root identifier for the series.
- **seriesId** (string) - Optional - The specific series identifier.
- **language** (string) - Optional - The language variant for the series metadata.

### Request Example
{
  "seriesId": "SH001151270000"
}

### Response
#### Success Response (200)
- **TMSId** (string) - Unique identifier for the program.
- **connectorId** (string) - Links the episode to the series variant.
- **seriesId** (string) - The parent series identifier.
- **seasonId** (string) - The identifier for the specific season.
- **title** (string) - The title of the episode or series.

#### Response Example
{
  "TMSId": "EP001151270001",
  "connectorId": "SH001151270000",
  "seriesId": "183931",
  "seasonId": "7892576",
  "title": "Pilot"
}
```

--------------------------------

### Retrieve Program Annotations via API

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Program%20Annotations%20Endpoint.htm

Examples of how to construct HTTP requests for the Program Annotations endpoint. This includes batch retrieval using updateId and specific program lookups using TmsId.

```http
GET http://on-api.gracenote.com/v3/ProgramAnnotations?updateId=0&limit=1000&api_key=<your-api-key>
```

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

--------------------------------

### GET /sports

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Sports%20Endpoints.htm

Retrieves comprehensive sports metadata for integrated sports and video content experiences.

```APIDOC
## GET /sports

### Description
Retrieves metadata for sports, enabling the integration of sports data with video content to drive audience engagement.

### Method
GET

### Endpoint
/sports

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your Gracenote API subscription key.

### Request Example
GET /sports?api_key=your_api_key

### Response
#### Success Response (200)
- **sports** (array) - List of sports metadata objects.

#### Response Example
{
  "sports": [
    {
      "sport_id": "123",
      "name": "Basketball"
    }
  ]
}
```

--------------------------------

### GET /v3/University

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Universities.htm

Retrieves a list of universities or specific university records based on provided parameters.

```APIDOC
## GET /v3/University

### Description
Retrieves collegiate metadata, imagery, and address details. This endpoint supports batching for large datasets and specific lookups for troubleshooting.

### Method
GET

### Endpoint
http://on-api.gracenote.com/v3/University

### Parameters
#### Query Parameters
- **api_key** (string) - Required - 24-character key obtained during application registration.
- **updateId** (integer) - Optional - Update token. Defaults to 0. Returns teams beginning with this sequential numeric offset.
- **limit** (integer) - Optional - Batch size. Maximum number of universities to be returned.
- **universityId** (string) - Optional - Comma-separated list of university IDs for specific lookups.

### Request Example
http://on-api.gracenote.com/v3/University?api_key=<your-api-key>

### Response
#### Success Response (200)
- **id** (integer) - Unique numeric ID of the university.
- **name** (string) - Name of the university.
- **lastUpdDate** (string) - Last modification timestamp.
- **assets** (array) - List of university logos.
- **universityGId** (string) - Unique identifier for the university record.
- **names** (array) - List of names with language and type attributes.
- **address** (object) - Address details including city, state, and country.

#### Response Example
{
  "id": 12345,
  "name": "Example University",
  "lastUpdDate": "2023-10-27T10:00:00Z",
  "assets": ["logo_url_1", "logo_url_2"]
}
```

--------------------------------

### Return Full Program Set in Batches

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Programs%20Endpoint.htm

This endpoint allows you to retrieve the full program set in manageable batches. It uses the `updateId` parameter to paginate through updates, ensuring you can retrieve all program data efficiently.

```APIDOC
## GET /v3/Programs

### Description
Retrieves a batch of program data, typically used for fetching updates or a large dataset in chunks. The `limit` parameter controls the batch size.

### Method
GET

### Endpoint
/v3/Programs

### Query Parameters
- **updateId** (string) - Required - The identifier for the update batch. Use '0' for the initial request.
- **limit** (integer) - Required - The maximum number of items to return in this batch (e.g., 1000).
- **api_key** (string) - Required - Your Gracenote API key.

### Request Example
```
http://on-api.gracenote.com/v3/Programs?updateId=0&limit=1000&api_key=<your-api-key>
```

### Response
#### Success Response (200)
- **programs** (array) - A list of program objects.
- **nextUpdateId** (string) - The updateId to use for fetching the next batch.

#### Response Example
```json
{
  "programs": [
    { ... program data ... },
    { ... program data ... }
  ],
  "nextUpdateId": "12345"
}
```
```

--------------------------------

### Image Types Reference

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Image%20Types.htm

This section details the different image types supported by the API, their characteristics, and examples.

```APIDOC
## Image Types Reference

This document outlines the various image types available through the Gracenote On API. Each image type has specific properties, valid use cases, and associated metadata.

### Image Type Details

| Image Type      | Valid for                                                                 | Has Title Text | Description
```

--------------------------------

### GET /programs/sports-events

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Programs%20Endpoint.htm

Retrieves sports-specific metadata including event timing, venue details, and team information.

```APIDOC
## GET /programs/sports-events

### Description
Retrieves detailed information about sports events, including game time, venue, and participating teams.

### Method
GET

### Endpoint
/programs/sports-events

### Parameters
#### Query Parameters
- **eventId** (string) - Required - The Gracenote Sports Connected event identifier.

### Request Example
GET /programs/sports-events?eventId=GNAK4TXGHDSJNQV

### Response
#### Success Response (200)
- **sportsInfo** (object) - Contains gameDate, venue, and team details.

#### Response Example
{
  "sportsInfo": {
    "gameDate": "2024-01-20",
    "venue": "Levi's Stadium",
    "team": {
      "name": "San Francisco 49ers",
      "isHome": true
    }
  }
}
```

--------------------------------

### Retrieve Program Mapping Batches via API

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Program%20Mappings%20Endpoint.htm

Demonstrates how to fetch program mapping updates in batches using the updateId and limit parameters. This is the primary method for synchronizing mapping data.

```HTTP
GET http://on-api.gracenote.com/v3/ProgramMappings?updateId=0&limit=1000&api_key=<your-api-key>
```

--------------------------------

### GET /v3/VideoDescriptorsTaxonomy

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Video%20Descriptors%20Taxonomy%20Endpoint.htm

Retrieves the Video Descriptor Taxonomy data, which defines the hierarchical relationship between video descriptors.

```APIDOC
## GET /v3/VideoDescriptorsTaxonomy

### Description
Retrieves the Video Descriptor Taxonomy data. This endpoint provides the hierarchical structure of video descriptors used for search and discovery.

### Method
GET

### Endpoint
http://on-api.gracenote.com/v3/VideoDescriptorsTaxonomy

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your Gracenote API key.
- **limit** (integer) - Optional - Limits the response to a specified number of Video Descriptor Types. Used with updateId.
- **typeId** (string) - Optional - GNID format ID for non-batch lookups. Returns all descriptors belonging to the specified type. Accepts comma-separated lists.
- **updateId** (string) - Optional - Unique update token used to retrieve taxonomy data at a type level. Returns a snapshot of keywords for the updated type.

### Request Example
http://on-api.gracenote.com/v3/VideoDescriptorsTaxonomy?updateID=0&limit=7&api_key=<your-api-key>

### Response
#### Success Response (200)
- **Taxonomy Data** (XML) - Returns the hierarchical structure of video descriptors including types and their underlying keywords.

#### Response Example
<VideoDescriptorsTaxonomy>
  <Type id="GNFMQH6ZGH1477N">
    <Keyword id="12345">Serious</Keyword>
  </Type>
</VideoDescriptorsTaxonomy>
```

--------------------------------

### GET /v3/Schedules

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Schedules%20Endpoint.htm

Retrieves schedule information including airing qualifiers, exact timing, and broadcast identifiers.

```APIDOC
## GET /v3/Schedules

### Description
Retrieves linear schedule data for programs, including technical qualifiers (HD, CC, Stereo), exact broadcast timing, and provider-specific broadcast identifiers.

### Method
GET

### Endpoint
http://on-api.gracenote.com/v3/Schedules

### Parameters
#### Query Parameters
- **updateId** (string) - Optional - The specific update identifier to filter results.
- **limit** (integer) - Optional - The maximum number of records to return.
- **api_key** (string) - Required - Your unique API authentication key.

### Request Example
GET http://on-api.gracenote.com/v3/Schedules?updateId=12345&limit=10&api_key=YOUR_API_KEY

### Response
#### Success Response (200)
- **event/quals** (string) - Pipe-delimited list of airing qualifiers (e.g., New|CC|HDTV).
- **event/@exactStartDateTime** (string) - The exact start datetime of a program in UTC.
- **event/@exactEndDateTime** (string) - The exact end datetime of a program in UTC.
- **event/broadcast/id** (string) - Broadcaster-specific identifier for the event.

#### Response Example
{
  "event": {
    "quals": "New|CC|HDTV",
    "exactStartDateTime": "2024-07-20T01:27:08Z",
    "exactEndDateTime": "2024-07-20T02:53:22Z",
    "broadcast": {
      "id": "2679283",
      "type": "remoteId"
    }
  }
}
```

--------------------------------

### Gracenote SourcePrograms XML Response Example

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/GN%20IDS%20SourcePrograms%20Endpoint.htm

This XML snippet demonstrates a typical response from the Gracenote On-API SourcePrograms endpoint. It includes header information, program details such as titles, descriptions, genres, release information, and crew data. The structure adheres to the specified XSD.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<on xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://files.api.gracenote.com/xsd/on_update_source_programs_3.26.xsd"
    schemaVersion="3.20">
    <header>
        <content>On - Updates: SourcePrograms</content>
        <created>2025-02-17T18:56:21Z</created>
        <copyright>Copyright 2025 Gracenote, a Nielsen Company. All rights reserved.</copyright>
        <requestParameters>
            <requestParameter name="id">GNLZZXW0000004R</requestParameter>
        </requestParameters>
    </header>
    <programs>
        <program id="GNLZZXW0000004R"
                 TMSId="MV016377830000"
                 updateId="5205415154"
                 updateDate="2023-05-02T22:15:15Z"
                 deleted="true">
            <sourceDataProvider>
                <id>GNLZZZ40000003Y</id>
                <name>Internal GN IDS Trial</name>
            </sourceDataProvider>
            <externalIds>
                <externalId primary="true"
                            provider="true"
                            label="MV016377830000">69274</externalId>
            </externalIds>
            <versionInfo>
                <labels>
                    <label>Original</label>
                </labels>
                <releaseDate>2022-02-09</releaseDate>
                <colorCode>color</colorCode>
                <duration>600000</duration>
                <presentationLabels>
                    <presentationLabel> Original ES</presentationLabel>
                </presentationLabels>
            </versionInfo>
            <titles>
                <title lang="en">Crescendo!</title>
            </titles>
            <descriptions>
                <desc size="250"
                      lang="en">From a young age, Michael Fabiano was told he wasn&apos;t good enough. Now, a global talent, Michael reflects on a journey that led him to find stardom, and love, inside New York City&apos;s Metropolitan Opera.</desc>
                <desc size="100"
                      lang="en">Michael Fabiano reflects on his journey as an operatic tenor.</desc>
                <desc size="60"
                      lang="en">Opera singer Michael Fabiano finds his voice.</desc>
            </descriptions>
            <progType>movie</progType>
            <subType>shortFilm</subType>
            <genres>
                <genre>DOCUMENTARY</genre>
                <genre>MUSIC</genre>
                <genre>GAY/LESBIAN</genre>
            </genres>
            <yearOfRelease>2020</yearOfRelease>
            <releases>
                <release>
                    <date>2022-02-09</date>
                </release>
            </releases>
            <countries>
                <country>US</country>
            </countries>
            <productionStatus>completed</productionStatus>
            <ratings>
                <rating code="TVPG"
                        ratingsBody="USA PARENTAL RATING">
</rating>
            </ratings>
            <crew>
                <member ord="01">
                    <name>
                        <first>Alex</first>
                        <last>Mallis</last>
                    </name>
                </member>
                <member ord="02">
                    <name>
                        <first>Matt</first>
                        <last>O&apos;Neill</last>
                    </name>
                </member>
                <member ord="03">
                    <name>
                        <first>Perri</first>
                        <last>Peltz</last>
                    </name>
                </member>
                <member ord="04">
                    <name>
                        <first>Eliot</first>
                        <last>Krimsky</last>
                    </name>
                </member>
            </crew>
        </program>
    </programs>
</on>
```

--------------------------------

### GET /v3/Teams

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Teams.htm

Retrieve a list of sports teams or specific team details using the Teams endpoint.

```APIDOC
## GET /v3/Teams

### Description
The Teams endpoint provides metadata and imagery for sports teams. It supports batch retrieval using updateId and limit, or specific lookups using teamId.

### Method
GET

### Endpoint
http://on-api.gracenote.com/v3/Teams

### Parameters
#### Query Parameters
- **api_key** (string) - Required - 24-character key obtained during application registration.
- **updateId** (integer) - Optional - Update token. Defaults to 0. Returns teams beginning with this sequential numeric offset.
- **limit** (integer) - Optional - Batch size. Maximum number of teams to be returned. Use with updateId.
- **teamId** (string) - Optional - Comma-separated list of teamIDs for non-batch lookups. Overrides updateId.

### Request Example
http://on-api.gracenote.com/v3/Teams?updateId=0&limit=1000&api_key=<your-api-key>

### Response
#### Success Response (200)
- **teamData** (object) - Contains fixed team block (country, gender, location) and active teamBrand block (names, logos).

#### Response Example
{
  "teams": [
    {
      "teamId": "12345",
      "teamBrand": {
        "name": "Brooklyn Nets",
        "abbreviation": "BKN"
      },
      "location": "Brooklyn"
    }
  ]
}
```

--------------------------------

### Image URL Construction

Source: https://documentation.gracenote.com/on-api/html/Content/dev-guide/Media%20Cloud%20Images.htm

Explains how to form the complete URL for an image by combining a client-specific subdomain with the image URI.

```APIDOC
## Image URL Construction

### Description
To retrieve image content, partial image paths provided by the API must be prefixed with a Media Cloud subdomain. This subdomain is provided by Gracenote.

### Method
GET

### Endpoint
`https://<ClientSubdomain>.tmsimg.com/<image URI>`

### Parameters
#### Path Parameters
- **ClientSubdomain** (string) - Required - Your unique Gracenote Media Cloud subdomain.
- **image URI** (string) - Required - The path to the image asset provided by the API.

### Request Example
```
https://<ClientSubdomain>.tmsimg.com/assets/p13755451_i_s4_af.jpg
```

### Response
#### Success Response (200)
Returns the image content.

#### Response Example
(Image binary data)
```

--------------------------------

### XML Schema Files (XSDs)

Source: https://documentation.gracenote.com/on-api/html/Content/on-api-schema-docs/xsds.htm

Download XML Schema Definition files for various components of the Gracenote ON API. These files define the structure and data types for XML requests and responses.

```APIDOC
## XML Schema Files (XSDs)

### Description
This section provides links to download the XML Schema Definition (XSD) files for the Gracenote ON API version 3.26. These files are essential for understanding and constructing valid XML requests and responses for the API.

### Download Options

*   **Batch Download:**
    *   Download all XSDs as a zip archive: [xsds.zip](http://files.api.gracenote.com/xsd/xsds.zip)

*   **Individual Downloads:**
    *   Celebrities: `http://files.api.gracenote.com/xsd/on_update_celebrities_3.26.xsd`
    *   Controlled Vocabularies: `http://files.api.gracenote.com/xsd/on_update_controlledVocabularies_3.26.xsd`
    *   Lineups: `http://files.api.gracenote.com/xsd/on_update_lineups_3.26.xsd`
    *   Organizations: `http://files.api.gracenote.com/xsd/on_update_organizations_3.26.xsd`
    *   Program Annotations: `http://files.api.gracenote.com/xsd/on_update_programAnnotations_3.26.xsd`
    *   Program Availabilities: `http://files.api.gracenote.com/xsd/on_update_programAvailabilities_3.26.xsd`
    *   Program Mappings: `http://files.api.gracenote.com/xsd/on_update_programmappings_3.26.xsd`
    *   Programs: `http://files.api.gracenote.com/xsd/on_update_programs_3.26.xsd`
    *   Schedules: `http://files.api.gracenote.com/xsd/on_update_schedules_3.26.xsd`
    *   Source Programs: `http://files.api.gracenote.com/xsd/on_update_source_programs_3.26.xsd`
    *   Sources: `http://files.api.gracenote.com/xsd/on_update_sources_3.26.xsd`
    *   Sports: `http://files.api.gracenote.com/xsd/on_update_sports_3.26.xsd`
    *   Sports Events: `http://files.api.gracenote.com/xsd/on_update_sports_events_3.26.xsd`
    *   Teams: `http://files.api.gracenote.com/xsd/on_update_teams_3.26.xsd`
    *   Universities: `http://files.api.gracenote.com/xsd/on_update_universities_3.26.xsd`
    *   Venues: `http://files.api.gracenote.com/xsd/on_update_venues_3.26.xsd`
    *   Video Descriptors Taxonomy: `http://files.api.gracenote.com/xsd/on_update_videoDescriptorsTaxonomy_3.26.xsd`
    *   Video Popularities: `http://files.api.gracenote.com/xsd/on_update_videoPopularities_3.26.xsd`
    *   Types: `http://files.api.gracenote.com/xsd/types_3.26.xsd`

### Usage
These XSD files can be used with XML validation tools or within your application to ensure that your API requests conform to the expected structure and data types.
```