API

Harness the power of CinemaTorrents.

API Introduction

The CinemaTorrents API is divided into two distinct components: SEARCH and QUERY.

In general, API requests are sent in the form of GET or POST requests with parameters (GET and POST are both supported). The results of the API requests are returned in the lightweight JSON format.

The CinemaTorrents API is open to all clients and there are currently no restrictions on its use. The API is completely free to use. When using the API, you need not attribute CinemaTorrents in your application in any way. In fact, by using QUERY requests, you could set up your very own movie torrents site in no time! That's cool with us!

Please be aware of the Imposed API Limitations before using the API.

API: SEARCH

SEARCH Introduction

SEARCH allows you to search for torrents already indexed on CinemaTorrents from your own applications. With SEARCH you can define specific search queries to find the right movie torrents for you.

How SEARCH works

To use SEARCH, just pass the SEARCH endpoint (http://cinematorrents.com/api/search) your search criteria in the form of parameters. GET and POST are both supported.

Some of the available search parameters are: title, genre, imdb_rank (combined with imdb_rank_op). For a complete list of the search parameters, see the reference.

What you get from SEARCH

SEARCH results are delivered in JSON. Check the success field to determine if the operation completed successfully. The result field will list the results when success == true. If success == false then check the reason field for an explanation.

The maximum number of results returned from a single SEARCH is set to 30. However, SEARCH now supports sorting of results and as such, a finer set of results can be obtained.

SEARCH Example

Here's a simple example of a SEARCH POST body where we are looking for good (7 or better on IMDB) thriller movies that were made since 2005. Remember the POST endpoint is http://cinematorrents.com/api/search.

The request: genre=thriller& imdb_rank=7& imdb_rank_op=GT& year=2005& year_op=GT

The result (trimmed to a single result--you would get more): { "success": true, "result": [ { "title": "Weekend at Jimmys 2006 XviD AC3 no rar", "url": "http://cinematorrents.com/movie/weekend-at-jimmys", "poster": "http://cinematorrents.com/files/imagecache/poster/f99acb76eadc323431da9d856a09c988.jpg", "year": "2006", "genres": "Horror, Thriller", "imdb_rank": "7.1", "imdb_votes": "7357", "rating": "R", "length": "108", "plot": "Jimmy has a great weekend, or does he?", "youtube_trailer_id": "AURbmFA65WI", "youtube_trailer": "http://www.youtube.com/watch?v=AURbmFA65WI", "download": "http://cinematorrents.com/download.torrent?nid=912874918" } ] }

SEARCH Reference

Parameter	Description	Required	Example
title	Title Keywords		title=Jimmy Fun
genre	A genre: action, thriller, comedy, etc		genre=sport
rating	A rating: G, PG_13, R, X, etc		rating=R
year	A year (requires year_op)		year=2004&year_op=EQ
year_op	GT (>=), LT (<=), EQ (==)	*	year=1990&year_op=GT
imdb_rank	IMDB rank (requires imdb_rank_op)		imdb_rank=5&imdb_rank_op=LT
imdb_rank_op	GT (>=), LT (<=), EQ (==)	*	imdb_rank=9&imdb_rank_op=GT
imdb_votes	IMDB votes (requires imdb_votes_op)		imdb_votes=1000&imdb_votes_op=GT
imdb_votes_op	GT (>=), LT (<=), EQ (==)	*	imdb_votes=500&imdb_votes_op=LT
length	Length in minutes (requires length_op)		length=120&length_op=LT
length_op	GT (>=), LT (<=), EQ (==)	*	length=60&length_op=GT
order	What to order by: title, genres, year, imdb_rank, imdb_votes, user_rank, length, added (default)		order=imdb_votes
sort	Order direction: asc, desc (default)		sort=asc

API: QUERY

QUERY Introduction

QUERY allows you to harness the power of the CinemaTorrents indexer engine for your own site. Got a list of torrents that you want to cross reference with movie information just like CinemaTorrents? Well, with QUERY you can.

How QUERY works

To use QUERY, just pass the QUERY endpoint (http://cinematorrents.com/api/query) a list of the torrent titles you would like to look up. GET and POST are both supported.

Requests must include a titles parameter. The titles parameter is a comma-separated list of the raw torrent titles you would like to look up. There is no need to clean up the torrent titles, QUERY will clean them up for you, that's what makes QUERY so useful.

What you get from QUERY

QUERY results are delivered in JSON. Check the success field to determine if the operation completed successfully. The result field will list the results of the query when success == true. If success == false then check the reason field for an explanation.

QUERY Example

Here's a simple GET example where we are looking up a single torrent title. Remember, you can look up a number of comma-delimited titles in one request.

The request: http://cinematorrents.com/api/query?titles=Jimmy Goes To Hollywood NTSC 2010 XviD Kingdom Release

The result: { "success": true, "result": [ { "title": "Jimmy Goes To Hollywood", "url": "http://cinematorrents.com/movie/jimmy-goes-to-hollywood", "poster": "http://cinematorrents.com/files/imagecache/poster/f99acb76eadc323431da9d856a09c987.jpg", "year": "2010", "genres": "Drama", "imdb_rank": "7.5", "imdb_votes": "4010", "rating": "G", "length": "96", "plot": "Jimmy wakes up and decides that he wants to go to Hollywood.", "youtube_trailer_id": "719HRpRA1", "youtube_trailer": "http://www.youtube.com/watch?v=719HRpRA1" } ] }

QUERY Reference

Parameter	Description	Required	Example
titles	Comma-delimited raw torrent titles	*	titles=Jimmy and the Whale {2001} LiMiT XVID no rar, ...

Imposed API Limitations

In order to prevent an unneccessary drain on resources by over-eager or abusive API users, there is a limit of one concurrent request per IP at any given time. Please ensure that you only send a single request at a time or your request will be denied.