Overview

This describes the resources that make up the official TVShow Time API v1. If you have any problems or requests please contact support.

All API access is over HTTPS, and accessed from the api.tvshowtime.com domain. All data is sent and received as JSON.

Getting Started

The TVShow Time API can only be accessed via OAuth 2.0. This is really important to help us track usage of the API by your applications while keeping our users’ data safe. It’s a standard used by various large API providers, including the Facebook Graph API.

Registering your app

OAuth2 is a protocol that lets external apps request authorization to private details in a user’s TVShow Time account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.

All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

To register your app, contact us at api@tvshowtime.com.

Note that we don't provide API access for personal usage.

Web Application Flow

This is a description of the OAuth2 flow from 3rd party web sites.

  1. Redirect users to request TVShow Time access

    GET https://www.tvshowtime.com/oauth/authorize
    

    Parameters

    Name Type Description
    client_id string Required. The client ID you received from TVShow Time when you registered.
    redirect_uri string The URL in your app where users will be sent after authorization. See details below about redirect urls.
    state string An unguessable random string. It is used to protect against cross-site request forgery attacks.
  2. TVShow Time redirects back to your site

    If the user accepts your request, TVShow Time redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.

    https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE
    
  3. Exchange the previous code for an access token

    POST https://api.tvshowtime.com/v1/oauth/access_token
    

    Parameters

    Name Type Description
    client_id string Required. The client ID you received from TVShow Time when you registered.
    client_secret string Required. The client secret you received from TVShow Time when you registered.
    code string Required. The code you received as a response to Step 2.
    redirect_uri string The URL in your app where users will be sent after authorization. See details below about redirect urls.

    Response

    { 'result': 'OK', 'access_token': ACCESS_TOKEN }
    
  4. Use the access token to access the API

    The access token allows you to make requests to the API on a behalf of a user.

    GET https://api.tvshowtime.com/v1/user?access_token=...
    

    You can pass the token in the query params like shown above, but a cleaner approach is to include it in the header

    TVST_ACCESS_TOKEN: OAUTH-TOKEN
    

    For example, in curl you can set the header like this:

    curl -H "TVST_ACCESS_TOKEN: OAUTH-TOKEN" https://api.tvshowtime.com/v1/user
    

Redirect URLs

The redirect_uri parameter is optional. If left out, TVShow Time will redirect users to the callback URL configured in the OAuth Application settings. If provided, the redirect URL’s host and port must exactly match the callback URL. The redirect URL’s path must reference a subdirectory of the callback URL.

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

Limited Device flow

This OAuth 2.0 flow is designed for applications that run on devices with limited input capabilities, such as game consoles or video cameras. In this flow, the user interacts with an application on the device to obtain a URL and a device code. The user then switches to another device, such as a computer or smartphone, that has richer input capabilities to authorize the device code.

This flow has the following steps:

  1. Request a device code

    POST https://api.tvshowtime.com/v1/oauth/device/code
    

    Parameters

    Name Type Description
    client_id string Required. The client ID you received from TVShow Time when you registered.

    Response

    { 
        'result': 'OK', 
        'device_code': DEVICE_CODE, 
        'user_code': USER_CODE, 
        'verification_url': VERIFICATION_URL, 
        'expires_in': 900, 
        'interval': 5 
    }
    
  2. Display USER_CODE and VERIFICATION_URL to the user

    The application on your device should display the user_code and verification_url to the user. It should store the device_code, expires_in, and interval values for use in step 3.

  3. Begin polling TVShow Time's authorization server

    Your application can begin polling TVShow Time's authorization server using the device_code returned in the JSON response in step 1. The interval returned in the JSON response in step 1 specifies the minimum amount of time, in seconds, that your application should wait between polling requests.

    POST https://api.tvshowtime.com/v1/oauth/access_token
    

    Parameters

    Name Type Description
    client_id string Required. The client ID you received from TVShow Time when you registered.
    client_secret string Required. The client secret you received from TVShow Time when you registered.
    code string Required. The device code you received as a response to Step 1.

    Until the user completes steps 4 through 6, your application receives one of the following responses to each polling request:

    Response

    { 'result': 'KO', 'message': 'Authorization pending' }
    { 'result': 'KO', 'message': 'Slow down' }
    
  4. User enters user_code in separate browser

    The user launches a browser on another device, such as a computer or mobile phone, and navigates to the verification_url. That URL displays a page where the user can enter the user_code obtained in step 1.

    Note: The user_code is case-sensitive, so the user needs to enter it exactly as it appears in the response.

  5. User logs in to TVShow Time Account

    After entering the user_code, the user is asked to log in to the TVShow Time Account that will be used to authorize API requests from your device. (Users who are already logged in proceed directly to the next step.)

  6. User consent decision

    After the user logs in, TVShow Time's authorization server displays a page that shows the name of your application. The user can then consent or refuse to grant access to your application.

  7. Process response from polling server to obtain tokens

    If the user grants access to your application, the next polling request that your device sends returns a JSON object that contains an access token.

    Response

    { 'result': 'OK', 'access_token': ACCESS_TOKEN }
    

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests. you can read the CORS W3C working draft, or this intro from the HTML 5 Security Guide.

Rate Limiting

For requests using OAuth, you can make up to 10 requests per minute (i.e per user).

You can check the returned HTTP headers of any API request to see your current rate limit status:

The headers tell you everything you need to know about your current rate limit status:

Header Name Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

Once you go over the rate limit you will receive an error response:

HTTP/1.1 403 Forbidden
Date: Tue, 2 Jul 2014 01:02:03 GMT
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1391734983

{ 'code': 403, 'result': 'KO', 'message': 'API rate limit exceeded.' }

Errors

Access denied

If the user rejects access to your application, TVShow Time will redirect to the registered callback URL with the following parameters summarizing the error:

http://example.com/callback?error=access_denied
  &error_description=The+user+has+denied+your+application+access.
  &error_uri=https://api.tvshowtime.com/doc
  &state=xyz

There’s nothing you can do here as users are free to choose not to use your application. More often than not, users will just close the window or press back in their browser, so it is likely that you’ll never see this error.

Other errors

If there is an error, the API will return

{ 'result': 'KO', 'message': 'The Error Message' }

Find out more

Episode Item Parameter

You can give one of these parameters bundle when using a method that needs an episode item:

Name Type Description
filename string Required*. The filename of the episode. e.g. "game.of.thrones.s04e10.720p.hdtv.x264-killers.mkv"

OR

Name Type Description
episode_id integer Required*. The TVDB ID of the episode.

OR

Name Type Description
imdb_id string Required*. The IMDB ID of the episode.

OR

Name Type Description
show_id integer Required*. The TVDB ID of the show.
season_number integer Required*. Season number of the episode.
number integer Required*. Episode number of the episode.

Methods

User

GET https://api.tvshowtime.com/v1/user

Get the user info.

To-Watch

GET https://api.tvshowtime.com/v1/to_watch

Get the user to-watch list.

Parameters

Name Type Description
page integer Page number. Default: 0
limit integer Elements per page. Default: 10
lang string Language of the content (en, fr, es, it, pt). Default: user lang

Agenda

GET https://api.tvshowtime.com/v1/agenda

Get the user agenda.

Parameters

Name Type Description
page integer Page number. Default: 0
limit integer Elements per page. Default: 10
include_watched boolean Include watched episodes in results.

Tips

boolean type is in fact 0 or 1, not true / false.

Library

GET https://api.tvshowtime.com/v1/library

Get the user library.

Parameters

Name Type Description
page integer Page number. Default: 0
limit integer Elements per page. Default: 10

Explore

GET https://api.tvshowtime.com/v1/explore

Discover trending shows.

Parameters

Name Type Description
page integer Page number. Default: 0
limit integer Elements per page. Default: 10

Show

GET https://api.tvshowtime.com/v1/show

Get show data.

Parameters

Name Type Description
show_id integer Required*. The TVDB ID of the show.
show_name string Required*. The name of the show.
include_episodes boolean Include all episodes in results.
exact boolean Exact match for show name. Default: 0

Response

{ 'result': 'OK', 'show': Object }

Tips

boolean type is in fact 0 or 1, not true / false.

Follow

POST https://api.tvshowtime.com/v1/follow

Follow a show.

Parameters

Name Type Description
show_id integer Required*. The TVDB ID of the show.

Response

{ 'result': 'OK' }

Is Followed

GET https://api.tvshowtime.com/v1/follow

Check if a show is followed.

Parameters

Name Type Description
show_id integer Required*. The TVDB ID of the show.

Response

{ 'result': 'OK', 'code': 0|1 } // O = not followed, 1 = followed

Unfollow

DELETE https://api.tvshowtime.com/v1/follow

OR

POST https://api.tvshowtime.com/v1/unfollow

Unfollow a show.

Parameters

Name Type Description
show_id integer Required*. The TVDB ID of the show.

Response

{ 'result': 'OK' }

Archive

POST https://api.tvshowtime.com/v1/archive

Archive a show.

Parameters

Name Type Description
show_id integer Required*. The TVDB ID of the show.

Response

{ 'result': 'OK' }

Is Archived

GET https://api.tvshowtime.com/v1/archive

Check if a show is archived.

Parameters

Name Type Description
show_id integer Required*. The TVDB ID of the show.

Response

{ 'result': 'OK', 'code': 0|1 } // O = not followed, 1 = followed

Unarchive

DELETE https://api.tvshowtime.com/v1/archive

OR

POST https://api.tvshowtime.com/v1/unarchive

Unarchive a show.

Parameters

Name Type Description
show_id integer Required*. The TVDB ID of the show.

Response

{ 'result': 'OK' }

Save Show Progress

POST https://api.tvshowtime.com/v1/show_progress

Set the progress for a show.

Parameters

Name Type Description
show_id integer Required*. The TVDB ID of the show.
season integer The season number.
episode integer The episode number.

Response

{ 'result': 'OK' }

Tips

You can also pass an array of shows : shows=[{"show_id":121361,"season":2,"episode":1}]

Delete Show Progress

DELETE https://api.tvshowtime.com/v1/show_progress

OR

POST https://api.tvshowtime.com/v1/delete_show_progress

Delete the progress for a show. The parameters are similar to Save Show Progress

Parameters

Name Type Description
show_id integer Required*. The TVDB ID of the show.
season integer The season number.
episode integer The episode number.

Response

{ 'result': 'OK' }

Tips

You can also pass an array of shows : shows=[{"show_id":121361,"season":2,"episode":1}]

Episode

GET https://api.tvshowtime.com/v1/episode

Get episode data.

Parameters

Name Type Description
episode item mixed See Episode Item Parameter section

Response

{ 'result': 'OK', 'episode': Object }

Checkin

POST https://api.tvshowtime.com/v1/checkin

Mark an episode as watched.

Parameters

Name Type Description
episode item mixed See Episode Item Parameter section
publish_on_ticker boolean Publish on Facebook.
publish_on_twitter boolean Publish on Twitter.
auto_follow boolean Auto-follow the show if not already followed. Default: 1

Response

{ 'result': 'OK' }

Tips

filename can also be a list of comma separated values (limited to 10 values).

boolean type is in fact 0 or 1, not true / false.

Is Checked

GET https://api.tvshowtime.com/v1/checkin

Check if an episode was watched.

Parameters

Name Type Description
episode item mixed See Episode Item Parameter section

Response

{ 'result': 'OK', 'code': 0|1 } // O = not watched, 1 = watched

Checkout

DELETE https://api.tvshowtime.com/v1/checkin

OR

POST https://api.tvshowtime.com/v1/checkout

Unmark an episode as watched.

Parameters

Name Type Description
episode item mixed See Episode Item Parameter section

Response

{ 'result': 'OK' }

Tips

filename can also be a list of comma separated values (limited to 10 values).

Retrieve Progress

GET https://api.tvshowtime.com/v1/progress

Get the progress for an episode.

Parameters

Name Type Description
episode item mixed See Episode Item Parameter section

Response

{ 'result': 'OK', 'progress': 42 } // progress in seconds

Save Progress

POST https://api.tvshowtime.com/v1/progress

Set the progress for an episode.

Parameters

Name Type Description
episode item mixed See Episode Item Parameter section

Response

{ 'result': 'OK', 'progress': 42 } // progress in seconds

Set emotion

POST https://api.tvshowtime.com/v1/emotion

Set the emotion for an episode.

Parameters

Name Type Description
episode_id integer Required*. The TVDB ID of the episode.
emotion_id integer Required*. The emotion the user felt.

emotion_id: 1 Good - 2 Fun - 3 Wow - 4 Sad - 6 Soso - 7 Bad

Response

{ 'result': 'OK', 'emotion_id': 1 } // emotion set

Delete emotion

DELETE https://api.tvshowtime.com/v1/emotion

OR

POST https://api.tvshowtime.com/v1/delete_emotion

Delete the emotion for an episode.

Parameters

Name Type Description
episode_id integer Required*. The TVDB ID of the episode.

Response

{ 'result': 'OK' }