Overview

This describes the resources that make up the official TV 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 TV 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 TV 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@tvtime.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 TV TIME access

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

   Parameters

   Name	Type	Description
   client_id	string	Required. The client ID you received from TV 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. TV TIME redirects back to your site

   If the user accepts your request, TV 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 TV TIME when you registered.
   client_secret	string	Required. The client secret you received from TV 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, TV 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 TV 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 TV TIME's authorization server

   Your application can begin polling TV 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 TV TIME when you registered.
   client_secret	string	Required. The client secret you received from TV 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 TV TIME Account

   After entering the user_code, the user is asked to log in to the TV 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, TV 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, TV 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

• http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified

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.

• If season is set, mark the whole season seen.
• If season and episode are set, mark all episodes seen until season and episode number (included).
• If nothing is set, mark the whole show as seen.

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' }