Headers and Responses

Introduction

This page provides an overview of how to setup your API requests, and handle responses.  Please refer to our Quick Start Guide for details on which values to use, and how to get started.

Not sure how HTTP headers work?  This external page provides a great overview.

Alternatively try our code samples.

Example request

https://api-gate2.movieglu.com/filmsNowShowing/?n=10

Request headers

Sent headerDescriptionData typeOptional / Mandatory
clientThis is your client username (see the email which provided your evaluation licence key). StringMandatory
x-api-keyThis is the key used to access the APIStringMandatory
authorizationThis is the key used to identify your access levels and permissionsStringMandatory
territoryTwo letter ISO country code, for example:
– US – United States
– UK – United Kingdom
– CA – Canada
– IE – Ireland
– FR – France
– ES – Spain
– DE – Germany
– IN – India
StringMandatory
api-versionIdentifies the version of the API that you are using. Please see the Quick start guide for the current version number. StringMandatory
geolocationFor many API methods, the geolocation is mandatory, so that relevant responses may be provided. For example when you use the filmShowTimes method, the API will return a list of the nearest cinemas showing the film you requested, based on the user’s geolocation. Please note that the Latitude and Longitude must be separated by a semicolon.

Example: 52.123;0.456

Note that some values require a minus prefix.

Latitude;Longitude

Maximum 6 decimal places, for example 52.123456;0.123456.

Latitude must be between +90/-90 degrees. Longitude between +180/-180

Optional (but Mandatory in some methods)
device-datetimeCurrent date and time of the DEVICE which is requesting the API.
This is used to filter out showtimes which are in the past and ensure the relevant data is provided in territories that have more than one time zone.

Format: yyyy-mm-ddThh:mm:ss.sssZ
Example: 2018-09-14T08:30:17.360Z

Every component shown in the example above must be present when expressing a date in ISO 8601 format; this includes all punctuation characters and the “T” character. Within a string, the “T” indicates the beginning of the time element.

The .sss value is optional.

ISO 8601: Combined date and time

More information:
w3.org
Wikipedia

Mandatory
user_idWhere you are making use of our personalisation features (eg Favourite cinemas, film wishlist), we require a user IDStringOptional
app_versionWhere you anticipate multiple versions of your app to be available simultaneously, you may wish to add your app_version to the header, which allows us to assist you with debugging specific versionsStringOptional
app_platformIdentifies the platform from which requests are sent, for example iOS, Android, Browser. This will allow us to assist you with debugging specific versions of your app.StringOptional

Response status codes

Status codeDescription
200OK
204No content available. Please see the message in the response header – MG-message field for more information.

In some cases, you may receive a 204 status because:
– the geolocation used is outside of the country (territory) that you are licenced for
– your device-datetime header is not current.

400Bad request – Can be incorrect api-version or Authorization, but usually due to an incorrect method name, URL structure or invalid query paramater. Please see the message in the response header – MG-message field for more information.
401Unauthorized – Please check your headers for correct territory, x-api-key and authorization values
403Forbidden – Incorrect/missing x-api-key

Incorrect API method (eg cinemaShow instead of cinemaShowTimes)

429Too many requests – Your quota for API requests has been exceeded. Please contact our support team.
504Gateway Time-out. Usually caused by a server issue. If this error persists for more than a few minutes, please contact our support team.

 Response headers

HeaderDescription
ExpiresYou can cache responses on individual clients / devices if the Expires field in the Response header shows a date/time later than the current time. If the date/time is before the current time, then you should not cache the data.

Expires –> Wed, 08 Feb 2017 16:30:00 GMT

MG-messageMovieGlu generated error message, providing guidance on possible causes of errors, or lack of data.

Response status messages

These messages can be found at the end of the API response.  Please note – these should not be confused with response headers.

Status codeDescription
countNumber of results returned
stateOne of 3 states OK, Error, Warning
methodThe method called
messageA descriptive error message, where applicable
request_methodThe HTTP method used (GET, PUT, DELETE)
versionThe version number of the requested API
territoryThe two letter ISO territory code, for example US, FR or ES
device_datetime_sentThe date and time you sent in your request
device_datetime_usedThe date and time we used to provide your results

Other error messages

Incorrect case used

The API method names are case sensitive.  If you see this message, or similar, then check that you have used the same cases as in the documentation.
“message”: “Authorization header requires ‘Credential’ parameter. Authorization header requires ‘Signature’ parameter. Authorization header requires ‘SignedHeaders’ parameter.
For example, you will see this error message if you use GET “CinemaDetails”.  But it will work fine if you use “cinemaDetails”.