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.
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/{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. |
| /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 | 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/{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. |
| /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.
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.
All your query URLs will have to pass 2 parameters for authentication:
- TvMediaApiKey: This is the API key we've set up for your evaluation directly from TV Media.
- subscription-Key: This is the API for IVA's API Management for a subscription to our TV Grid Online subscription.
Station Logos:
- Station logos are available at: http://cdn.tvpassport.com/image/station/size/{provided filename}
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.
In order to get LineupIDs by Country/Region/Area, we recommend the following steps:
- 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.
- Get all areas for a particular region using the /lineups/browse/{CountryID}/{RegionID} endpoint.
- Get all lineups (and LineupIDs) in a particular area using the /lineups/browse/{CountryID}/{RegionID}/{AreaID} endpoint.
https://ee.iva-api.com/api/tvgrid/lineups/browse/{CountryId}?
TvMediaApiKey={YourTvMediaApiKey}
&subscription-Key={YourIVAApiKey}
&format=json
https://ee.iva-api.com/api/tvgrid/lineups/browse/{CountryId}/{RegionId}?
TvMediaApiKey={YourTvMediaApiKey}
&subscription-Key={YourIVAApiKey}
&format=json
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:
- Get all lineups (and LineupIDs) in a particular zip code using the /lineups endpoint and passing the PostalCode parameter.
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:
- Get all lineups (and LineupIDs) near a particular geo-location using the /lineups/geo endpoint and pass the Latitude and Longitude parameters.
https://ee.iva-api.com/api/tvgrid/geo?
Latitude={YourLatitude}
&Longitude={YourLongitude}
&TvMediaApiKey={YourTvMediaApiKey}
&subscription-Key={YourIVAApiKey}
&format=json
In order to get a straight list of individual listings, we recommend the following steps:
- Get individual listings for a lineup by using the /lineups/{LineupID}/listings endpoint.
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:
- Get collections of listings by channel for a lineup using the /lineups/{LineupID}/listings/grid endpoint.
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 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 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 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