Calling the whatismymovie.com search API is easy.

After you have obtained your API key for the Beta Program, you can call our REST API using the familiar HTTP(S) GET method. The return values in the response messages are in the JSON format. On error, the HTTP error codes are used in the responses, so your code should check that the response has the 200 OK status before trying to parse the response as JSON data. If there was no error but the search didn't yield any results, an empty JSON array is returned.

Note: While also an endpoint with plain HTTP is available, you should use HTTPS in the API calls. Only with HTTPS-based secure connections you can ensure the confidentiality of the communication, including your API key that must be kept secret. 7th Mar 2016: We have fixed the SSL/TLS problem in the API. We are sorry for any inconvenience, if you tried to use HTTPS before the fix.

Query Limit: For the API keys in the Beta Program, a limit on the number of queries applies. Currently the limit is 100 queries per day. The limit is subject to change as our system matures. If your application needs more quota, please contact us and state your intended use for the extra queries and the estimated quota you need.

The API key (api_key) is a mandatory parameter.

The other mandatory parameter is the descriptive search string (text), which is any free-form, English-language, UTF-8 encoded string (maximum length 500 characters) that describes the movie(s) to be searched from our movie database.

Important! If you want to enable query refinements for your application, you need to use the parameter refinements=enabled in the API calls. What are query refinements? The feature that allows your user, who has made a query and examined the results of the query, to refine the results by expressing additional details in the next query. For example, the user might first search for "movies about birds", glance over the results list, and then focus the results by searching for "only horror"; our system will return a modified list containing horror movies about birds. The refinement query must be identified (as opposed to being a completely new query) by your application using the parameter query_id in the API call for the refinement query. The query ID is a UUID value provided in the response of the original query. See an example at the end of this guide. There can be several refinement queries for the same query; every new refinement will be intelligently combined with the original query and all previous refinements of that query.

If you did NOT enable query refinements, the returned value is just a ranked JSON array: the movies that matched best the search string are the first in the array. For each result movie, the returned data contains the IMDB-ID of the movie (integer, always provided; field name imdb_id), the original long IMDB-ID (string, always provided; field name imdb_id_long), the title of the movie (string, always provided; field name title), and the year of the movie (integer, provided if the year is known, otherwise null; field name year). Special Unicode characters in the return data are encoded using the familiar \uxxxx syntax of JSON, so for example the character "ö" would be encoded as \u00f6.

If you enabled query refinements, the returned value is a JSON object with two data members: 1) the query_id which you need to use if your user wants to make a refinement, and 2) the results array (field name: results) in the same format as described above.

In the following examples, the API key is "kkkkkkkkkkkkkkkk". Based on the examples, you are able to create your own search queries and parse the returned values. For brevity, some lines have been omitted from the example responses shown — often the number of returned movies is large, but this doesn't matter because the best matches are the first ones in the ranked list.

Example request: 

https://api.whatismymovie.com/1.0/?api_key=kkkkkkkkkkkkkkkk&text=a+boy+learns+he+is+a+wizard

Response:
[
  {"imdb_id":241527, "imdb_id_long":"tt0241527", "title":"Harry Potter and the Sorcerer's Stone", "year":2001},
  {"imdb_id":429589, "imdb_id_long":"tt0429589", "title":"The Ant Bully", "year":2006},
  {"imdb_id":970179, "imdb_id_long":"tt0970179", "title":"Hugo", "year":2011},
  ......
]

Example request: 

https://api.whatismymovie.com/1.0/?api_key=kkkkkkkkkkkkkkkk&text=drummer+of+the+band+explodes,+there+is+stonehenge+and+amplifier+going+to+eleven

Response:
[
  {"imdb_id":88258, "imdb_id_long":"tt0088258", "title":"This Is Spinal Tap", "year":1984},
  ......
]

Example request: 

https://api.whatismymovie.com/1.0/?api_key=kkkkkkkkkkkkkkkk&text=The+stuff+that+dreams+are+made+of

Response:
[
  {"imdb_id":33870, "imdb_id_long":"tt0033870", "title":"The Maltese Falcon", "year":1941}, 
  ......
]

Example request: 

https://api.whatismymovie.com/1.0/?api_key=kkkkkkkkkkkkkkkk&text=Champagne+computer+is+evil

Response:
[
  {"imdb_id":87197, "imdb_id_long":"tt0087197", "title":"Electric Dreams", "year":1984},
  ......
]

Example request with query refinements enabled: 

https://api.whatismymovie.com/1.0/?api_key=kkkkkkkkkkkkkkkk&refinements=enabled&text=movies+about+birds

Response:
{
  "query_id":"41ebcb29-1a10-4f9d-aa2c-fca1f934c67a",
  "results":
  [
    {"imdb_id":56869, "imdb_id_long":"tt0056869", "title":"The Birds", "year":1963},
    {"imdb_id":1636539, "imdb_id_long":"tt1636539", "title":"Love Birds", "year":2011},
    {"imdb_id":295552, "imdb_id_long":"tt0295552", "title":"Rare Birds", "year":2001},
    ......
  ]
}

Example request for a refinement of the previous query: 

https://api.whatismymovie.com/1.0/?api_key=kkkkkkkkkkkkkkkk&refinements=enabled&text=only+horror&query_id=41ebcb29-1a10-4f9d-aa2c-fca1f934c67a

Response:
[
  "query_id":"41ebcb29-1a10-4f9d-aa2c-fca1f934c67a",
  "results":
  [
    {"imdb_id":56869, "imdb_id_long":"tt0056869", "title":"The Birds", "year":1963},
    {"imdb_id":377749, "imdb_id_long":"tt0377749", "title":"Dead Birds", "year":2004},
    {"imdb_id":156706, "imdb_id_long":"tt0156706", "title":"Killing Birds: Raptors", "year":1987}
    ......
  ]
]