API Documentation

As this API is just entering public beta, it is highly advisable that you let me know if you build an application so I can contact you should any of the API details change - it's also great to see what people are building! Alternatively, you can tweet and follow me on Twitter for all of the latest updates.

Currently Available Methods

Parameters

Parameters are passed via the GET method in the URL which must be encoded. Every method in the API has two standard properties as defined below, and in most cases it's own specific parameters:

Required

  • method - The method that you wish to invoke.

Optional

  • format - Both JSON and XML are supported. If entered incorrectly or not at all, will default to JSON.
  • debug - If set to 'true', then it will suppress the header on any response. This allows you to see the result in your browser directly. Default value is 'false'.

Methods

get.cinemas

Returns a list of cinemas in the UK (eventually this will be expanded globally).

URL

http://showsapi.com/movies/?method=get.cinemas

Parameters

keyword - A keyword or part of the cinema name you are requesting.

location (optional) - Postal code or address.

Example

Request: http://showsapi.com/movies/?method=get.cinemas&keyword=Vue

get.movies

Returns a list of movies currently showing in the UK (eventually this will be expanded globally) or in the cinema supplied in the parameter.

URL

http://showsapi.com/movies/?method=get.movies

Parameters

keyword (optional) - A keyword or part of the title of the movie you are requesting.

genre (optional) - Genre of the movies you are trying to retrieve.

cinema (optional) - Cinema name exactly as returned in get.cinemas.

location (optional) - Postal code or address.

Example

Request: http://showsapi.com/movies/?method=get.movies&keyword=Knight&cinema=Vue+Cinemas+-+Aberdeen

Response

get.showtimes

Returns the show times of the movie at the specified cinema.

URL

http://showsapi.com/movies/?method=get.showtimes

Parameters

title - Movie name exactly as returned in get.movies.

cinema - Cinema name exactly as returned in get.cinemas.

day (optional) - Default to today. Should be in the format of Ymd (i.e. 20100815), can be a range, specified like 20100101-20100131. Maximum range is 31 days.

Example

Request: http://showsapi.com/movies/?method=get.showtimes&title=Knight+and+Day&cinema=Cineworld+-+Aberdeen+Union+Square&day=20100814

Response

search.movies

Returns a list of movies (and the cinema the movie is playing at) dependant on the parameters supplied.

URL

http://showsapi.com/movies/?method=search.movies

Parameters

keyword - Movie title or part of the title of the movie you are requesting.

cinema (optional) - Cinena name or part of the cinema you are requesting.

location (optional) - Postal code or address.

Example

Request: http://showsapi.com/movies/?method=search.movies&title=Knight&debug=true

Response

search.cinemas

Returns a list of movies (and the cinema the movie is playing at) dependant on the parameters supplied.

URL

http://showsapi.com/movies/?method=search.movies

Parameters

keyword Cinema name or part of it that you are requesting.

location (optional) - Postal code or address.

Example

Request: http://showsapi.com/movies/?method=search.cinema&keyword=Aberdeen&debug=true

Response

Error Handling

When an error is encountered, you will be sent an error response in the format that you made your initial request for (defaults to 'json'). The error output will consist of an error element with a single message:

Example

Request: http://showsapi.com/movies/?method=search

Response
{"response":{"error":"Missing parameter."}}

It is recommended that you always check for the presence of an error element before dealing with other elements. There will never be an error element if the request was successful.

Caching & Throttling

At present, this API is not in any way throttled meaning you can make multiple requests to the service. However, it should be noted that you are recommended to cache any responses from the API in order to save my bandwidth!

It is suggested that you make API calls no more frequently than once a minute - if you are building a large application, either let me know so I can cater for more bandwidth, or do an API request once a minute and cache the results on your server and make your application access the cache.

If I deem that your application is making too many requests, then I reserve the right to throttle your requests. If you set your user-agent to something identifiable (preferably with an email address or URL in it) then I will contact you before throttling.

Please contact me if you have any questions or suggestions, I don't bite!