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.
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.
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}
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
$genres = $client->genres()->all();
genres = guidebox.Genre.list()
genres = guidebox.genres.list
var genres = Guidebox.genres.list();
As a Header
Authorization: YOUR_API_KEY
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
Each API key is allowed to make a limited number of requests per month. If you need to make more requests, please contact Guidebox.
Each API response will return a header that contains your max requests per billing period, as well as the progress toward that quota.
Guidebox-Quota:3995
Guidebox-Quota-Max:150000
Alternately, you may use our API Endpoint to retrieve your current quota details.
GET /v2/quota
$ 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();
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.
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:
Filter shows by a particular channel using the short_name field from the Channels section below.
Skips this number of records. Useful for pagination.
Number of records to return per request.
Filter shows by source. Valid options include:
Multiple sources may be comma-separated.
Note: this does not filter clips
Filter by platform. Valid options include:
Filter show by tags. You may retrieve a list of tags from the Tags endpoint.
GET /v2/shows
$ 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
$ 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
$ 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
$ 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
$ 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
$ 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
$ 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
$ 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
$ 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' });
This endpoint retrieves the details for a single show.
GET /v2/shows/{id}
$ 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);
This endpoint retrieves a list of the seasons for a single show.
GET /v2/shows/{id}/seasons
$ 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);
This endpoint retrieves a list of the images for a single show.
You may also filter by image size:
GET /v2/shows/{id}/images
$ 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
$ 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' });
This endpoint retrieves a list of the related shows for a single show.
GET /v2/shows/{id}/related
$ 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);
This endpoint retrieves the available content for a single show.
GET /v2/shows/{id}/available_content
$ 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 are full length videos associated with a particular show. Episodes are grouped into seasons and ordered by episode number.
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.
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.
Required: show_id - the ID for a specific show. See Shows for more information.
The following filters are available:
A particular season for a show.
Skips this number of records. Useful for pagination.
Number of records to return per request.
Filter shows by source. Valid options include:
Multiple sources may be comma-separated.
Filter by platform. Valid options include:
Provide a value of true if you would like to return streaming or purchase links.
Returns the episodes in descending order of release date. Used to show most recent episodes.
Select all episodes:
GET /v2/shows/{show_id}/episodes
$ 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
$ 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
$ 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
$ 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
$ 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
$ 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
$ 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 });
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
$ 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.
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
$ 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 });
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
$ 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);
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}
$ 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);
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
$ 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);
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}
$ 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);
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
$ 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);
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}
$ 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);
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
$ 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);
All of the shows in the Guidebox API are associated with one or more channels.
Fetches a list of all channels. You may use the following arguments to filter:
Valid options include:
Skips this number of records. Useful for pagination.
Number of records to return per request.
Select all Channels
GET /v2/channels
$ 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();
Returns the details of a single channel.
Example
GET /v2/channels/{id}
$ 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);
Returns the images from a single channel.
Example
GET /v2/channels/{id}/images
$ 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 are broad categorizations like "comedy" or "drama".
Return a list of all genres
Example
GET /v2/genres
$ 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();
Movies are a core entity in the Guidebox API.
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:
Skips this number of records. Useful for pagination.
Number of records to return per request.
Filter shows by source. Valid options include:
Multiple sources may be comma-separated.
Filter by platform. Valid options include:
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.
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
$ 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
$ 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
$ 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
$ 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
$ 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' });
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}
$ 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);
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
$ 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
$ 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' });
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
$ 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);
Return a list of trailers related to the specified movie.
Required - movie_id - the ID associated with a movie
Available filters include:
Skips this number of records. Useful for pagination.
Number of records to return per request.
Filter shows by source. Valid options include:
Select all Trailers
GET /v2/movies/{movie_id}/videos
$ 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
$ 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
$ 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' });
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.
Returns a list of all sources.
The type of source. Valid options include: free, subscription, purchase, tv_everywhere
Valid options include: movie, show
Select all Sources
GET /v2/sources
$ 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
$ 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
$ 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
$ 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' });
A Person is a core entity in the Guidebox API. These make up the cast/crew of a given title.
This endpoint retrieves the details for a single person.
GET /v2/person/{id}
$ 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);
This endpoint retrieves the images for a single person.
GET /v2/person/{id}/images
$ 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);
This endpoint retrieves the credits for a single person.
Available parameters include:
Valid roles include: cast, crew
Valid types include: movie, show
Select all cast credits
GET /v2/person/{id}/credits?role=cast
$ 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
$ 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
$ 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' });
The Guidebox API exposes a slick interface to let you search our API for movies, shows, and people!
Returns a list of titles that match the query.
The type of entity. Valid options include: movie, channel, person, show
Valid options are different, depending on type:
How exact the search query should be. Valid options include: exact, fuzzy
Valid options are different, depending on type:
Search Movies by Title
GET /v2/search?type=movie&field=title&query=Terminator
$ 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
$ 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
$ 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
$ 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'});
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.
Returns recently updated shows.
Skips this number of records. Useful for pagination.
Number of records to return per request.
For getting show updates, this value should be show
Type of update to retrieve. Valid options include:
Unix timestamp from which to begin the update list
Get New Shows
GET /v2/updates?object=show&type=new&time=1653424961
$ curl http://api-public.guidebox.com/v2/updates?api_key=YOUR_API_KEY
$updates = $client->updates()->all([
'object' => 'show',
'type' => 'new',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='show', type='new', time=1653424961)
updates = guidebox.updates.list({ :object='show', :type='new', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'show', type: 'new', time: 1653424961 });
Get New Episodes for a Show
GET /v2/updates?object=show&type=new_episodes&time=1653424961
$updates = $client->updates()->all([
'object' => 'show',
'type' => 'new_episodes',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='show', type='new_episodes', time=1653424961)
updates = guidebox.updates.list({ :object='show', :type='new_episodes', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'show', type: 'new_episodes', time: 1653424961 });
Get Changed Episodes for a Show
GET /v2/updates?object=show&type=changed_episodes&time=1653424961
$updates = $client->updates()->all([
'object' => 'show',
'type' => 'changed_episodes',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='show', type='changed_episodes', time=1653424961)
updates = guidebox.updates.list({ :object='show', :type='changed_episodes', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'show', type: 'changed_episodes', time: 1653424961 });
Get New Clips for a Show
GET /v2/updates?object=show&type=new_clips&time=1653424961
$updates = $client->updates()->all([
'object' => 'show',
'type' => 'new_clips',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='show', type='new_clips', time=1653424961)
updates = guidebox.updates.list({ :object='show', :type='new_clips', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'show', type: 'new_clips', time: 1653424961 });
Get New Segments for a Show
GET /v2/updates?object=show&type=new_segments&time=1653424961
$updates = $client->updates()->all([
'object' => 'show',
'type' => 'new_clips',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='show', type='new_clips', time=1653424961)
updates = guidebox.updates.list({ :object='show', :type='new_clips', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'show', type: 'new_clips', time: 1653424961 });
Returns recently updated episodes.
Skips this number of records. Useful for pagination.
Number of records to return per request.
For getting episode updates, this value should be episode
Type of update to retrieve. Valid options include:
Unix timestamp from which to begin the update list
If you want to filter by show ID, you may supply it here.
Get Episode Changes
GET /v2/updates?object=episode&type=changes&time=1653424961&id=6959
$updates = $client->updates()->all([
'object' => 'episode',
'type' => 'changes',
'time' => 1653424961,
'id' => 6959
]);
updates = guidebox.Genre.all(object='episode', type='changes', time=1653424961, id=6959)
updates = guidebox.updates.list({ :object='episode', :type='changes', :time=1653424961, :id=6959 })
var updates = Guidebox.updates.list({ object: 'episode', type: 'changes', time: 1653424961, id: 6959});
Get New Episodes
GET /v2/updates?object=episode&type=new&time=1653424961&id=6959
$updates = $client->updates()->all([
'object' => 'episode',
'type' => 'new',
'time' => 1653424961,
'id' => 6959
]);
updates = guidebox.Genre.all(object='episode', type='new', time=1653424961, id=6959)
updates = guidebox.updates.list({ :object='episode', :type='new', :time=1653424961, :id=6959 })
var updates = Guidebox.updates.list({ object: 'episode', type: 'new', time: 1653424961, id: 6959 });
Get Deleted Episodes
GET /v2/updates?object=episode&type=deletes&time=1653424961
$updates = $client->updates()->all([
'object' => 'episode',
'type' => 'deletes',
'time' => 1653424961,
'id' => 6959
]);
updates = guidebox.Genre.all(object='episode', type='deletes', time=1653424961, id=6959)
updates = guidebox.updates.list({ :object='episode', :type='deletes', :time=1653424961, :id=6959 })
var updates = Guidebox.updates.list({ object: 'episode', type: 'deletes', time: 1653424961, id: 6959});
Get Clip Changes
Skips this number of records. Useful for pagination.
Number of records to return per request.
For getting clip updates, this value should be clip
Type of update to retrieve. Valid options include:
Unix timestamp from which to begin the update list
Get Clip Changes
GET /v2/updates?object=clip&type=changes&time=1653424961
$updates = $client->updates()->all([
'object' => 'clip',
'type' => 'changes',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='clip', type='changes', time=1653424961)
updates = guidebox.updates.list({ :object='clip', :type='changes', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'clip', type: 'changes', time: 1653424961 });
Get New Clips
GET /v2/updates?object=clip&type=new&time=1653424961
$updates = $client->updates()->all([
'object' => 'clip',
'type' => 'new',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='clip', type='new', time=1653424961)
updates = guidebox.updates.list({ :object='clip', :type='new', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'clip', type: 'new', time: 1653424961 });
Get Deleted Clips
GET /v2/updates?object=clip&type=deletes&time=1653424961
$updates = $client->updates()->all([
'object' => 'clip',
'type' => 'deletes',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='clip', type='deletes', time=1653424961)
updates = guidebox.updates.list({ :object='clip', :type='deletes', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'clip', type: 'deletes', time: 1653424961 });
Get Segment Changes
Skips this number of records. Useful for pagination.
Number of records to return per request.
For getting segment updates, this value should be segment
Type of update to retrieve. Valid options include:
Unix timestamp from which to begin the update list
GET /v2/updates?object=segment&type=changes&time=1653424961
$updates = $client->updates()->all([
'object' => 'segments',
'type' => 'changes',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='segments', type='changes', time=1653424961)
updates = guidebox.updates.list({ :object='segments', :type='changes', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'segments', type: 'changes', time: 1653424961 });
Get New Segments
GET /v2/updates?object=segment&type=new&time=1653424961
$updates = $client->updates()->all([
'object' => 'segments',
'type' => 'new',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='segments', type='new', time=1653424961)
updates = guidebox.updates.list({ :object='segments', :type='new', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'segments', type: 'new', time: 1653424961 });
Get Deleted Segments
GET /v2/updates?object=segment&type=deletes&time=1653424961
$updates = $client->updates()->all([
'object' => 'segments',
'type' => 'deletes',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='segments', type='deletes', time=1653424961)
updates = guidebox.updates.list({ :object='segments', :type='deletes', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'segments', type: 'deletes', time: 1653424961 });
Get Movie Changes
Skips this number of records. Useful for pagination.
Number of records to return per request.
For getting movie updates, this value should be movie
Type of update to retrieve. Valid options include:
Unix timestamp from which to begin the update list
GET /v2/updates?object=movie&type=changes&time=1653424961
$updates = $client->updates()->all([
'object' => 'movie',
'type' => 'changes',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='movie', type='changes', time=1653424961)
updates = guidebox.updates.list({ :object='movie', :type='changes', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'movie', type: 'changes', time: 1653424961 });
Get New Movies
GET /v2/updates?object=movie&type=new&time=1653424961
$updates = $client->updates()->all([
'object' => 'movie',
'type' => 'new',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='movie', type='new', time=1653424961)
updates = guidebox.updates.list({ :object='movie', :type='new', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'movie', type: 'new', time: 1653424961 });
Get Deleted Movies
GET /v2/updates?object=movie&type=deletes&time=1653424961
$updates = $client->updates()->all([
'object' => 'movie',
'type' => 'deletes',
'time' => 1653424961
]);
updates = guidebox.Genre.all(object='movie', type='deletes', time=1653424961)
updates = guidebox.updates.list({ :object='movie', :type='deletes', :time=1653424961 })
var updates = Guidebox.updates.list({ object: 'movie', type: 'deletes', time: 1653424961 });