Guidebox | API Docs

API Documentation

Examples
cURL
PHP
Python
Ruby
Node

Introduction

Welcome to the Guidebox API! Our API is organized around REST principles, with predictable, resource-oriented URIs, and uses sensible HTTP codes to indicate API errors. We use HTTP verbs and HTTP authentication, which every HTTP client should understand. We also support cross-origin resource sharing, allowing you to securely interact with Guidebox from your web applications.

Our API returns JSON for all responses, including errors.

Base API URL

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

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

We highly recommend that you use our API Client Libraries for your chosen language, if one is available.

GET http://api-public.guidebox.com/v2/{endpoint}

Authentication

Each user is given an API key. In order to make a request to the Guidebox API, simply append the API key to the end of your request.

Alternately, you may pass in the API Key as an Authorization header.

$ curl http://api-public.guidebox.com/v2/genres?api_key=YOUR_API_KEY?api_key={YOUR API KEY}

$genres = $client->genres()->all();

genres = guidebox.Genre.list()

genres = guidebox.genres.list

var genres = Guidebox.genres.list();

As a Header

Authorization: YOUR_API_KEY

Setting a Region

By default, all API calls will be processed in the US region.

Using Other Regions

If you would like to use another region, you may pass it in as a query parameter or as a header

For a list of acceptable regions, please see the Regions endpoint.

As a query parameter:

GET /v2/{endpoint}?region=JP

As a header:

Guidebox-Region: JP

Using our Client Libraries

$ curl http://api-public.guidebox.com/v2/genres?api_key=YOUR_API_KEY?api_key={YOUR API KEY}&region=JP

$client = new Guidebox\Guidebox($api_key, 'JP')

import guidebox
guidebox.api_key = "YOUR_API_KEY"
guidebox.region = "JP"

guidebox = Guidebox::Client.new(api_key: 'YOUR_API_KEY', region: JP)

var client = require('guidebox')
var Guidebox = new client('YOUR_API_KEY', 'JP');

API Limits

Rate limits are in effect for all users. All users may make up to 240 API requests per minute. For each request, additional response headers are passed to let you know where you stand:

Number of requests per minute

X-RateLimit-Limit: 240

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:

Number of requests remaining for this minute window

X-RateLimit-Remaining: 135

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

Returns seconds remaining until next allowed request

Retry-After: 36

Quotas

Each API key is allowed to make a limited number of requests per month. If you need to make more requests, please contact Guidebox.

Headers

Each API response will return a header that contains your max requests per billing period, as well as the progress toward that quota.

Header

Guidebox-Quota:3995
Guidebox-Quota-Max:150000

API Endpoint

Alternately, you may use our API Endpoint to retrieve your current quota details.

API Endpoint

GET /v2/quota

Example Request

$ curl http://api-public.guidebox.com/v2/quota?api_key=YOUR_API_KEY

$quota = $client->quota();

quota = guidebox.Quota.retrieve()

quota = guidebox.quota.find()

var quota = Guidebox.quota.retrieve();

Shows

A TV show is one of the core entities of Guidebox data. It represents the TV show or series element, with a title, description, rating, and much more.

Below is a list of endpoints through which you can retrieve the myriad data points available about a particular show.

List all Shows

This endpoint retrieves all currently active shows from Guidebox. The results are ordered by popularity. You may get additional information about each show using its show ID. More on that below.

The following filters are available:

channeloptional

Filter shows by a particular channel using the short_name field from the Channels section below.

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 25

Number of records to return per request.

sourcesoptional

Filter shows by source. Valid options include:

free
tv_everywhere
subscription
purchase
A specific source, such as amazon_prime or hbo

Multiple sources may be comma-separated.

Note: this does not filter clips

platformoptional

Filter by platform. Valid options include:

ios
android
web

tagsoptional

Filter show by tags. You may retrieve a list of tags from the Tags endpoint.

Base URL

GET /v2/shows

Example Request

$ curl http://api-public.guidebox.com/v2/shows?api_key=YOUR_API_KEY

$shows = $client->shows()->all();

shows = guidebox.Show.list()

shows = guidebox.shows.list

var shows = Guidebox.shows.list();

Select shows from a specific channel:

GET /v2/shows?channel=hbo

Example Request

$ curl http://api-public.guidebox.com/v2/shows?api_key=YOUR_API_KEY&channel=hbo

$shows = $client->shows()->all([
    'channel' => 'hbo'
]);

shows = guidebox.Show.list(channel="hbo")

shows = guidebox.shows.list({:channel => 'hbo'})

var shows = Guidebox.shows.list({channel: 'hbo'});

Select the first twelve results:

GET /v2/shows?limit=12

Example Request

$ curl http://api-public.guidebox.com/v2/shows?api_key=YOUR_API_KEY&limit=12

$shows = $client->shows()->all([
    'limit' => 12
]);

shows = guidebox.Show.list(limit=12)

shows = guidebox.shows.list({:limit => 12})

var shows = Guidebox.shows.list({channel: 'hbo'});

Select the next page of 12 results:

GET /v2/shows?limit=12&offset=12

Example Request

$ curl http://api-public.guidebox.com/v2/shows?api_key=YOUR_API_KEY&limit=12&offset=12

$shows = $client->shows()->all([
    'limit' => 12,
    'offset' => 12
]);

shows = guidebox.Show.list(limit=12,offset=12)

shows = guidebox.shows.list({:limit => 12, :offset => 12})

var shows = Guidebox.shows.list({limit: 12, offset: 12});

Select free shows:

GET /v2/shows?sources=free

Example Request

$ curl http://api-public.guidebox.com/v2/shows?api_key=YOUR_API_KEY&sources=free

$shows = $client->shows()->all([
    'sources' => 'free'
]);

shows = guidebox.Show.list(sources='free')

shows = guidebox.shows.list({:sources => 'free'})

var shows = Guidebox.shows.list({ sources: 'free' });

Select free and subscription shows

GET /v2/shows?sources=free,subscription

Example Request

$ curl http://api-public.guidebox.com/v2/shows?api_key=YOUR_API_KEY&sources=free,subscription

$shows = $client->shows()->all([
    'sources' => 'free,subscription'
]);

shows = guidebox.Show.list(sources='free,subscription')

shows = guidebox.shows.list({:sources => 'free,subscription'})

var shows = Guidebox.shows.list({ sources: 'free,subscription' });

Select subscription shows from subscription sources AND Amazon Prime:

GET /v2/shows?sources=subscription,amazon_prime

Example Request

$ curl http://api-public.guidebox.com/v2/shows?api_key=YOUR_API_KEY&sources=subscription,amazon_prime

$shows = $client->shows()->all([
    'sources' => 'subscription,amazon_prime'
]);

shows = guidebox.Show.list(sources='subscription,amazon_prime')

shows = guidebox.shows.list({:sources => 'subscription,amazon_prime'})

var shows = Guidebox.shows.list({ sources: 'subscription,amazon_prime' });

Select only shows available on iOS:

GET /v2/shows?platform=ios

Example Request

$ curl http://api-public.guidebox.com/v2/shows?api_key=YOUR_API_KEY&platform=ios

$shows = $client->shows()->all([
    'platform' => 'ios'
]);

shows = guidebox.Show.list(platform='ios')

shows = guidebox.shows.list({:platform => 'ios'})

var shows = Guidebox.shows.list({ platforms: 'ios' });

Select shows filtered by tag:

GET /v2/shows?tags=comedy

Example Request

$ curl http://api-public.guidebox.com/v2/shows?api_key=YOUR_API_KEY&tag=comedy

$shows = $client->shows()->all([
    'tag' => 'comedy'
]);

shows = guidebox.Show.list(tag='comedy')

shows = guidebox.shows.list({:tag => 'comedy'})

var shows = Guidebox.shows.list({ tag: 'comedy' });

Retrieve a single show

This endpoint retrieves the details for a single show.

GET /v2/shows/{id}

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959?api_key=YOUR_API_KEY

$show = $client->shows()->get(6959);

show = guidebox.Show.retrieve(id=6959)

var show = Guidebox.shows.retrieve(6959);

Retrieve all seasons for a single show

This endpoint retrieves a list of the seasons for a single show.

GET /v2/shows/{id}/seasons

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/seasons?api_key=YOUR_API_KEY

$seasons = $client->shows()->seasons(6959);

seasons = guidebox.Show.seasons(id=6959)

var seasons = Guidebox.shows.seasons(6959);

Retrieve all images for a single show

This endpoint retrieves a list of the images for a single show.

You may also filter by image size:

thumbnails
posters
banners
backgrounds

GET /v2/shows/{id}/images

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/images?api_key=YOUR_API_KEY

$images = $client->shows()->images(6959);

images = guidebox.Show.images(id=6959)

var images = Guidebox.shows.images(6959);

Fetch only thumbnails

GET /v2/shows/{id}/images?filter=thumbnails

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/images?api_key=YOUR_API_KEY&filter=thumbnails

$images = $client->shows()->images(6959, [
    'filter' => 'thumbnails'
]);

images = guidebox.Show.images(id=6959, filter='thumbnails')

var images = Guidebox.shows.images(6959, { filter: 'thumbnails' });

Retrieve all related shows for a single show

This endpoint retrieves a list of the related shows for a single show.

GET /v2/shows/{id}/related

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/related?api_key=YOUR_API_KEY

$related = $client->shows()->related(6959);

related = guidebox.Show.related(id=6959)

var related = Guidebox.shows.related(6959);

Retrieve all available content for a single show

This endpoint retrieves the available content for a single show.

GET /v2/shows/{id}/available_content

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/available_content?api_key=YOUR_API_KEY

$related = $client->shows()->available_content(6959);

related = guidebox.Show.available_content(id=6959)

var related = Guidebox.shows.availableContent(6959);

Episodes, Clips, and Segments

What are "Episodes"?

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

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.

What are "Segments"?

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.

List all episodes

Required: show_id - the ID for a specific show. See Shows for more information.

The following filters are available:

seasonoptional

A particular season for a show.

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 25

Number of records to return per request.

sourcesoptional

Filter shows by source. Valid options include:

free
tv_everywhere
subscription
purchase
A specific source, such as amazon_prime or hbo

Multiple sources may be comma-separated.

platformoptional

Filter by platform. Valid options include:

ios
android
web

include_linksoptional

Provide a value of true if you would like to return streaming or purchase links.

reverse_orderingoptional

Returns the episodes in descending order of release date. Used to show most recent episodes.

Select all episodes:

GET /v2/shows/{show_id}/episodes

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/episodes?api_key=YOUR_API_KEY

$episodes = $client->shows()->episodes(6959);

episodes = guidebox.Show.episodes(id=6959)

episodes = guidebox.shows.episodes(6959)

var episodes = Guidebox.shows.episodes(6959);

Select only episodes from a single season:

GET /v2/shows/{show_id}/episodes?season=1

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/episodes?api_key=YOUR_API_KEY&season=1

$episodes = $client->shows()->episodes(6959, [
    'season' => 1
]);

episodes = guidebox.Show.episodes(id=6959,season=1)

episodes = guidebox.shows.episodes(6959, {:season => 1})

var episodes = Guidebox.shows.episodes(6959, { season: 1 });

Select only subscription episodes:

GET /v2/shows/{show_id}/episodes?sources=subscription

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/episodes?api_key=YOUR_API_KEY&sources=subscription

$episodes = $client->shows()->episodes(6959, [
    'sources' => 'subscription'
]);

episodes = guidebox.Show.episodes(id=6959, sources='subscription')

episodes = guidebox.shows.episodes(6959, {:sources => 'subscription'})

var episodes = Guidebox.shows.episodes(6959, { sources: 'subscription' });

Select only subscription episodes from Amazon Prime:

GET /v2/shows/{show_id}/episodes?sources=subscription,amazon_prime

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/episodes?api_key=YOUR_API_KEY&sources=subscription,amazon_prime

$episodes = $client->shows()->episodes(6959, [
    'sources' => 'subscription,amazon_prime'
]);

episodes = guidebox.Show.episodes(id=6959, sources='subscription,amazon_prime')

episodes = guidebox.shows.episodes(6959, {:sources => 'subscription,amazon_prime'})

var episodes = Guidebox.shows.episodes(6959, { sources: 'subscription,amazon_prime' });

Select only iOS episodes:

GET /v2/shows/{show_id}/episodes?platform=ios

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/episodes?api_key=YOUR_API_KEY&platform=ios

$episodes = $client->shows()->episodes(6959, [
    'platform' => 'ios'
]);

episodes = guidebox.Show.episodes(id=6959, platform='ios')

episodes = guidebox.shows.episodes(6959, {:platform => 'ios'})

var episodes = Guidebox.shows.episodes(6959, { platform: 'ios' });

Return streaming and purchase links:

GET /v2/shows/{show_id}/episodes?include_links=true

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/episodes?api_key=YOUR_API_KEY&include_links=true

$episodes = $client->shows()->episodes(6959, [
    'include_links' => true
]);

episodes = guidebox.Show.episodes(id=6959, include_links=True)

episodes = guidebox.shows.episodes(6959, {:include_links => true})

var episodes = Guidebox.shows.episodes(6959, { include_links: true });

Return episodes in reverse order:

GET /v2/shows/{show_id}/episodes?reverse_ordering=true

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/episodes?api_key=YOUR_API_KEY&reverse_ordering=true

$episodes = $client->shows()->episodes(6959, [
    'reverse_ordering' => 'true'
]);

episodes = guidebox.Show.episodes(id=6959, reverse_ordering=True)

episodes = guidebox.shows.episodes(6959, {:reverse_ordering => true})

var episodes = Guidebox.shows.episodes(6959, { reverse_ordering: true });

Clips

List all clips for a given show.

Required: show_id - the ID for a specific show. See Shows for more information.

GET /v2/shows/{show_id}/clips

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/clips?api_key=YOUR_API_KEY

$clips = $client->shows()->clips(6959);

clips = guidebox.Show.clips(id=6959)

clips = guidebox.shows.clips(6959)

var clips = Guidebox.shows.clips(6959);

The clips endpoint is identical to the episodes endpoint, with the exception of one extra filter.

min_durationoptional

The minimum duration allowed, in seconds

Select only clips with a duration greater than 60 seconds:

GET /v2/shows/{show_id}/clips?min_duration=60

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/clips?api_key=YOUR_API_KEY&min_duration=60

$clips = $client->shows()->clips(6959, [
    'min_duration' => 60
]);

clips = guidebox.Show.clips(id=6959, min_duration=60)

clips = guidebox.shows.clips(6959, {:min_duration => 60})

var clips = Guidebox.shows.clips(6959, { min_duration: 60 });

Segments

List all segments for a given show. The segments endpoint is identical to the episodes endpoint.

Required: show_id - the ID for a specific show. See Shows for more information.

GET /v2/shows/{show_id}/segments

Example Request

$ curl http://api-public.guidebox.com/v2/shows/6959/segments?api_key=YOUR_API_KEY

$segments = $client->shows()->segments(6959);

segments = guidebox.Show.segments(id=6959)

segments = guidebox.shows.segments(6959)

var segments = Guidebox.shows.segments(6959);

Episode Details

Returns the details of an episode.

Required: episode_id - the ID for a specific episode. See above for more information.

GET /v2/episodes/{episode_id}

Example Request

$ curl http://api-public.guidebox.com/v2/episodes/100315?api_key=YOUR_API_KEY

$episode = $client->episodes()->get(100315);

episode = guidebox.Episode.retrieve(id=100315)

episode = guidebox.episodes.find(100315)

var episode = Guidebox.episodes.retrieve(100315);

Episode Images

Returns the images for a given episode.

Required: episode_id - the ID for a specific episode. See above for more information.

GET /v2/episodes/{episode_id}/images

Example Request

$ curl http://api-public.guidebox.com/v2/episodes/100315/images?api_key=YOUR_API_KEY

$images = $client->episodes()->images(100315);

images = guidebox.Episode.images(id=100315)

images = guidebox.episodes.images(100315)

var images = Guidebox.episodes.images(100315);

Clip Details

Returns the details of a clip.

Required: clip_id - the ID for a specific clip. See above for more information.

GET /v2/clips/{clip_id}

Example Request

$ curl http://api-public.guidebox.com/v2/clips/1072767?api_key=YOUR_API_KEY

$clip = $client->clips()->get(1072767);

clip = guidebox.Clip.retrieve(id=1072767)

clip = guidebox.clips.find(1072767)

var clip = Guidebox.clips.retrieve(1072767);

Clip Images

Returns the images for a given clip.

Required: clip_id - the ID for a specific clip. See above for more information.

GET /v2/clips/{clip_id}/images

Example Request

$ curl http://api-public.guidebox.com/v2/clips/1072767/images?api_key=YOUR_API_KEY

$images = $client->clips()->images(1072767);

images = guidebox.Clip.images(id=1072767)

images = guidebox.clips.images(1072767)

var clip = Guidebox.clips.images(1072767);

Segment Details

Returns the details of a segment.

Required: segment_id - the ID for a specific segment. See above for more information.

GET /v2/segments/{segment_id}

Example Request

$ curl http://api-public.guidebox.com/v2/segments/57954?api_key=YOUR_API_KEY

$segment = $client->segments()->get(57954);

segment = guidebox.Segment.retrieve(id=57954)

segment = guidebox.segments.find(57954)

var segment = Guidebox.segments.retrieve(57954);

Segment Images

Returns the images for a given segment.

Required: segment_id - the ID for a specific segment. See above for more information.

GET /v2/segments/{segment_id}/images

Example Request

$ curl http://api-public.guidebox.com/v2/segments/57954/images?api_key=YOUR_API_KEY

$images = $client->segments()->images(57954);

images = guidebox.Segment.images(id=57954)

images = guidebox.segments.images(57954)

var segment = Guidebox.segments.images(57954);

Channels

All of the shows in the Guidebox API are associated with one or more channels.

Get All Channels

Fetches a list of all channels. You may use the following arguments to filter:

typeoptional

Valid options include:

online
television

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 25

Number of records to return per request.

Select all Channels

GET /v2/channels

Example Request

$ curl http://api-public.guidebox.com/v2/channels?api_key=YOUR_API_KEY

$channels = $client->channels()->all();

channels = guidebox.Channel.list()

channels = guidebox.channels.list

var channels = Guidebox.channels.list();

Get Channel by ID

Returns the details of a single channel.

Example

GET /v2/channels/{id}

Example Request

$ curl http://api-public.guidebox.com/v2/channels/1?api_key=YOUR_API_KEY

$channel = $client->channels()->get(1);

channel = guidebox.Channel.retrieve(id=1)

channel = guidebox.channels.find(1)

var channels = Guidebox.channels.retrieve(1);

Get Channel Images

Returns the images from a single channel.

Example

GET /v2/channels/{id}/images

Example Request

$ curl http://api-public.guidebox.com/v2/channels/1/images?api_key=YOUR_API_KEY

$images = $client->channels()->images(1);

images = guidebox.Channel.images(id=1)

channel = guidebox.channels.images(1)

var channels = Guidebox.channels.images(1);

Genres

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

Get all Genres

Return a list of all genres

Example

GET /v2/genres

Example Request

$ curl http://api-public.guidebox.com/v2/genres?api_key=YOUR_API_KEY

$genres = $client->genres()->all();

genres = guidebox.Genre.list()

genres = guidebox.genres.list

var genres = Guidebox.genres.list();

Regions

Streaming titles are often geo-restricted by region.

Get all Regions

Return a list of all regions

Example

GET /v2/regions

Example Request

$ curl http://api-public.guidebox.com/v2/regions?api_key=YOUR_API_KEY

$regions = $client->regions()->all();

regions = guidebox.Region.list()

regions = guidebox.regions.list

var regions = Guidebox.regions.list();

Movies

Movies are a core entity in the Guidebox API.

Get all Movies

Returns the basic metadata for all movies for immediate playback. The results are ordered by popularity. You may get additional information about each movie using its movie ID. More on that below.

Available filters include:

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 25, max: 250

Number of records to return per request.

sourcesoptional

Filter shows by source. Valid options include:

free
tv_everywhere
subscription
purchase
A specific source, such as amazon_prime or hbo

Multiple sources may be comma-separated.

platformoptional

Filter by platform. Valid options include:

ios
android
web

include_preordersoptional

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, set this to true.

include_in_theatersoptional

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, set this to true.

Select all movies:

GET /v2/movies

Example Request

$ curl http://api-public.guidebox.com/v2/movies?api_key=YOUR_API_KEY

$movies = $client->movies()->all();

movies = guidebox.Movie.list()

movies = guidebox.movies.list

var movies = Guidebox.movies.list();

Select first 10 movies:

GET /v2/movies?limit=10

Example Request

$ curl http://api-public.guidebox.com/v2/movies?api_key=YOUR_API_KEY&limit=10

$movies = $client->movies()->all([
    'limit' => 10
]);

movies = guidebox.Movie.list(limit=10)

movies = guidebox.movies.list({:limit => 10})

var movies = Guidebox.movies.list({ limit: 10 });

Select free movies:

GET /v2/movies?sources=free

Example Request

$ curl http://api-public.guidebox.com/v2/movies?api_key=YOUR_API_KEY&sources=free

$movies = $client->movies()->all([
    'sources' => 'free'
]);

movies = guidebox.Movie.list(sources='free')

movies = guidebox.movies.list({:sources => 'free'})

var movies = Guidebox.movies.list({ sources: 'free' });

Select free movies on Amazon Prime:

GET /v2/movies?sources=free,amazon_prime

Example Request

$ curl http://api-public.guidebox.com/v2/movies?api_key=YOUR_API_KEY&sources=free,amazon_prime

$movies = $client->movies()->all([
    'sources' => 'free,amazon_prime'
]);

movies = guidebox.Movie.list(sources='free,amazon_prime')

movies = guidebox.movies.list({:sources => 'free,amazon_prime'})

var movies = Guidebox.movies.list({ sources: 'free,amazon_prime' });

Select movies available on iOS:

GET /v2/movies?platform=ios

Example Request

$ curl http://api-public.guidebox.com/v2/movies?api_key=YOUR_API_KEY&platform=ios

$movies = $client->movies()->all([
    'platform' => 'ios'
]);

movies = guidebox.Movie.list(platform='ios')

movies = guidebox.movies.list({:platform => 'ios'})

var movies = Guidebox.movies.list({ platform: 'ios' });

Get Specific Movie

Return the metadata associated with the specified movie.

Required - movie_id - the ID associated with a movie

Select all Related Movies

GET /v2/movies/{movie_id}

Example Request

$ curl http://api-public.guidebox.com/v2/movies/135934?api_key=YOUR_API_KEY

$movie = $client->movies()->get(135934);

movie = guidebox.Movie.retrieve(id=135934)

movie = guidebox.movies.find(135934)

var movie = Guidebox.movies.retrieve(135934);

Get Movie Images

Return a list of images for the specified movie.

Required - movie_id - the ID associated with a movie

Optional - filter - valid options include: thumbnails, posters, banners, backgrounds

Select all Images

GET /v2/movies/{movie_id}/images

Example Request

$ curl http://api-public.guidebox.com/v2/movies/135934/images?api_key=YOUR_API_KEY

$images = $client->movies()->images(135934);

images = guidebox.Movie.images(id=135934)

images = guidebox.movies.images(135934)

var images = Guidebox.movies.images(135934);

Select all Images that are posters

GET /v2/movies/{movie_id}/images?filter=posters

Example Request

$ curl http://api-public.guidebox.com/v2/movies/135934/images?api_key=YOUR_API_KEY&filter=posters

$images = $client->movies()->images(135934, [
    'filter' => 'posters',
]);

images = guidebox.Movie.images(id=135934, filter='posters')

images = guidebox.movies.images(135934, {:filter => 'posters'})

var images = Guidebox.movies.images(135934, { filter: 'posters' });

Get Related Movies

Return a list of movies related to the specified movie.

Required - movie_id - the ID associated with a movie

Select all Related Movies

GET /v2/movies/{movie_id}/related

Example Request

$ curl http://api-public.guidebox.com/v2/movies/135934/related?api_key=YOUR_API_KEY

$related = $client->movies()->related(135934);

related = guidebox.Movie.related(id=135934)

related = guidebox.movies.related(135934)

var related = Guidebox.movies.related(135934);

Get Movie Trailers

Return a list of trailers related to the specified movie.

Required - movie_id - the ID associated with a movie

Available filters include:

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 25

Number of records to return per request.

sourcesoptional

Filter shows by source. Valid options include:

youtube
guidebox

Select all Trailers

GET /v2/movies/{movie_id}/videos

Example Request

$ curl http://api-public.guidebox.com/v2/movies/135934/videos?api_key=YOUR_API_KEY

$trailers = $client->movies()->trailers(135934);

trailers = guidebox.Movie.trailers(id=135934)

trailers = guidebox.movies.trailers(135934)

var trailers = Guidebox.movies.trailers(135934);

Select first 10 Trailers

GET /v2/movies/{movie_id}/videos?limit=10

Example Request

$ curl http://api-public.guidebox.com/v2/movies/135934/videos?api_key=YOUR_API_KEY&limit=10

$trailers = $client->movies()->trailers(135934, [
    'limit' => 10
]);

trailers = guidebox.Movie.trailers(id=135934, limit=10)

trailers = guidebox.movies.trailers(135934, {:limit => 10})

var trailers = Guidebox.movies.trailers(135934, { limit: 10 });

Select Guidebox trailers

GET /v2/movies/{movie_id}/videos?sources=guidebox

Example Request

$ curl http://api-public.guidebox.com/v2/movies/135934/videos?api_key=YOUR_API_KEY&sources=guidebox

$trailers = $client->movies()->trailers(135934, [
    'sources' => 'guidebox'
]);

trailers = guidebox.Movie.trailers(id=135934, sources='guidebox')

trailers = guidebox.movies.trailers(135934, {:sources => 'guidebox'})

var trailers = Guidebox.movies.trailers(135934, { sources: 'guidebox' });

Sources

A Source is a place where the movie, episode, or clip can be found. For example, a show might be available on Netflix, Hulu, and NBC.com. Each of these three platforms would be a source.

For more information about usage of Sources and restrictions, please visit our Sources page.

Get all Sources

Returns a list of all sources.

typeoptional

The type of source. Valid options include: free, subscription, purchase, tv_everywhere

filteroptional

Valid options include: movie, show

Select all Sources

GET /v2/sources

Example Request

$ curl http://api-public.guidebox.com/v2/sources?api_key=YOUR_API_KEY

$sources = $client->sources()->all();

sources = guidebox.Source.list()

sources = guidebox.sources.list

var sources = Guidebox.sources.list();

Select free sources:

GET /v2/sources?type=free

Example Request

$ curl http://api-public.guidebox.com/v2/sources?api_key=YOUR_API_KEY&type=free

$sources = $client->sources()->all([
    'type' => 'free'
]);

sources = guidebox.Source.list(type='free')

sources = guidebox.sources.list({ :type => 'free' })

var sources = Guidebox.sources.list({ type: 'free' });

Select movie sources

GET /v2/sources?filter=movie

Example Request

$ curl http://api-public.guidebox.com/v2/sources?api_key=YOUR_API_KEY&filter=movie

$sources = $client->sources()->all([
    'filter' => 'movie'
]);

sources = guidebox.Source.list(filter='movie')

sources = guidebox.sources.list({ :filter => 'movie' })

var sources = Guidebox.sources.list({ filter: 'movie' });

Select free movie sources

GET /v2/sources?type=free&filter=movie

Example Request

$ curl http://api-public.guidebox.com/v2/sources?api_key=YOUR_API_KEY&type=free&filter=movie

$sources = $client->sources()->all([
    'type'   => 'free',
    'filter' => 'movie'
]);

sources = guidebox.Source.list(type='free', filter='movie')

sources = guidebox.sources.list({ :filter => 'movie', :type => 'free' })

var sources = Guidebox.sources.list({ filter: 'movie', type: 'free' });

Persons

A Person is a core entity in the Guidebox API. These make up the cast/crew of a given title.

Retrieve a single person

This endpoint retrieves the details for a single person.

GET /v2/person/{id}

Example Request

$ curl http://api-public.guidebox.com/v2/person/212668?api_key=YOUR_API_KEY

$person = $client->persons()->get(212668);

person = guidebox.Person.retrieve(id=212668)

person = guidebox.person.find(212668)

var person = Guidebox.person.retrieve(212668);

Retrieve all images for a single person

This endpoint retrieves the images for a single person.

GET /v2/person/{id}/images

Example Request

$ curl http://api-public.guidebox.com/v2/person/212668/images?api_key=YOUR_API_KEY

$images = $client->persons()->images(212668);

images = guidebox.Person.images(id=212668)

images = guidebox.person.images(212668)

var images = Guidebox.person.images(212668);

Retrieve all credits for a single person

This endpoint retrieves the credits for a single person.

Available parameters include:

rolerequired

Valid roles include: cast, crew

typeoptional

Valid types include: movie, show

Select all cast credits

GET /v2/person/{id}/credits?role=cast

Example Request

$ curl http://api-public.guidebox.com/v2/person/212668/credits?api_key=YOUR_API_KEY&role=cast

$credits = $client->persons()->credits(212668, [
    'role' => 'cast'
]);

credits = guidebox.Person.credits(id=212668, role='cast')

credits = guidebox.person.credits(212668, {:role => 'cast'})

var credits = Guidebox.person.credits(212668, { role: 'cast' });

Select all crew credits

GET /v2/person/{id}/credits?role=crew

Example Request

$ curl http://api-public.guidebox.com/v2/person/212668/credits?api_key=YOUR_API_KEY&role=crew

$credits = $client->persons()->credits(212668, [
    'role' => 'crew'
]);

credits = guidebox.Person.credits(id=212668, role='crew')

credits = guidebox.person.credits(212668, {:role => 'crew'})

var credits = Guidebox.person.credits(212668, { role: 'crew' });

Select all cast credits from movies

GET /v2/person/{id}/credits?role=cast&type=movie

Example Request

$ curl http://api-public.guidebox.com/v2/person/212668/credits?api_key=YOUR_API_KEY&role=cast&type=movie

$credits = $client->persons()->credits(212668, [
    'role' => 'cast',
    'type' => 'movie',
]);

credits = guidebox.Person.credits(id=212668, role='cast', type='movie')

credits = guidebox.person.credits(212668, {:role => 'cast', :type => 'movie'})

var credits = Guidebox.person.credits(212668, { role: 'cast', type: 'movie' });

Search

The Guidebox API exposes a slick interface to let you search our API for movies, shows, and people!

Search

Returns a list of titles that match the query.

typerequired

The type of entity. Valid options include: movie, channel, person, show

fieldoptional

Valid options are different, depending on type:

Shows: title, id
Movies: title, id
Channels: not required
Person: not required

precisionoptional, default: fuzzy

How exact the search query should be. Valid options include: exact, fuzzy

id_typeoptional

Valid options are different, depending on type:

Shows: tvdb, themoviedb, imdb
Movies: imdb, themoviedb
Channels: not required
Person: not required

Search Movies by Title

GET /v2/search?type=movie&field=title&query=Terminator

Example Request

$ curl http://api-public.guidebox.com/v2/search?api_key=YOUR_API_KEY&type=movie&field=title&query=Terminator

$results = $client->search()->movies([
    'field' => 'title',
    'query' => 'Terminator'
]);

results = guidebox.Search.movies(field='title', query='Terminator')

results = guidebox.search.movies({
    :field => 'title',
    :query => 'Terminator'
})

var results = Guidebox.search.movies({field: 'title', query: 'Terminator'});

Search Shows by ID:

GET /v2/search?type=movie&field=id&id_type=imdb&query=tt1826940

Example Request

$ curl http://api-public.guidebox.com/v2/search?api_key=YOUR_API_KEY&type=movie&field=id&id_type=imdb&query=tt1826940

$results = $client->search()->shows([
    'field' => 'id',
    'id_type' => 'imdb',
    'query' => 'tt1826940'
]);

results = guidebox.Search.shows(field='id', id_type='imdb', query='tt1826940')

results = guidebox.search.shows({
    :field => 'id',
    :id_type => 'imdb',
    :query => 'tt1826940'
})

var results = Guidebox.search.shows({field: 'id', id_type: 'imdb', query: 'tt1826940'});

Search Person:

GET /v2/search?type=person&query=Harrison+Ford

Example Request

$ curl http://api-public.guidebox.com/v2/search?api_key=YOUR_API_KEY&type=person&query=Harrison+Ford

$results = $client->search()->person([
    'query' => 'Harrison Ford'
]);

results = guidebox.Search.person(query='Harrison Ford')

results = guidebox.search.person({
    :query => 'Harrison Ford'
})

var results = Guidebox.search.person({query: 'Harrison Ford'});

Search Channel:

GET /v2/search?type=channel&query=ABC

Example Request

$ curl http://api-public.guidebox.com/v2/search?api_key=YOUR_API_KEY&type=channel&query=ABC

$results = $client->search()->channels([
    'query' => 'ABC'
]);

results = guidebox.Search.channels(query='ABC')

results = guidebox.search.channels({
    :query => 'ABC'
})

var results = Guidebox.search.channels({query: 'ABC'});

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.

Show Updates

Returns recently updated shows.

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 100

Number of records to return per request.

objectrequired

For getting show updates, this value should be show

typerequired

Type of update to retrieve. Valid options include:

new
changes
deletes
new_episodes
new_clips
new_segments
changed_episodes

timerequired

Unix timestamp from which to begin the update list

Shows

Get New Shows

GET /v2/updates?object=show&type=new&time=1568915256

$ curl http://api-public.guidebox.com/v2/updates?api_key=YOUR_API_KEY

$updates = $client->updates()->all([
    'object' => 'show',
    'type' => 'new',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='show', type='new', time=1568915256)

updates = guidebox.updates.list({ :object='show', :type='new', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'show', type: 'new', time: 1568915256 });

Get New Episodes for a Show

GET /v2/updates?object=show&type=new_episodes&time=1568915256

$updates = $client->updates()->all([
    'object' => 'show',
    'type' => 'new_episodes',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='show', type='new_episodes', time=1568915256)

updates = guidebox.updates.list({ :object='show', :type='new_episodes', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'show', type: 'new_episodes', time: 1568915256 });

Get Changed Episodes for a Show

GET /v2/updates?object=show&type=changed_episodes&time=1568915256

$updates = $client->updates()->all([
    'object' => 'show',
    'type' => 'changed_episodes',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='show', type='changed_episodes', time=1568915256)

updates = guidebox.updates.list({ :object='show', :type='changed_episodes', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'show', type: 'changed_episodes', time: 1568915256 });

Get New Clips for a Show

GET /v2/updates?object=show&type=new_clips&time=1568915256

$updates = $client->updates()->all([
    'object' => 'show',
    'type' => 'new_clips',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='show', type='new_clips', time=1568915256)

updates = guidebox.updates.list({ :object='show', :type='new_clips', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'show', type: 'new_clips', time: 1568915256 });

Get New Segments for a Show

GET /v2/updates?object=show&type=new_segments&time=1568915256

$updates = $client->updates()->all([
    'object' => 'show',
    'type' => 'new_clips',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='show', type='new_clips', time=1568915256)

updates = guidebox.updates.list({ :object='show', :type='new_clips', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'show', type: 'new_clips', time: 1568915256 });

Episode Updates

Returns recently updated episodes.

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 100

Number of records to return per request.

objectrequired

For getting episode updates, this value should be episode

typerequired

Type of update to retrieve. Valid options include:

new
changes
deletes

timerequired

Unix timestamp from which to begin the update list

idoptional

If you want to filter by show ID, you may supply it here.

Episodes

Get Episode Changes

GET /v2/updates?object=episode&type=changes&time=1568915256&id=6959

$updates = $client->updates()->all([
    'object' => 'episode',
    'type' => 'changes',
    'time' => 1568915256,
    'id' => 6959
]);

updates = guidebox.Genre.all(object='episode', type='changes', time=1568915256, id=6959)

updates = guidebox.updates.list({ :object='episode', :type='changes', :time=1568915256, :id=6959 })

var updates = Guidebox.updates.list({ object: 'episode', type: 'changes', time: 1568915256, id: 6959});

Get New Episodes

GET /v2/updates?object=episode&type=new&time=1568915256&id=6959

$updates = $client->updates()->all([
    'object' => 'episode',
    'type' => 'new',
    'time' => 1568915256,
    'id' => 6959
]);

updates = guidebox.Genre.all(object='episode', type='new', time=1568915256, id=6959)

updates = guidebox.updates.list({ :object='episode', :type='new', :time=1568915256, :id=6959 })

var updates = Guidebox.updates.list({ object: 'episode', type: 'new', time: 1568915256, id: 6959 });

Get Deleted Episodes

GET /v2/updates?object=episode&type=deletes&time=1568915256

$updates = $client->updates()->all([
    'object' => 'episode',
    'type' => 'deletes',
    'time' => 1568915256,
    'id' => 6959
]);

updates = guidebox.Genre.all(object='episode', type='deletes', time=1568915256, id=6959)

updates = guidebox.updates.list({ :object='episode', :type='deletes', :time=1568915256, :id=6959 })

var updates = Guidebox.updates.list({ object: 'episode', type: 'deletes', time: 1568915256, id: 6959});

Clips Updates

Get Clip Changes

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 100

Number of records to return per request.

objectrequired

For getting clip updates, this value should be clip

typerequired

Type of update to retrieve. Valid options include:

new
changes
deletes

timerequired

Unix timestamp from which to begin the update list

Clips

Get Clip Changes

GET /v2/updates?object=clip&type=changes&time=1568915256

$updates = $client->updates()->all([
    'object' => 'clip',
    'type' => 'changes',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='clip', type='changes', time=1568915256)

updates = guidebox.updates.list({ :object='clip', :type='changes', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'clip', type: 'changes', time: 1568915256 });

Get New Clips

GET /v2/updates?object=clip&type=new&time=1568915256

$updates = $client->updates()->all([
    'object' => 'clip',
    'type' => 'new',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='clip', type='new', time=1568915256)

updates = guidebox.updates.list({ :object='clip', :type='new', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'clip', type: 'new', time: 1568915256 });

Get Deleted Clips

GET /v2/updates?object=clip&type=deletes&time=1568915256

$updates = $client->updates()->all([
    'object' => 'clip',
    'type' => 'deletes',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='clip', type='deletes', time=1568915256)

updates = guidebox.updates.list({ :object='clip', :type='deletes', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'clip', type: 'deletes', time: 1568915256 });

Segments Updates

Get Segment Changes

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 100

Number of records to return per request.

objectrequired

For getting segment updates, this value should be segment

typerequired

Type of update to retrieve. Valid options include:

new
changes
deletes

timerequired

Unix timestamp from which to begin the update list

GET /v2/updates?object=segment&type=changes&time=1568915256

$updates = $client->updates()->all([
    'object' => 'segments',
    'type' => 'changes',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='segments', type='changes', time=1568915256)

updates = guidebox.updates.list({ :object='segments', :type='changes', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'segments', type: 'changes', time: 1568915256 });

Get New Segments

GET /v2/updates?object=segment&type=new&time=1568915256

$updates = $client->updates()->all([
    'object' => 'segments',
    'type' => 'new',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='segments', type='new', time=1568915256)

updates = guidebox.updates.list({ :object='segments', :type='new', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'segments', type: 'new', time: 1568915256 });

Get Deleted Segments

GET /v2/updates?object=segment&type=deletes&time=1568915256

$updates = $client->updates()->all([
    'object' => 'segments',
    'type' => 'deletes',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='segments', type='deletes', time=1568915256)

updates = guidebox.updates.list({ :object='segments', :type='deletes', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'segments', type: 'deletes', time: 1568915256 });

Movies Updates

Get Movie Changes

offsetoptional, default: 0

Skips this number of records. Useful for pagination.

limitoptional, default: 100

Number of records to return per request.

objectrequired

For getting movie updates, this value should be movie

typerequired

Type of update to retrieve. Valid options include:

new
changes
deletes

timerequired

Unix timestamp from which to begin the update list

GET /v2/updates?object=movie&type=changes&time=1568915256

$updates = $client->updates()->all([
    'object' => 'movie',
    'type' => 'changes',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='movie', type='changes', time=1568915256)

updates = guidebox.updates.list({ :object='movie', :type='changes', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'movie', type: 'changes', time: 1568915256 });

Get New Movies

GET /v2/updates?object=movie&type=new&time=1568915256

$updates = $client->updates()->all([
    'object' => 'movie',
    'type' => 'new',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='movie', type='new', time=1568915256)

updates = guidebox.updates.list({ :object='movie', :type='new', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'movie', type: 'new', time: 1568915256 });

Get Deleted Movies

GET /v2/updates?object=movie&type=deletes&time=1568915256

$updates = $client->updates()->all([
    'object' => 'movie',
    'type' => 'deletes',
    'time' => 1568915256
]);

updates = guidebox.Genre.all(object='movie', type='deletes', time=1568915256)

updates = guidebox.updates.list({ :object='movie', :type='deletes', :time=1568915256 })

var updates = Guidebox.updates.list({ object: 'movie', type: 'deletes', time: 1568915256 });

Documentation

Version 2.0

API Documentation

Examples

Introduction

Base API URL

Authentication

Setting a Region

Using Other Regions

API Limits

Quotas

Headers

Header

API Endpoint

API Endpoint

Example Request

Shows

List all Shows

channeloptional

offsetoptional, default: 0

limitoptional, default: 25

sourcesoptional

platformoptional

tagsoptional

Base URL

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Retrieve a single show

Example Request

Retrieve all seasons for a single show

Example Request

Retrieve all images for a single show

Example Request

Example Request

Retrieve all related shows for a single show

Example Request

Retrieve all available content for a single show

Example Request

Episodes, Clips, and Segments

What are "Episodes"?

What are "Clips"?

What are "Segments"?

List all episodes

seasonoptional

offsetoptional, default: 0

limitoptional, default: 25

sourcesoptional

platformoptional

include_linksoptional

reverse_orderingoptional

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Clips

Example Request

min_durationoptional

Example Request

Segments

Example Request

Episode Details

Example Request

Episode Images

Example Request

Clip Details

Example Request

Clip Images

Example Request

Segment Details

Example Request