# TV Grid Online API Docs ## General Information The [TV Grid Online API](/origin/apis-all/tv-grid-online-api-docs/tvgrid.md) 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** filename} \ A representation of a TV series the features the series cast or a setting familiar to the series. **Title Card** 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** 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.
PropertySizeSizeSizeSizeSizeOrientation/Ratio
Showcard1920x10801280x720960x540480x270240x135H 16:9
Titlecard1920x10801280x720960x540480x270240x135H 16:9
Episodic1920x10801280x720960x540480x270240x135H 16:9
Poster960x1440480x720240x360120x18060x90V 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: 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: filename} * Team logos are available at: 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. \ \&Longitude={YourLongitude} \ \&TvM`ediaApiKey={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` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://knowledgebase.fabricdata.com/origin/apis-all/tv-grid-online-api-docs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.