SubDB

... is a free subtitle database.

This documentation describes how to use the SubDB API to download and upload subtitles from our database.

Back to home

How it works

The API uses an unique hash, calculated from the video file to match a subtitle. This way, we cannot only guarantee that the subtitle fits the intended video but improve the search speed while we keep the API as simple as it can be.

Basics

The entire API works using the HTTP protocol, using GET and POST requests to request and send information to the server. We use almost only the HTTP header to send messages between client and server, which reduces the use of bandwidth and improves the performance of the whole system.

Hash function

The hash function is the core of our database system. You'll need to know the hash of the video file, either to download or upload subtitles.
Our hash is composed by taking the first and the last 64kb of the video file, putting all together and generating a md5 of the resulting data (128kb).
The following function, written in python, implements our hash algorithm:

            
    #this hash function receives the name of the file and returns the hash code
    def get_hash(name):
        readsize = 64 * 1024
        with open(name, 'rb') as f:
            size = os.path.getsize(name)
            data = f.read(readsize)
            f.seek(-readsize, os.SEEK_END)
            data += f.read(readsize)
        return hashlib.md5(data).hexdigest()
            
        

Samples

To make sure that your hash function is returning the correct hash for a video, here we have two sample files you can use to compare:
Showtime Dexter Promo sample for SubDB: ffd8d4aa68033dc03d1c8ef373b9028c
FX Justified Trailer sample for SubDB: edc1981d6459c6111fe36205b4aff6c2

No copyright infringement intended. Those video files are taken from You Tube for educational purpose only.

User agent

Setting the correct user agent string is a requirement to access our database. It is composed using the name and the version of the protocol, followed by the name, version and URL of the client.
If the user agent is not correct, every request you make to us will result in a HTTP status code 412.
Here is an example of a valid user agent:

            
    SubDB/1.0 (Pyrrot/0.1; http://github.com/jrhames/pyrrot-cli)
    
    Where:
        'SubDB' is the protocol name;
        '1.0' is the protocol version;
        'Pyrrot' is the client name (change this field to your own client name);
        '0.1' is the client version (change this field to your own client version);
        'http://github.com/jrhames/pyrrot-cli' is the client url (change this field to your own client url).
            
        

Why the user agent is so important?

The user agent is important to prevent users from accessing the API directly from the web browser by mistake. We also use this information to create statistics about how many clients are using SubDB and how many requests each client does on our system.

Important: Please, don't mimic another client user agent string. Create one for yourself.

Limits

There are no requests limits on our database, but we ask that you have common sense and not make unnecessary requests. We're doing this service for everyone, but it wouldn't be helpful if our servers are overloaded all the time.

Methods

List of API's supported methods (actions):

            
    'action': (Required)
    The parameter action can be:
        "languages": to list all subtitle languages stored in our database;
        "search": to retrieve a list of available subtitle languages for a given hash;
        "download": to download subtitles;
        "upload": to upload subtitles.
            
        

Available languages

Important: Google has deprecated it's Translate API and now we only support a limited number of languages. More info here.

One frequently asked question we receive is why SubDB supports so few languages. The answer is: We do not support a few languages, we support a bunch of them. Our systems can handle any language that Google Language API supports.

We now have an API method that lists the languages of all subtitles stored on our database (not all languages that we support - see Google Language API for this).
To list the languages, a HTTP GET request will be made to the server.

            
Request:

    'http://api.thesubdb.com/?action=languages' (GET)

Response:
    
    'Success': (HTTP/1.1 200 OK)
        A comma separated list of the available languages will be returned with the status code 200.
        Example:
        '''
            en,es,fr,it,nl,pl,pt,ro,sv,tr
        '''
        
    'Malformed': (HTTP/1.1 400 Bad Request)
        If the request was malformed, the HTTP status code 400 will be returned.
            
        

Important: During development and for tests purposes, please use http://sandbox.thesubdb.com/ as the API url.

Searching subtitles

To list the available subtitle languages for a given hash, a HTTP GET request will be made to the server.

            
Request:

    'http://api.thesubdb.com/?action=search&hash=edc1981d6459c6111fe36205b4aff6c2[&versions]' (GET)
    
    'hash': (Required)
        The parameter hash is the hash of the video file, generated using our hash function.
    
    'versions': (Optional)
        This parameter is optional. Using it to return how many versions per language of a subtitle we have in our database.

Response:
    
    'Success': (HTTP/1.1 200 OK)
        If any subtitle for the requested hash exists, the language comma separated list will be returned with the status code 200.
        Example:
        '''
            en,pt
        '''
        
        When using versions modifier, the result will also contain the number of subtitle versions per language we have for the specified hash.
        Example WITH versions modifier:
        '''
            en:2,pt:3
        '''
    
    'NotFound': (HTTP/1.1 404 Not Found)
        If we cant find a subtitle for the requested hash on the server, the HTTP status code 404 will be returned.
        
    'Malformed': (HTTP/1.1 400 Bad Request)
        If the request was malformed, the HTTP status code 400 will be returned.
            
        

Important: During development and for tests purposes, please use http://sandbox.thesubdb.com/ as the API url.

Downloading subtitles

To download a subtitle, a HTTP GET request will be made to the server.

            
Request:

    'http://api.thesubdb.com/?action=download&hash=edc1981d6459c6111fe36205b4aff6c2&language=pt,en' (GET)
    
    'hash': (Required)
        The parameter hash is the hash of the video file, generated using our hash function.
    
    'language': (Required)
        The parameter language can be a single language code (ex.: us), or a comma separated list in order of priority (ex.: us,nl).
        When using a comma separated list, the first subtitle found is returned.

Response:
    
    'Success': (HTTP/1.1 200 OK)
        If the requested subtitle exists, the subtitle will be served to download with the status code 200.
        The language of the downloaded subtitle is returned in the Content-Language field in the header of the response.

    'NotFound': (HTTP/1.1 404 Not Found)
        If the subtitle doesnt exist on the server, the HTTP status code 404 will be returned.
        
    'Malformed': (HTTP/1.1 400 Bad Request)
        If the request was malformed, the HTTP status code 400 will be returned.
            
        

Important: During development and for tests purposes, please use http://sandbox.thesubdb.com/ as the API url.

Uploading subtitles

To upload a subtitle, a HTTP POST request will be made to the server.

            
Request:
            
    'http://api.thesubdb.com/?action=upload' (POST)
    
    'hash': (Required)
        The parameter hash is the hash of the video file, generated using our hash function.
    
    And the file data together with the file length.
    
Response:

        'Uploaded': (HTTP/1.1 201 Created)
            If everything was OK, the HTTP status code 201 will be returned.
            
        'Duplicated': (HTTP/1.1 403 Forbidden)
            If the subtitle file already exists in our database, the HTTP status code 403 will be returned.
            
        'Invalid': (HTTP/1.1 415 Unsupported Media Type)
            If the subtitle file is not supported by our database, the HTTP status code 415 will be returned.
            
        'Malformed': (HTTP/1.1 400 Bad Request)
            If the request was malformed, the HTTP status code 400 will be returned.
            
        

Request sample

Here's an example of how your upload request should look like:

            
POST /?action=upload HTTP/1.1
Host: api.thesubdb.com
User-Agent: SubDB/1.0 (Pyrrot/0.1; http://github.com/jrhames/pyrrot-cli)
Content-Length: 60047
Content-Type: multipart/form-data; boundary=xYzZY

- - --xYzZY
Content-Disposition: form-data; name="hash"

edc1981d6459c6111fe36205b4aff6c2
- - --xYzZY
Content-Disposition: form-data; name="file"; filename="subtitle.srt"
Content-Type: application/octet-stream


[PAYLOAD]
            
        

We want to thank David Santiago (demanuel at ymail.com) for sending this example to us.

Supported subtitle formats

Currently we support only the SubRip and SubViewer subtitle's formats.

Important: During development and for tests purposes, please use http://sandbox.thesubdb.com/ as the API url.

Sandbox API

The sandbox API is a copy of the original API, used for testing purposes during the client development. To use the sandbox API, change the url to http://sandbox.thesubdb.com.
We don't keep the subtitles uploaded to the sandbox API, but the behavior and the returned messages are the same.
We have two subtitles (english and portuguese) for the hash edc1981d6459c6111fe36205b4aff6c2 (justified.mp4) stored on the sandbox.


Since we don't store any info about the subtitles besides itself and a computed hash, we cannot control what users are uploading to us.
If you think that any copyright law was infringed by any subtitles we may have in our database, please, .

Check our blog/twitter and keep up to date with us.