Guidebox - API Documentation - v1.43

Documentation Updated: August 24, 2016

Base API URL

Our API is available in JSON. The base URL is structured like this:

http://api-public.guidebox.com/v1.43/ {region} / {api key}

Or you can use SSL by structuring the base URL with https:// like this:

https://api-public.guidebox.com/v1.43/ {region} / {api key}

From this base URL, you will structure your API calls.

Please note: earlier versions of the API used content type (i.e. "JSON") instead of "region". Content type has now been deprecated. Since the only content type is JSON, this field is being utilized for region support. If a country code isn't set (i.e. you are still using "JSON" in that field), "US" will be assumed.

Please also note: "all" isn't a proper region and will default to "US". You must select a particular region if you wish to browse content in other regions.

Regions

Please note: All regions other than the United States (US) region are in an early development preview and are not ready for production usage. These early development previews are designed for interested developers looking to develop applications for these alternate regions. Please contact us if you are interested in any particular region or if you are a web developer or movie/TV expert who is familiar with a particular region and are willing to help.

  • Get All Regions
    {Base API URL} /regions/all

API Limits

Development API Keys

Every visitor is given a temporary development API Key. Your temporary development API key is pre-filled in example API calls. This is done so you can dive right into the API.

The following limitations and restrictions are placed on temporary API keys. Please use temporary API keys for testing only. Production API keys don't have the same restrictions:

  • Limited to a total of 250 calls.
  • Rate limited (as defined below).
  • Data pulled using a temporary API key cannot be put on a live website or app until a production API key is generated for the project and has been approved by Guidebox.
  • If you do not generate a production API key, you will need to delete any temporary test data.
  • Do not permanently store any data locally when using the temporary API key.

Production API Keys

Production API keys are assigned a monthly quota when the key is generated. The monthly quota resets the 1st of every month. If you need additional API calls, please contact us after you have generated your production API key and we can make the necessary adjustments.

When you are ready to generate a production API key, click here

Rate Limits

Rate limits are in effect for all API keys. The following rate limits are in effect for your API key: 240 API calls per minute. For each API call, a few additional headers are passed to let you know where you stand:

  • X-RateLimit-Limit (request limit per minute)
  • X-RateLimit-Remaining (number of requests left for this minute window)

As you hit the API, you will see the X-RateLimit-Remaining number decrease until it hits 0. You will receive an error when you run out of API calls for the current time window. When you hit that error, you will receive an additional header:

  • Retry-After (number of seconds remaining until you can try again)

When the Retry-After header reaches 0, the minute window will reset and the X-RateLimit-Remaining will reset as well, allowing you to once again successfully access the API.

If you need to make a change to your rate limit, please contact us after you have generated your production API key and we can make the necessary adjustments.

Shows

Get Show IDs

The following API call will return all currently active shows from Guidebox.

  • Get All Shows

    This API call will return the basic metadata for all available shows. These are ordered by popularity.

    {Base API URL} /shows/ {channel} / {limit 1} / {limit 2} / {sources} / {platform}
  • Variable NamePossible Values
    {channel}Filter shows by a particular channel using the {short_name} variable from the "Channels" section below, or use "all" to return all shows.
    {limit 1}Where in the list of shows to start
    {limit 2}How many shows to return (Maximum 250). For example, 50/25 ({limit 1}/{limit 2}) starts with show 50 and returns 25 shows
    {sources}Filter shows by those with episodes or episode segments of source type ("free", "tv_everywhere", "subscription", "purchase" or "all") or with episodes or episode segments from a specific source (i.e. "amazon_prime" or "hbo"). Multiple source types and sources can be comma separated (i.e. amazon_prime,free would return all shows with free and Amazon Prime episodes). Please note: this doesn't filter based on clips.
    {platform} Filter shows by those with episodes playable on "web", "ios", "android" or "all"
    ?tags={comma separated list of URL encoded tags} Optional To filter shows by those tagged with one or more specific tags, simply add this GET parameter to the API call. To see all available tags, please see the "Genres and Tags" section below. Please ensure to URL encode each keyword

If you already have a show database, you can use the following queries to match the shows in your database with the ID from Guidebox.

  • Search using a Show Title :
    Currently limited to 50 results. Exact match (if any) will be returned first. "Fuzzy" search type is the default.

    {Base API URL} /search/title/ {TRIPLE url encoded show name} / {"exact" or "fuzzy"}
  • Search using a TVDB, THEMOVIEDB or IMDB ID:
    {Base API URL} /search/id/ {tvdb, themoviedb or imdb} / {id}
  • Custom Matching
    The Guidebox API can be customized to provide 1:1 show matching against other data sources to fit your specific needs. Please contact us to discuss these options.

Get Show Information

  • Basic Show Information
    {Base API URL} /show/ {id}
  • All Seasons in a Show

    This API call will return all of the available seasons for a particular show. Please note that not all shows are grouped into seasons. There may still be content available even if this API call returns no results.

    {Base API URL} /show/ {id} /seasons
  • Show Images

    This API call will return the all the images associated with a particular show.

    {Base API URL} /show/ {id} /images/ {"all","thumbnails","posters","banners","backgrounds"}
  • Related Shows

    This API call will return shows that are related to a particular show.

    {Base API URL} /show/ {id} /related

Episodes, Clips and Episode Segments

  • Available Content for a Show

    This API call will return the number of available clips, episode segments and episodes for each supported platform (web, iOS and Android).

    {Base API URL} /show/ {id} /available_content
  • All Available Episodes in a Show

    This API call will return the basic metadata for all available episodes in a show. You can get additional information (including playback links) via the episode API call directly for each episode. See below for more information.

    What are "Episodes"? Episodes are full length videos associated with a particular show. Episodes are grouped into seasons and ordered by episode number.

    {Base API URL} /show/ {id} /episodes/ {season} / {limit 1} / {limit 2} / {sources} / {platform} / {include links}
  • Variable NamePossible Values
    {id}Any Guidebox show ID
    {season}A particular season number or "all" to get episodes from all seasons
    {limit 1}Where in the list of episodes to start
    {limit 2}How many episodes to return (Maximum 100). For example, 50/25 ({limit 1}/{limit 2}) starts with episode 50 and returns 25 episodes
    {sources}Filter episodes by source type ("free", "tv_everywhere", "subscription", "purchase" or "all") or by a specific source (i.e. "amazon_prime" or "hbo"). Multiple source types and sources can be comma separated (i.e. amazon_prime,free would return all free and all Amazon Prime episodes)
    {platform} Filter episodes by those playable on "web", "ios", "android" or "all"
    {include links} Optional Set this value to "true" if you want to return streaming and purchase links in the results or leave blank to not return links. Please note, this will have a performance impact so if you don't immediately need this information, you can leave this blank and get the streaming and purchase links when needed via the episode API call directly for each episode.
    ?reverse_ordering=true Optional Append this GET parameter to reverse the episode order. Default ordering is reverse chronological (most recent episode first). This parameter reverses the ordering to start with the oldest episode first.
  • All Available Clips in a Show

    This API call will return the basic metadata for all available clips in a show. You can get additional information (including playback links) via the clip API call directly for each clip. See below for more information.

    What are "Clips"? Clips (a.k.a. "Videos" or "Extras") are uncategorized videos associated with a particular show. Clips can be small snippets of an episode, behind the scene footage, or in some cases (as with YouTube and other online original shows) can be a self-contained piece of content which hasn't been assigned any episode level metadata.

    {Base API URL} /show/ {id} /clips/all/ {limit 1} / {limit 2} / {sources} / {platform} / {include links}
  • Variable NamePossible Values
    {id}Any Guidebox show ID
    {limit 1}Where in the list of clips to start
    {limit 2}How many clips to return (Maximum 100). For example, 50/25 ({limit 1}/{limit 2}) starts with clip 50 and returns 25 clips
    {sources}Filter clips by source type ("free", "tv_everywhere", "subscription", "purchase" or "all") or by a specific source (i.e. "amazon_prime" or "hbo"). Multiple source types and sources can be comma separated (i.e. amazon_prime,free would return all free and all Amazon Prime clips)
    {platform} Filter clips by those playable on "web", "ios", "android" or "all"
    {include links} Optional Set this value to "true" if you want to return streaming and purchase links in the results or leave blank to not return links. Please note, this will have a performance impact so if you don't immediately need this information, you can leave this blank and get the streaming and purchase links when needed via the clip API call directly for each episode.
    ?min_duration={seconds} Optional To filter clips by a minimum duration, simply add this GET parameter to the API call.
    ?reverse_ordering=true Optional Append this GET parameter to reverse the clip order. Default ordering is reverse chronological (most recent clip first). This parameter reverses the ordering to start with the oldest clip first.
  • All Available Episode Segments in a Show

    This API call will return the basic metadata for all available episode segments in a show. You can get additional information (including playback links) via the episode segment API call directly for each episode segment. See below for more information.

    What are "Episode Segments"? Episode Segments are best explained using a cartoon as an example. Sometimes an episode of a cartoon is actually comprised of two or more complete cartoons with separate titles and storylines. These separate cartoons in the Guidebox ecosystem, when released individually on a playback source, are called episode segments. We treat episode segments differently then episodes or clips because episode segments are self-contained pieces of content (i.e. not a brief snippet or clip) and aren't a full episode because the full episode in the original broadcast (or release) of the cartoon included two or more other episode segments.

    {Base API URL} /show/ {id} /segments/all/ {limit 1} / {limit 2} / {sources} / {platform} / {include links}
  • Variable NamePossible Values
    {id}Any Guidebox show ID
    {limit 1}Where in the list of episode segments to start
    {limit 2}How many episode segments to return (Maximum 100). For example, 50/25 ({limit 1}/{limit 2}) starts with episode segment 50 and returns 25 episode segments
    {sources}Filter episode segments by source type ("free", "tv_everywhere", "subscription", "purchase" or "all") or by a specific source (i.e. "amazon_prime" or "hbo"). Multiple source types and sources can be comma separated (i.e. amazon_prime,free would return all free and all Amazon Prime episode segments)
    {platform} Filter episode segments by those playable on "web", "ios", "android" or "all"
    {include links} Optional Set this value to "true" if you want to return streaming and purchase links in the results or leave blank to not return links. Please note, this will have a performance impact so if you don't immediately need this information, you can leave this blank and get the streaming and purchase links when needed via the segment API call directly for each episode.
    ?reverse_ordering=true Optional Append this GET parameter to reverse the episode segment order. Default ordering is reverse chronological (most recent episode segment first). This parameter reverses the ordering to start with the oldest episode segment first.

After you get the Guidebox ID for a particular episode, clip or episode segment, you can then query the API to get the Streaming and Purchase Links and other meta data.

  • A Particular Episode
    {Base API URL} /episode/ {id}
  • A Particular Clip
    {Base API URL} /clip/ {id}
  • A Particular Episode Segment
    {Base API URL} /segment/ {id}
  • Episode, Clip or Episode Segment Images

    This API call will return all associated images for a particular episode, clip or episode segment.

    {Base API URL} / {"episode", "clip" or "segment"} / {id} /images/all
  • Custom Matching
    The Guidebox API can be customized to provide 1:1 episode matching against other data sources to fit your specific needs. Please contact us to discuss these options.

Channels

All of the shows in the Guidebox API are associated with one or more channels. You can use the {short_name} returned in the following API call to browse shows by channel in the "Get All Shows" API call above.

Get Channel IDs

  • Get All Channels
    {Base API URL} /channels/ {channel type} / {limit 1} / {limit 2}
  • Variable NamePossible Values
    {channel type}Filter channels by type: "all", "online" or "television"
    {limit 1}Where in the list of channels to start
    {limit 2}How many channels to return (Maximum 50). For example, 50/25 ({limit 1}/{limit 2}) starts with channel 50 and returns 25 channels
  • Search for a Channel Using a Channel Title
    Currently limited to 50 results. Exact match (if any) will be returned first. "Fuzzy" search type is the default.

    {Base API URL} /search/channel/title/ {TRIPLE url encoded channel title} / {"exact" or "fuzzy"}

Get Channel Information

  • Basic Channel Information
    {Base API URL} /channel/ {id}
  • Channel Images
    {Base API URL} /channel/ {id} /images/all

Genres and Tags

PLEASE NOTE: At this time, shows are the only pieces of content that are assigned genres and tags. Other content types (movies, channels, videos, etc) will be available soon.

Genres

Genres are broad categorizations of content like "comedy" or "drama".

  • Get All Genres
    {Base API URL} /genres

Tags

Tags are free-form keywords associated with a particular piece of content. Tags are more specific than genres.

  • Get All Tags
    {Base API URL} /tags/ {limit 1} / {limit 2}
  • Variable NamePossible Values
    {limit 1}Where in the list of tags to start
    {limit 2}How many tags to return (Maximum 250). For example, 50/25 ({limit 1}/{limit 2}) starts with tag 50 and returns 25 tags

Movies

Get Movie IDs

  • Get All Movies

    This API call will return the basic metadata for all movies available for immediate playback. These are ordered by popularity. You can get additional information (including playback links) via the movie API call directly for each movie.

    {Base API URL} /movies/all/ {limit 1} / {limit 2} / {sources} / {platform}
  • Variable NamePossible Values
    {limit 1}Where in the list of movies to start
    {limit 2}How many movies to return (Maximum 250). For example, 50/25 ({limit 1}/{limit 2}) starts with movie 50 and returns 25 movies
    {sources}Filter movies by source type ("free", "tv_everywhere", "subscription", "purchase" or "all") or by a specific source (i.e. "amazon_prime" or "hbo"). Multiple source types and sources can be comma separated (i.e. amazon_prime,free would return all free and all Amazon Prime movies)
    {platform} Filter movies by "web", "ios", "android" or "all"
    ?include_preorders=true By default, we only include movies which are available for immediate playback. If you want to include movies which are ONLY available for pre-order alongside movies which are immediately playable, append this GET parameter.
    ?include_in_theaters=true By default, we only include movies which are available for immediate playback. If you want to include movies which are ONLY available in theaters alongside movies which are immediately playable, append this GET parameter.

If you already have a movie database, you can use the following queries to match the movies in your database with the ID from Guidebox.

  • Search using a Movie Title
    Currently limited to 50 results. Exact match (if any) will be returned first. "Fuzzy" search type is the default.

    {Base API URL} /search/movie/title/ {TRIPLE url encoded show name} / {"exact" or "fuzzy"}
  • Search using an IMDB or themoviedb ID:
    {Base API URL} /search/movie/id/ {themoviedb or imdb} / {id}
  • Custom Matching
    The Guidebox API can be customized to provide 1:1 movie matching against other data sources to fit your specific needs. Please contact us to discuss these options.

Get Movie Information

After you get the Guidebox ID for a particular movie, you can then query the API to get the Streaming and Purchase Links and other meta data for the movie.

  • Basic Movie Information
    {Base API URL} /movie/ {id}
  • Variable NamePossible Values
    ?include_preorders=true By default, we only include movie playback links which are available for immediate playback. If you want to include movies links which are available for pre-order, append this GET parameter.
  • Movie Images
    {Base API URL} /movie/ {id} /images/ {"all","thumbnails","posters","banners","backgrounds"}
  • Related Movies
    {Base API URL} /movie/ {id} /related

Movie Trailers and Related Videos

Many movies in the Guidebox API have associated trailers, behind the scenes featurettes, interviews and other related videos. The main Guidebox trailer is included in the basic movie API call, all other videos and alternate trailers can be retrieved using the following API call.

  • Get Movie Trailers and Related Videos for a Particular Movie
    {Base API URL} /movie/ {id} /videos/ {sources} / {limit 1} / {limit 2}
  • Variable NamePossible Values
    {id}Movie id.
    {sources}Filter videos by a specific source. Currently we only support "guidebox" and "youtube" for this API call
    {limit 1}Where in the list of videos to start
    {limit 2}How many videos to return. For example, 50/25 ({limit 1}/{limit 2}) starts with video 50 and returns 25 videos

Playback 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.

Also, please note: You will need special permission to include Netflix data in your application. Please contact us if you want additional information.

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.

All Available Sources

The following API calls will return all the sources currently supported in the API. These can be filtered by source type and by sources with available movies or shows.

  • All Sources
    {Base API URL} /sources/all/ {"all", "movies" or "shows"}
  • All Free Sources
    {Base API URL} /sources/free/ {"all", "movies" or "shows"}
  • All Subscription Sources
    {Base API URL} /sources/subscription/ {"all", "movies" or "shows"}
  • All Purchase Sources
    {Base API URL} /sources/purchase/ {"all", "movies" or "shows"}
  • All TV Everywhere Sources
    {Base API URL} /sources/tv_everywhere/ {"all", "movies" or "shows"}

Please note: new sources are added periodically.

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).

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).

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).

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 this particular TV Everywhere source.

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.

People

  • Search for a Person Using Their Name
    Currently limited to 50 results. Exact match (if any) will be returned first. "Fuzzy" search type is the default.

    {Base API URL} /search/person/name/ {TRIPLE url encoded person's name} / {"exact" or "fuzzy"}
  • Basic Person Information
    {Base API URL} /person/ {id}
  • Person Images
    {Base API URL} /person/ {id} /images/all
  • Get Person Credits
    {Base API URL} /person/ {id} /credits/ {"movies", "shows" or "all"} / {"cast", "crew"}

Customization

Support for Other Platforms (Smart TVs, Streaming Media Players, etc)

The Guidebox API can be customized to support nearly any platform in addition to the platforms which are currently supported by default (Web, iOS and Android). Please contact us to discuss customization options.

Additional Sources and Media Types

In addition to the sources and media types currently supported in the API, we can customize the API to support nearly any source or media type. We have indexed some media types and some lesser known sources that we haven't yet exposed in the API. If a service or media type that is important to your application doesn't currently show up in the API, please contact us to discuss. In many cases, a new source or media type can be added quickly.

Custom ID Matching

The Guidebox API can be customized to provide 1:1 matching against other data sources to fit your specific needs. We have matched the Guidebox IDs to several 3rd party IDs to make integration easier. Please contact us to discuss these options.

Caching or Storing Data

You are allowed to store the Guidebox data on your local systems if you abide by the following guidelines. (Please note: If we find stale or bad data being displayed in your application, we will notify you via email. We may ask you to cease storing local data if we have to reach out multiple times.)

Caching

You can cache the Guidebox API results for up to 24 hours. After a 24 hour period, you must completely purge the results and fetch again. Guidebox data presented in your application must not be older than 24 hours.

Local Storage

You are also free to store the data locally provided you:

  1. Check for updates at least 2 times per 24 hour period using the various /updates API calls.
  2. Keep the data completely in sync with the live Guidebox data. If any metadata (description, images, title) or links to sources change in any way, your local data needs to be updated.

If you delete your API key or if your API key is terminated by Guidebox, you must remove all cached and locally stored Guidebox data from your application within 30 days.

Updates

If you choose to store the Guidebox data locally, we provide the following API calls for keeping your data in sync with Guidebox. These API calls list the updates after a particular UNIX timestamp. For more information on caching and storing Guidebox data, please see the "Caching or Storing Guidebox Data" section above.

Please note: We only provide updates for the previous few weeks. It is recommended that you run the updates at least twice per day to ensure that all your data is in sync.

  • Get current server time for {last process time}
    Use this time to mark when you last synced with the API data
    {Base API URL} /updates/get_current_time

Show Updates

  • Show Changes
    Show IDs are listed here when any basic show data changes (i.e. overview, related images, etc). Please note that if any child data changes (i.e. an episode), that will not be reflected here.
    {Base API URL} /updates/shows/changes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • New Shows
    New show IDs are listed here when they are added to Guidebox.
    {Base API URL} /updates/shows/new/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • New Episodes for a show
    Show IDs are listed here when they have new episodes added to Guidebox.
    {Base API URL} /updates/shows/new_episodes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • Changed Episodes for a show
    Show IDs are listed here when they have changed episodes (i.e. when a episode is removed from or added to a streaming or download source or any episode metadata changes).
    {Base API URL} /updates/shows/changed_episodes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • New Clips for a Show
    Show IDs are listed here when they have new clips added to Guidebox.
    {Base API URL} /updates/shows/new_clips/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • New Episode Segments for a Show
    Show IDs are listed here when they have new episode segments added to Guidebox.
    {Base API URL} /updates/shows/new_segments/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • Deleted Shows
    Show IDs are listed here when they are completely deleted from Guidebox. Please note: since the show was deleted, calling it in the API via the /show call will return FALSE.
    {Base API URL} /updates/shows/deletes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

Episode Updates

  • Episode Changes
    Episode IDs are listed here when any episode data changes (i.e. when a episode is removed from or added to a streaming or download source or any episode metadata changes). You can retrieve all episodes, or filter by a particular show.
    {Base API URL} /updates/episodes/changes/ {last process time} / {show ID (optional)} ?limit= {limit (max 1000)} &page= {page #}

  • New Episodes
    New episode IDs are listed here when they are added to Guidebox.
    {Base API URL} /updates/episodes/new/ {last process time} / {show ID (optional)} ?limit= {limit (max 1000)} &page= {page #}

  • Deleted Episodes
    Episode IDs are listed here when they are completely deleted from Guidebox. Please note: since the episode was deleted, calling it in the API via the /episode call will return FALSE.
    {Base API URL} /updates/episodes/deletes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

Clip Updates

  • Clip Changes
    Clip IDs are listed here when any clip data changes (i.e. when a clip is removed from or added to a streaming or download source or any clip metadata changes).
    {Base API URL} /updates/clips/changes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • New Clips
    New clip IDs are listed here when they are added to Guidebox.
    {Base API URL} /updates/clips/new/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • Deleted Clips
    Clip IDs are listed here when they are completely deleted from Guidebox. Please note: since the clip was deleted, calling it in the API via the /clip call will return FALSE.
    {Base API URL} /updates/clips/deletes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

Episode Segment Updates

  • Episode Segment Changes
    Episode Segment IDs are listed here when any episode segment data changes (i.e. when a episode segment is removed from or added to a streaming or download source or any episode segment metadata changes).
    {Base API URL} /updates/segments/changes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • New Episode Segments
    New episode segment IDs are listed here when they are added to Guidebox.
    {Base API URL} /updates/segments/new/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • Deleted Episode Segments
    Episode Segment IDs are listed here when they are completely deleted from Guidebox. Please note: since the episode segment was deleted, calling it in the API via the /segment call will return FALSE.
    {Base API URL} /updates/segments/deletes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

Movie Updates

  • Movie Changes
    Movie IDs are listed here when any movie data changes (i.e. when a movie is removed from or added to a streaming or download source or any metadata changes).
    {Base API URL} /updates/movies/changes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • New Movies
    New movie IDs are listed here when they are added to Guidebox.
    {Base API URL} /updates/movies/new/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

  • Deleted Movies
    Movie IDs are listed here when they are completely deleted from Guidebox. Please note: since the movie was deleted, calling it in the API via the /movie call will return FALSE.
    {Base API URL} /updates/movies/deletes/ {last process time} ?limit= {limit (max 1000)} &page= {page #}

Error Handling

Please build your applications to watch for server 500 errors. If you get a server 500 error, please pause your calls to the API until the error is resolved. The error is displayed in the JSON under <error>. In these cases, no other data is returned. Here is an example call to the API that will cause an error: (Example)

Processing the Data You Get Back

The data from Guidebox is dynamic and changes every few minutes. Information is added, changed and sometimes removed. Thumbnails are added, descriptions are filled out, titles are fixed and so on. Please keep this in mind when building out your application. Also build your application so that it can ignore fields in JSON that it doesn't need. We are continuing to add additional fields to our API as they become available.

Questions or Comments

We are always looking for ways to improve the API, website and documentation. Please provide feedback or ask your questions by contacting us.