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.

GENERIC LINEUPS

you have access to these generic lineups. We created these lineups to include the most popular TV stations.

LineupIDName/Timezone

• 36617 / US Generic - Eastern

• 41624 / US Generic - Pacific

• 41625 / US Generic - Mountain

• 41626 / US Generic - Central

• 6340 / Canada Generic - Eastern

• 6344 / Canada Generic - Pacific

• 6345 / Canada Generic - Mountain

• 6346 / Canada Generic - Atlantic

• 6347 / Canada Generic - Central

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

Fabric Origin can help get you live linear North American TV listings data and provide all the data needed plus Fabric Origin’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 Fabric Origin'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.

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.

   https://ee.iva-api.com/api/tvgrid/lineups/browse/{CountryId}?TvMediaApiKey={YourTvMediaApiKey} 
   &subscription-Key={YourFabricOriginApiKey} 
   &format=json

2. Get all areas for a particular region using the /lineups/browse/{CountryID}/{RegionID} endpoint.

   https://ee.iva-api.com/api/tvgrid/lineups/browse/{CountryId}/{RegionId}?TvMediaApiKey={YourTvMediaApiKey} 
   &subscription-Key={YourFabricOriginApiKey} 
   &format=json

3. 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}/{RegionId}/{AreaId}?TvMediaApiKey={YourTvMediaApiKey} 
   &subscription-Key={YourFabricOriginApiKey} 
   &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.

   https://ee.iva-api.com/api/tvgrid/lineups?PostalCode={YourZipCode} 
   &TvMediaApiKey={YourTvMediaApiKey} 
   &subscription-Key={YourFabricOriginApiKey} 
   &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.

   https://ee.iva-api.com/api/tvgrid/geo?Latitude={YourLatitude} 
   &Longitude={YourLongitude} 
   &TvMediaApiKey={YourTvMediaApiKey} 
   &subscription-Key={YourFabricOriginApiKey} 
   &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.

   https://ee.iva-api.com/api/tvgrid/lineups/{LineupID}/listings?TvMediaApiKey={YourTvMediaApiKey} 
   &subscription-Key={YourFabricOriginApiKey} 
   &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.

   https://ee.iva-api.com/api/tvgrid/lineups/{LineupID}/listings/grid? TvMediaApiKey={YourTvMediaApiKey}
   &subscription-Key={YourFabricOriginApiKey} 
   &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={YourFabricOriginApiKey} 
&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={YourFabricOriginApiKey} 
&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={YourFabricOriginApiKey} 
&format=json