Documentation
Version 2.0
Note: If you're currently using Version 1.43, please view our Upgrade Guide. The legacy documentation may be found here.
We have no plans to deprecate v1.43, but we highly recommend that you upgrade to v2 for ease of use, and so that you can take advantage of our new client libraries.
Introduction Making a Request Authentication Setting a Region API Limits Quotas Shows Episodes Channels Genres Regions Tags Movies Sources Persons Search Updates
How to Handle Sources
Please note: You are not allowed to remove or modify any tracking or affiliate information on any video link. When the user clicks to a video source, they must pass through the link unmodified. You are allowed to add a tracking link in front of the link provided in our API. You can receive special permission for modifying certain links by contacting us.
Get Streaming and Purchase Links for a Movie or Episode
Streaming and purchase links are found in the episode (clip, episode segment or episode) or movie API response directly. (Please see "Get Movie Information" or "Episode, Clip and Episode Segment" above for further information.
How to Handle Free Sources (Non-Authenticated)
When there are free sources available, the episode (clip, episode segment or episode) and movie API responses will return a list of all the free sources where that piece of content can be watched. Web, iOS and Android sources are broken out individually: free_web_sources, free_ios_sources and free_android_sources. These sources do not require the user to authenticate (i.e. login with pay TV credentials) or pay anything.
The fields returned for Free Sources (Non-Authenticated) are as follows:
source
This is the source short name.
display_name
This is the source display name.
link
This is the link to the piece of content. (Please do not remove tracking or affiliate information from links).
Free Sources
"free_web_sources": [
{
"source": "youtube",
"display_name": "YouTube",
"id": 8789558,
"link": "https://www.youtube.com/watch?v=pSXs7BI2aOM",
"embed": "https://www.youtube.com/embed/pSXs7BI2aOM"
}
],
"free_ios_sources": [
{
"source": "youtube",
"display_name": "YouTube",
"id": 8789558,
"link": "https://www.youtube.com/watch?v=pSXs7BI2aOM",
"embed": "https://www.youtube.com/embed/pSXs7BI2aOM",
"app_name": "YouTube",
"app_link": 0,
"app_required": 0,
"app_download_link": "itms-apps://itunes.apple.com/app/youtube/id544007664"
}
],
"free_android_sources": [
{
"source": "youtube",
"display_name": "YouTube",
"id": 8789558,
"link": "https://www.youtube.com/watch?v=pSXs7BI2aOM",
"embed": "https://www.youtube.com/embed/pSXs7BI2aOM",
"app_name": "YouTube",
"app_link": 0,
"app_required": 0,
"app_download_link": "https://play.google.com/store/apps/details?id=com.google.android.youtube"
}
],
How to Handle Subscription Sources
When there are subscription sources available, the episode (clip, episode segment or episode) and movie API responses will return a list of all the subscription sources where that piece of content can be watched. Web, iOS and Android sources are broken out individually: subscription_web_sources, subscription_ios_sources and subscription_android_sources.
The fields returned for Subscription Sources are as follows:
source
This is the source short name.
display_name
This is the source display name.
link
This is the link to the piece of content. (Please do not remove tracking or affiliate information from links).
Subscription Sources
"subscription_web_sources": [
{
"source": "tribeca_shortlist",
"display_name": "Tribeca Shortlist",
"id": 8789558,
"link": "https://www.tribecashortlist.com/video/1234",
"embed": "https://www.tribecashortlist.com/embed/1234"
}
],
"subscription_ios_sources": [
{
"source": "tribeca_shortlist",
"display_name": "Tribeca Shortlist",
"id": 8789558,
"link": "https://www.tribecashortlist.com/video/1234",
"embed": "https://www.tribecashortlist.com/embed/1234",
"app_name": "Tribeca Shortlist",
"app_link": 0,
"app_required": 0,
"app_download_link": "itms-apps://itunes.apple.com/app/tribecashortlist/id544007664"
}
],
"subscription_android_sources": [
{
"source": "tribeca_shortlist",
"display_name": "Tribeca Shortlist",
"id": 8789558,
"link": "https://www.tribecashortlist.com/video/1234",
"embed": "https://www.tribecashortlist.com/embed/1234",
"app_name": "Tribeca Shortlist",
"app_link": 0,
"app_required": 0,
"app_download_link": "https://play.google.com/store/apps/details?id=com.google.android.tribecashortlist"
}
],
How to Handle Purchase Sources
When there are purchase sources available, the episode (clip, episode segment or episode) and movie API responses will return a list of all the sources where that piece of content can be purchased. Web, iOS and Android sources are broken out individually: purchase_web_sources, purchase_ios_sources and purchase_android_sources.
The fields returned for Purchase Sources are as follows:
source
This is the source short name.
display_name
This is the source display name.
link
This is the link to the piece of content. (Please do not remove tracking or affiliate information from links).
Purchase Sources Examples
"purchase_web_sources": [
{
"source": "itunes",
"display_name": "iTunes",
"id": 7951570,
"link": "https://itunes.apple.com/us/tv-season/the-winds-of-winter/id1091363548?i=1127951326&at=10laHb",
"formats": [
{
"price": "2.99",
"format": "SD",
"type": "purchase"
},
{
"price": "3.99",
"format": "HD",
"type": "purchase"
}
]
}
],
"purchase_ios_sources": [
{
"source": "itunes",
"display_name": "iTunes",
"id": 7951570,
"link": "itms://itunes.apple.com/us/tv-season/the-winds-of-winter/id1091363548?i=1127951326&at=10laHb",
"app_name": "iTunes",
"app_link": 1,
"app_required": 1,
"app_download_link": "itms-apps://",
"formats": [
{
"price": "2.99",
"format": "SD",
"type": "purchase"
},
{
"price": "3.99",
"format": "HD",
"type": "purchase"
}
]
}
],
"purchase_android_sources": [
{
"source": "vudu",
"display_name": "VUDU",
"id": 7951714,
"link": "vuduapp://780646",
"app_name": "VUDU",
"app_link": 1,
"app_required": 1,
"app_download_link": "https://play.google.com/store/apps/details?id=air.com.vudu.air.DownloaderTablet",
"formats": [
{
"price": "2.99",
"format": "SD",
"type": "purchase"
},
{
"price": "3.99",
"format": "HD",
"type": "purchase"
}
]
}
]
How to Handle TV Everywhere Sources (Authenticated)
TV Everywhere refers to the service that allows pay TV customers to watch movie and TV content on the web and mobile devices by authenticating their pay TV subscription. For example, the latest episodes of AMC TV shows on the amctv.com website are available to AMC TV channel subscribers through Xfinity, Time Warner Cable and several others, while not available to customers of other pay TV services like Dish and DirectTV or those who don't subscribe to the AMC TV channel. Each TV Everywhere source on Guidebox has a corresponding list of supported pay TV providers.
In each of the episode (clip, episode segment or episode) and movie API responses, when there are TV everywhere sources available, a list of sources will be returned, along with the required TV channel the user needs to be a subscriber to (i.e. AMC, TNT, CNN, etc). Web, iOS and Android sources are broken out individually: tv_everywhere_web_sources, tv_everywhere_ios_sources and tv_everywhere_android_sources.
The fields returned for TV Everywhere Sources (Authenticated) are as follows:
source
This is the source short name.
display_name
This is the source display name.
link
This is the link to the piece of content. (Please do not remove tracking or affiliate information from links).
tv_channel
This is the required pay TV channel the user has to subscribe to in order to watch this piece of content on TV Everywhre sources
TV Everywhere Sources
"tv_everywhere_web_sources": [
{
"source": "hbo",
"display_name": "HBO GO",
"tv_channel": "HBO",
"id": 8641625,
"link": "http://www.hbogo.com/#series/video&assetID=GOROSTGP55610?videoMode=embeddedVideo/"
}
],
"tv_everywhere_ios_sources": [
{
"source": "hbo",
"display_name": "HBO GO",
"tv_channel": "HBO",
"id": 8641625,
"link": "hbogo://deeplink/ASE.AL/SERIES/GOROSTGP31734/GOROSTGP55610",
"app_name": "HBO GO",
"app_link": 1,
"app_required": 1,
"app_download_link": "itms-apps://itunes.apple.com/app/hbo-go/id429775439"
}
],
"tv_everywhere_android_sources": [
{
"source": "hbo",
"display_name": "HBO GO",
"tv_channel": "HBO",
"id": 8641625,
"link": "hbogo://deeplink/ASE.AL/SERIES/GOROSTGP31734/GOROSTGP55610",
"app_name": "HBO GO",
"app_link": 1,
"app_required": 1,
"app_download_link": "https://play.google.com/store/apps/details?id=com.HBO"
}
],
Android and iOS Support
For Android and iOS Free, Subscription, TV Everywhere and Purchase sources, there are additional fields that will tell you how to handle those links. The additional fields are as follows:
app_link
If the link to a particular piece of content is via an app deep link (customhandler://), this is set to 1, otherwise if the link to a piece of content is via standard http://, this flag is set to 0. If app_link is 1, use canopenurl or some other similar method to determine if the user can access the app via the link or if they need to be redirected to the app_download_link to download the app. If app_link is 0, two things might be the case: (1) the content might be playable on the mobile web via html5 or (2) the end user might still need the app installed because the http:// link redirects into an app. See app_required below to determine if the app is required.
app_required
This is set to 1 if the app is required to playback a particular piece of content, and it is set to 0 if the content is playable on the mobile web via html5 and no app is required.
app_download_link
If the app_link is set to 1 and the user cannot open the link, assume they don't have the application installed, and direct them to the app_download_link for them to install the application.