API: Cinemas

Location

http://www.cineworld.com/api/quickbook/cinemas

Overview

This query returns a list of cinemas that have programmed performances. The results can be filtered by supplying optional film, date and cinema parameters. These can all take multiple values, so for example it is possible to search for all cinemas showing film1 or film2 on a specific date.

http://www.cineworld.com/api/quickbook/cinemas?key=key&film=12345&film=54321&date=20100801

Parameters

Name Type Required? Default Description
key String Yes N/A Your developer API key.
territory String Optional GB Sets which territory to return cinemas for, valid values for United Kingdom and Ireland are; GB and IE.
callback String Optional N/A Wraps the response JSON in the callback function specified to allow cross browser scripting, note that if you use jQuery and JSONP the callback parameter is automatically added for you.
full Boolean Optional false Returns additional fields for each cinema, namely; address, postcode and telephone.
film Integer Optional N/A Film EDI to retrieve all cinemas showing this film, or for all films if excluded. More than one edi can be passed in, by assigning multiple values: film=1234&film=2345 - this will mean cinemas are retrieved that are showing at least ONE of the films.
date Integer Optional N/A Date (format yyyymmdd) - retrieves cinemas with performances on this date, or on any date if excluded; several dates can be passed in: date=20100810&date=20100811.
cinema Integer Optional N/A Cinema ID to retrieve - this can be passed in if information for a particular cinema is required.
category String Optional N/A Category code- this can be passed in to filter the results to only contain cinemas that have at least on performance for a film in this category.
event String Optional N/A Event code- this can be passed in to filter the results to only contain cinemas that have at least on performance for a film linked to this event.
distributor Integer Optional N/A Distributor id- this can be passed in to filter the results to only contain cinemas that have at least on performance for a film from this distributor.

Response

Use this to retrieve an array of Cineworld cinemas ordered by name and returned in JSON format. An example of what will be returned is below (use the full parameter to retrieve more data for each cinema):

{"cinemas":[{
    "id":78,
    "name":"Aberdeen-Union-Square",
    "cinema_url":"http://www.cineworld.co.uk/cinemas/78/information"
}]}

If any errors should occur they will be returned as an array:

{"errors":["valid key not supplied"]}
Name Type Description
id Integer Cinema ID
name String Cinema name
cinema_url String Absolute URL the cinema page
address String Full cinema address (all lines, excluding postcode)
postcode String Cinema postcode
telephone String Cinema telephone number

jQuery Demo

Source Code

$(document).ready(function() {
    $('a.retrieve').click(function() {
        $.ajax({
            url: 'http://www.cineworld.com/api/quickbook/cinemas',
            type: 'GET',
            data: {key: 'your developer key'},
            dataType: 'jsonp', // Setting this data type will add the callback parameter for you
            success: parseCinemas
        });
    });

    $('a.clear').click(function() {
        $('span.cinema.count').text('0');
        $('ol.cinema.list').empty();
    });
});

function parseCinemas(response, status) {
    var html = '';

    // Check for errors from the server
    if (response.errors) {
        $.each(response.errors, function() {
            html += '<li>' + this + '</li>';
        });
    } else {
        $('span.cinema.count').text(response.cinemas.length);
        $.each(response.cinemas, function() {
            html += '<li>' + this.name + '</li>';
        });
    }

    // Faster than doing a DOM call to append each node
    $('ol.cinema.list').append(html);
}

Live Example

Retrieve Cinemas Clear

Retrieved information about 0 cinemas.