1. Description

This document is intended to serve software developers as an implementation guide for integration with Torrent API.

Torrent API provides data about Torrent-files. Unique identifier of Torrent-file is info hash (Infohash).

2. Connectivity

2.1. Connection type

Connection to Torrent API is available over the HTTPS protocol based on REST. Every request that your application sends to the Torrent API needs to contain API key as parameter key. Please request API key from your manager.

2.2. Torrent List for Movie Content

You can get full known torrents for one movie by HTTP GET request:

https://{host}/torrent/list/imdb/{imdbId}/?key={key}

where

  • host - hostname, will be provided.

  • imdbId - id of movie from IMDB, should be like ttXXXXXXX, where X is digit.

  • key - API Key.

Response format - Json, example:

{
    "imdb":"tt2250912",
    "title":"Spider-Man: Homecoming",
    "torrents":[
        {
            "infohash":"473bf68d4dd002a068e5c819de9dfaf2ec3d7dc0",
            "size":2970014871,
            "dateAdded":"2017-10-09T00:30:58.080+0000",
            "name":"Spider-Man.Homecoming.(2017).BDRip.x264.AFM.mkv",
            "alive":true
        },
        {
            "infohash":"3531f26c8a49b203b3d0672a55b09a07fdaa7840",
            "size":2450276855,
            "dateAdded":"2017-10-08T14:03:30.111+0000",
            "name":"Homem-Aranha - De Volta ao Lar 2017 [BluRay] (3D)",
            "alive":true
        }
     ]
}
Response JSON fields
Field Description

imdb

Imdb id of movie

title

Movie title

torrents

Array of torrent files distributing this movie

torrents.infohash

Info hash of torrent

torrents.size

Size in bytes of torrent’s files

torrents.name

Name of torrent

torrents.alive

Is this torrent alive or not. Torrent becomes dead (not alive) if there are too small peers distributing this torrent

2.3. Torrent Information

You can get torrent information by HTTP GET request:

https://{host}/torrent/info/{infohash}/?key={key}

where

  • host - hostname, will be provided.

  • infohash - info hash of torrent.

  • key - API Key.

Response format - Json, example 1:

{
    "infohash":"acb849c248930b9f45cd6bfc2de8d9d4be304b20",
    "torrentName":"Spider-Man Homecoming 2017 Movies HD Cam XviD Clean Audio AAC New Source with Sample ☻rDX☻",
    "size":738982523,
    "category":"Movies",
    "title":"Spider-Man: Homecoming",
    "imdbId":"tt2250912",
    "dateAdded":"2017-07-08T16:34:30.359+0000",
    "alive":true
}

Example 2:

{
    "infohash":"3b7afa9c9481b3af43f053f5d9627b334aaa8633",
    "torrentName":"Game of Thrones_ Season 4_Soundtrack",
    "size":148865997,
    "category":"Music",
    "title":"Game of Thrones_ Season 4_Soundtrack",
    "dateAdded":"2016-06-23T21:41:30.427+0000",
    "alive":true
}
Response JSON fields
Field Description

infohash

Info hash of torrent

torrentName

Name of torrent

size

Size in bytes of torrent’s files

category

Category of torrent

title

Title of content if known

imdbId

imdb id of movie contnent if known

dateAdded

Date when torrent was added to our database

alive

Is this torrent alive or not. Torrent becomes dead (not alive) if there are too small peers distributing this torrent

2.4. Torrent Peers History

You can get torrent peers history by HTTP GET request:

https://{host}/torrent/peers/{infohash}/?day={day}&countryCode={countryCode}&short={short}key={key}

where

  • host - hostname, will be provided.

  • infohash - info hash of torrent.

  • day - day, format "yyyy-MM-dd", optional. By default - last calculated day.

  • countryCode - ISO 3166-1 alpha-2 country code, optional. Response contains all countries if countryCode is not specified.

  • short - short report, true/false. Optional, by default - false.

  • key - API Key.

Response format - Json, example:

{
    "day":"2017-10-08",
    "infohash":"acb849c248930b9f45cd6bfc2de8d9d4be304b24",
    "totalPeers":350,
    "countries":[
        {"code":"BR","peers":200},
        {"code":"US","peers":100},
        {"code":"IN","peers":50}
    ]
}
Response JSON fields
Field Description

day

Date of report

totalPeers

Sum of totalPeers of all countries

countries

Statistics by country

countries.code

Country ISO code

countries.peers

Number of unique peers in country

2.5. Add Torrent

You can easily add torrent to our database by HTTP POST request:

https://{host}/torrent/add/

POST parameters

  • key - API Key.

  • infohash - Torrent info hash.

Response contains HTTP 200 OK and empty Json if added.

2.6. HTTP response codes

  • 200 - OK

  • 500 - Internal server error

2.7. Error response

In case of error response body contains error and message:

{
    error: "API_KEY_UNKNOWN",
    message: "API Key is unknown",
}
possible error values (new can be added later)

  • API_KEY_UNKNOWN - API key is unknown

  • API_KEY_SUSPENDED - API key is suspended

  • ACCESS_FORBIDDEN - API key doen’t provide access to method

  • INVALID_IMDB - value of imdb is invalid

  • INVALID_INFOHASH - value of infohash is invalid

  • INFOHASH_NOT_FOUND - torrent with infohash not found in our database

2.8. Content categories

  • Movies

  • Anime

  • TV

  • Music

  • Books

  • PC

  • Mobile

  • XXX

  • Child Porno

  • Unsorted