Method name
- Quick start guide
- Troubleshooting
- Headers and Responses
- Sample code
- GET filmsNowShowing
- GET filmsComingSoon
- GET filmLiveSearch
- GET cinemaLiveSearch
- GET filmDetails
- GET cinemaDetails
- GET cinemasNearby
- GET cinemaShowTimes
- GET filmShowTimes
- GET closestShowing
- GET purchaseConfirmation
- GET images
- GET trailers
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.
Endpoint
https://api-gate2.movieglu.com/
Example request
https://api-gate2.movieglu.com/filmsNowShowing/?n=10
Request headers
| Sent header | Description | Data type | Optional / Mandatory |
|---|---|---|---|
| client | This is your client username (see the email which provided your evaluation licence key). | String | Mandatory |
| x-api-key | This is the key used to access the API | String | Mandatory |
| authorization | This is the key used to identify your access levels and permissions | String | Mandatory |
| territory | Two letter ISO country code, for example: – US – United States – UK – United Kingdom – CA – Canada – IE – Ireland – FR – France – ES – Spain – DE – Germany – IN – India | String | Mandatory |
| api-version | Identifies the version of the API that you are using. Please see the Quick start guide for the current version number. | String | Mandatory |
| geolocation | For 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 | Mandatory in some methods |
| device-datetime | Current 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. Standard: ISO 8601 (excluding timezone offset) In this example, the time showing on the user’s device, based on their location, is 19:30. Showtimes that start before 19:30 will not appear in API responses. Showtimes after 19:30 will appear in the API response. The location of the user is irrelevant. The API will always provide showtimes that start after the device’s current time. 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 | Mandatory |
| user_id | Where you are making use of our personalisation features (eg Favourite cinemas, film wishlist), we require a user ID | String | Optional |
| app_version | Where 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 versions | String | Optional |
| app_platform | Identifies 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. | String | Optional |
Response status codes
| Status code | Description |
|---|---|
| 200 | OK |
| 204 | No 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: |
| 400 | Bad 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. |
| 401 | Unauthorized – Please check your headers for correct territory, x-api-key and authorization values |
| 403 | Forbidden – Incorrect/missing x-api-key
Incorrect API method (eg cinemaShow instead of cinemaShowTimes) |
| 429 | Too many requests – Your quota for API requests has been exceeded. Please contact our support team. |
| 504 | Gateway 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
| Header | Description |
|---|---|
| Expires | You 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-message | MovieGlu 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 code | Description |
|---|---|
| count | Number of results returned |
| state | One of 3 states OK, Error, Warning |
| method | The method called |
| message | A descriptive error message, where applicable |
| request_method | The HTTP method used (GET, PUT, DELETE) |
| version | The version number of the requested API |
| territory | The two letter ISO territory code, for example US, FR or ES |
| device_datetime_sent | The date and time you sent in your request |
| device_datetime_used | The 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”.