TV Grid API Guide

This implementation guide will walk you through implementing the TV Grid Online APIs including lineups, teams info, and linear grid data.

General Information

The TV Grid Online API provides access to 14 days of live linear North American TV listings data by provider and by the half hour, complete with descriptions, showcards, and trailers.

The TV Grid Online API contains the following specific endpoints (grouped by purpose).

LINEUPS
/lineups Allows you to get lineups metadata (including Lineup IDs) by Postal Code.
/lineups/browse Returns a list of available countries to serve as a starting point for lineups browsing.
/lineups/browse/{CountryID} Allows you to get list of regions for a country.
/lineups/browse/{CountryID}/{RegionID} Allows you to get service Areas for a specific country and region.
/lineups/browse/{CountryID}/{RegionID}/{AreaID} Allows you to get lineups metadata (including Lineup IDs) for a given CountryID, RegionID, and AreaID.
/lineups/geo Allows you to get lineups metadata (including LineupIDs) by geo-location.
/lineups/{LineupID} Allows you to get lineup details for a specific lineup by LineupID.
/lineups/{LineupID}/listings Allows you to get chronological listings for a given Lineup ID.
/lineups/{LineupID}/listings/grid Allows you to get a collection of listings grouped by channel and ordered by listDateTime.
/lineups/{LineupID}/listings/highlights Allows you to get featured listings for a given Lineup ID.

STATIONS
/stations/{StationID} Allows you to get details about a particular station by StationID.
/stations/{StationID}/listings Allows you to get listings for a given Station ID.

REFERENCE
/genres/movies Allows you to get a list of movie genres.
/genres/shows Allows you to get a list of show genres.
/genres/sports Allows you to get a list of sports genres.
/reference/lineups Allows you to get a list of generic LineupIDs that can be used. A ‘generic’ lineup is not a real lineup, but a collection of stations defined by TV Media. Any listing retrieved using a generic lineup will not return any channel number information, as it is irrelevant.

LEAGUES
/leagues Allows you to get a list of all sports leagues.
/leagues/{LeagueID}/listings Allows you to get listings for a given League ID.
/leagues/{LeagueID}/teams Allows you to get list of teams in a league for a given League ID.

TEAMS
/teams/{TeamID} Allows you to get details about a specific sports team by TeamID.
/teams/{TeamID}/listings Allows you to get listings for a given Team ID.

VIDEO
/Videos Allows you to get a list of videos for a program.

Open API/Swagger documentation can be found on the TV Grid API page.


Implementation Examples and Best Practices

IVA can help get you live linear North American TV listings data and provide all the data needed plus IVA’s enhanced metadata, images and trailer content.

These APIs are not to be set up client-side. Developers will need to pre-cache some of this information and update accordingly.

If you have any questions please reach out to our support team.


Authentication

All your query URLs will have to pass 2 parameters for authentication:

  1. TvMediaApiKey: This is the API key we've set up for your use directly from TV Media.
  2. subscription-Key: This is the API for IVA's API Management for a subscription to our TV Grid Online subscription.

Artwork

Artwork is returned as an array that specifies the types of artwork that is available. Artwork can be accessed at various sizes. Note: Not all types of artwork are available for each series/episode.

Show Card
http://cdn.tvpassport.com/image/show/size/{provided filename}
A representation of a TV series the features the series cast or a setting familiar to the series.

Title Card
http://cdn.tvpassport.com/image/show/size/{provided filename}
A representation of a TV series the features the series’ logo. The image may or may not have cast members or a setting from the series.

Poster
http://cdn.tvpassport.com/image/show/size/{provided filename}
A representation of a TV series the features the series cast or a setting familiar to the series as well as the logo.

Episodic
http://cdn.tvpassport.com/image/show/size/{provided filename}
A photo from an TV series episode or a movie.
Property Size Size Size Size Size Orientation/Ratio
showcard 1920x1080 1280x720 960x540 480x270 240x135 H 16:9
titlecard 1920x1080 1280x720 960x540 480x270 240x135 H 16:9
episodic 1920x1080 1280x720 960x540 480x270 240x135 H 16:9
poster 960x1440 480x720 240x360 120x180 60x90 V 2:3
We strongly recommend you only use the image size closest to your requirements.
Using Logo Filepaths to Find Images

Station Logos:

  • Station logos are available at: http://cdn.tvpassport.com/image/station/{size}/{provided filename}

Station logo sizes can be one of the following:

100x100
Square logos
76x28
Bounded by maximum constraint
75x16
Bounded by maximum constraint

Sports Logos:

  • League logos are available at: http://cdn.tvpassport.com/image/league/{provided filename}
  • Team logos are available at: http://cdn.tvpassport.com/image/team/{provided filename}

Review the examples below to see how to work with the TV Grid API. These examples represent a common use-case of caching and updating listings data.


Best Practice for Getting LineupIDs

In order to get LineupIDs by Country/Region/Area, we recommend the following steps:

  1. Get all regions from the /lineups/browse/{CountryID} endpoint by country, using 'US' for United States or 'CA' for Canada in the end of the base URL.
    2. https://ee.iva-api.com/api/tvgrid/lineups/browse/{CountryId}?
                    TvMediaApiKey={YourTvMediaApiKey}
                    &subscription-Key={YourIVAApiKey}
                    &format=json
  2. Get all areas for a particular region using the /lineups/browse/{CountryID}/{RegionID} endpoint.
    3. https://ee.iva-api.com/api/tvgrid/lineups/browse/{CountryId}/{RegionId}?
                    TvMediaApiKey={YourTvMediaApiKey}
                    &subscription-Key={YourIVAApiKey}
                    &format=json
  3. Get all lineups (and LineupIDs) in a particular area using the /lineups/browse/{CountryID}/{RegionID}/{AreaID} endpoint.
    4. https://ee.iva-api.com/api/tvgrid/lineups/browse/{CountryId}/{RegionId}/{AreaId}?
                    TvMediaApiKey={YourTvMediaApiKey}
                    &subscription-Key={YourIVAApiKey}
                    &format=json

In order to get LineupIDs by Zip Code, we recommend the following steps:

  1. Get all lineups (and LineupIDs) in a particular zip code using the /lineups endpoint and passing the PostalCode parameter.
    2. https://ee.iva-api.com/api/tvgrid/lineups?
                         PostalCode={YourZipCode}
                         &TvMediaApiKey={YourTvMediaApiKey}
                         &subscription-Key={YourIVAApiKey}
                         &format=json

In order to get LineupIDs by Geo-location, we recommend the following steps:

  1. Get all lineups (and LineupIDs) near a particular geo-location using the /lineups/geo endpoint and pass the Latitude and Longitude parameters.
    2. https://ee.iva-api.com/api/tvgrid/geo?
                         Latitude={YourLatitude}
                         &Longitude={YourLongitude}
                         &TvMediaApiKey={YourTvMediaApiKey}
                         &subscription-Key={YourIVAApiKey}
                         &format=json



Best Practice for Getting Listings for a Particular Lineup

In order to get a straight list of individual listings, we recommend the following steps:

  1. Get individual listings for a lineup by using the /lineups/{LineupID}/listings endpoint.
    2. https://ee.iva-api.com/api/tvgrid/lineups/{LineupID}/listings?
                    TvMediaApiKey={YourTvMediaApiKey}
                    &subscription-Key={YourIVAApiKey}
                    &format=json

    NOTE: This query has several optional parameters such as limiting the channels returned, the start and end date of the query (these default to current date/time for Start and Start+4 hours for End), etc. Details can be found by following the link to the endpoint above.

In order to get a collection of listings grouped by channel ("grid"), we recommend the following steps:

  1. Get collections of listings by channel for a lineup using the /lineups/{LineupID}/listings/grid endpoint.
    2. https://ee.iva-api.com/api/tvgrid/lineups/{LineupID}/listings/grid?
                         TvMediaApiKey={YourTvMediaApiKey}
                         &subscription-Key={YourIVAApiKey}
                         &format=json

    NOTE: This query has several optional parameters such as limiting the channels returned, the start and end date of the query (these default to current date/time for Start and Start+4 hours for End), etc. Details can be found by following the link to the endpoint above.


Get List of All Sports Leagues

Get a list of all sports leagues (including Name, LeagueID, and Logo filepath) by using the /leagues endpoint.

https://ee.iva-api.com/api/tvgrid/leagues?
                        TvMediaApiKey={YourTvMediaApiKey}
                        &subscription-Key={YourIVAApiKey}
                        &format=json

Get List of Teams in a Particular League

Get a list of all sports teams in a particular league (including Names, TeamID, and Logo filepath) by using the /leagues/{LeagueID}/teams endpoint.

https://ee.iva-api.com/api/tvgrid/leagues/{LeagueID}/teams?
                        TvMediaApiKey={YourTvMediaApiKey}
                        &subscription-Key={YourIVAApiKey}
                        &format=json

Get Individual Listings for a Particular Team in a Particular Lineup

Get a straight list of listings for a particular team given a particular lineup by using the /leagues/{LeagueID}/listings and passing the required LineupID parameter.

https://ee.iva-api.com/api/tvgrid/leagues/{LeagueID}/listings?
                        TvMediaApiKey={YourTvMediaApiKey}
                        &subscription-Key={YourIVAApiKey}
                        &format=json