Guides

Getting Showtimes for a Movie

Learn how to retrieve showtimes for a movie using the /showings endpoint with flexible filtering options including location, date ranges, technical features, and more.

Prerequisites

Before fetching showtimes, ensure:

you have Movie ID for the movie you want to search showings for. The Movie ID is a number, e.g. 699236.
there are showings in the database for this movie.

Environments:

Production: https://api.cineamo.com
Staging: https://api.staging.cineamo.com

Examples use production URLs. Replace with your target environment.

Required Headers

All API requests should include a User-Agent header to identify your application:

Header	Description	Example
`User-Agent`	Identifies your application	`YourAppName/1.0 (your-domain.com)`

User-Agent Format: Use the format AppName/Version (domain.com) where:

AppName - Your application or company name
Version - Your app version (optional)
domain.com - Your website domain or contact information

This helps us identify API usage patterns and contact you if there are issues with your integration.

Quick Start

Get started with a minimal example - fetch all showtimes for a specific movie:

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Important:

Always include a User-Agent header identifying your application (e.g., your app name and domain)

This returns all future showtimes for the movie across all cinemas.

Endpoint

Base Request

Code
GET /showings

Required Parameters

Parameter	Type	Description
`startDatetime`	string	Start of date range (ISO 8601 format)
`endDatetime`	string	End of date range (ISO 8601 format)

The range between startDatetime and endDatetime must be less then 1 week. These properties filter showings by their startDatetime, this means that if you pass endDatetime which represents time of 18:00, this will match showings that start until 17:59, not the ones that end by 17:59.

And at least one of the following parameters:

Parameter	Type	Description
`cinemaIds`	array	Array of cinema IDs
`movieId`	number	Specific movie ID (Movie.id)
`contentId`	number	Specific content/movie ID - not useful if searching by `movieId`
`countryCode`	string	Filter by country code (e.g., "DE", "AT") of the cinemas
`longitude` + `latitude` + `distance`	numbers	Location-based filtering (see details below)

Note: You must provide at least one of these filters. You can combine multiple filters for more specific results.

Deprecation: The legacy cineamoMovieId filter (a string ending in m, e.g. 967941m) is deprecated. Use the numeric movieId instead — it takes precedence when both are given. See the Movie ID upgrade guide for migration steps.

Legacy Alphanumeric Movie ID deprecation

Use the new movieId filter with a numeric Movie id (e.g. 699236), instead of the legacy alphanumeric cineamoMovieId filter (e.g. 967941m). For backwards compatibiliy, legacy filter is still accepted, but is considered deprecated, and will be phased out, removing support after a grace period. For more information, see the release notes.

Location-Based Filtering

Find showtimes within a geographic area:

Parameter	Type	Description
`longitude`	number	Longitude coordinate
`latitude`	number	Latitude coordinate
`distance`	number	Radius in meters (e.g., 50000 for 50km)

All three parameters are required when using location filtering.

Example: Find showtimes near Berlin

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&longitude=13.4050&latitude=52.5200&distance=50000&sort=distance&order=asc" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

When using location filters, you can sort results by distance using sort=distance.

Advanced Filters

Showing Technology Filters

Filter by technical features and premium cinema formats:

Parameter	Type	Description
`isThreeDimensional`	boolean	3D screenings
`isImax`	boolean	IMAX format
`isDolbyAtmos`	boolean	Dolby Atmos sound
`isDolbyVision`	boolean	Dolby Vision HDR
`isDolbyCinema`	boolean	Dolby Cinema
`is4DX`	boolean	4DX motion seats
`isScreenX`	boolean	ScreenX panoramic screens
`isHFR`	boolean	High Frame Rate
`isDbox`	boolean	D-BOX motion seats
`isLive`	boolean	Live event screenings

Example: Get only IMAX showtimes

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&isImax=true" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Language & Audio Filters

Filter by audio language, subtitles, and dubbing:

Parameter	Type	Description
`language`	string	Audio language code (ISO 639-3, e.g., "deu", "gsw")
`isOriginalLanguage`	boolean	Original language screenings
`isSubtitled`	boolean	Has subtitles
`subtitledLanguage`	string	Subtitle language code

Example: Get original language screenings with subtitles

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&isOriginalLanguage=true&isSubtitled=true" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Example: Get German subtitled screenings

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&isSubtitled=true&subtitledLanguage=deu" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Other Filters

Parameter	Type	Description
`cinemaRoomIds`	array	Filter by specific cinema rooms
`showingTagIds`	array	Filter by showing tags
`hasShowingTags`	boolean	Has any showing tags
`hasMovie`	boolean	Has associated movie
`isHighlightAfterDatetime`	string	Highlight after specific datetime

Sorting & Pagination

Sorting Parameters

Parameter	Type	Default	Description
`sort`	string	"startDatetime"	Sort field (e.g., "startDatetime", "distance")
`order`	string	"asc"	Sort order: "asc" or "desc"

Available sort fields:

startDatetime - Sort by showing start time (default)
distance - Sort by distance (only when using location filters)

Pagination Parameters

Parameter	Type	Default	Description
`page`	number	1	Current page number

Example: Paginated results sorted by distance

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&longitude=13.4050&latitude=52.5200&distance=50000&sort=distance&order=asc&page=2" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Embedded Resources

Use the embed[] parameter to include related data in the response. Only request embeds you need for better performance.

Embed Value	Description	Use When
`cinema`	Cinema details (name, location, logo, etc.)	Building showtimes finder or cinema listings
`content`	Movie/content information (title, poster, duration)	Need movie metadata with each showing

Example: Get showtimes with all embeds

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&embed[]=cinema&embed[]=content" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Response Structure

HAL Response Format

The API returns responses in HAL (Hypertext Application Language) format:


Code
{
  "_total_items": 156,
  "_page": 1,
  "_page_count": 8,
  "_links": {
    "self": {
      "href": "/showings?movieId=123&page=1"
    },
    "next": {
      "href": "/showings?movieId=123&page=2"
    },
    "last": {
      "href": "/showings?movieId=123&page=8"
    }
  },
  "_embedded": {
    "showings": [
      {
        "id": 39944966,
        "contentId": 362257,
        "eventRequestId": null,
        "cinemaRoomId": 1794,
        "name": "The Hate U Give",
        "startDatetime": "2025-12-09T09:30:00Z",
        "endDatetime": null,
        "state": "scheduled",
        "isThreeDimensional": null,
        "isRegularShowtime": true,
        "isDolbyAtmos": null,
        "language": "eng",
        "originalLanguage": "eng",
        "isOriginalLanguage": true,
        "isDubbed": null,
        "dubbedLanguage": null,
        "isSubtitled": true,
        "subtitledLanguage": "deu",
        "movieId": 470044,
        "onlineTicketUrl": "https://www.kinoheld.de/kino/hamburg/abaton-kino-hamburg?rb=0&mode=widget&appView=1&ref=cinepass&showId=551889",
        "cinemaId": 563,
        "eventRequest": null,
        "imageUrl": null,
        "priceOption": null,
        "highlightAfterDatetime": null,
        "highlightText": null,
        "endSaleDatetime": null,
        "isImax": null,
        "isDolbyVision": null,
        "isDolbyCinema": null,
        "is4DX": null,
        "isScreenX": null,
        "isLive": null,
        "isHFR": null,
        "isDbox": null,
        "ticketUrls": {
          "default": "https://www.kinoheld.de/kino/hamburg/abaton-kino-hamburg?rb=0&mode=widget&appView=1&ref=cinepass&showId=551889",
          "web": null,
          "ios": null,
          "android": null,
          "cinemaWebsite": null
        },
        "bookingUrlExternal": "https://www.kinoheld.de/kino/hamburg/abaton-kino-hamburg?rb=0&mode=widget&appView=1&ref=cinepass&showId=551889",
        "_links": {
          "self": {
            "href": "https://api.cineamo.com/showings/39944966"
          }
        },
        "_embedded": {
          "content": {
            "id": 362257,
            "name": "The Hate U Give",
            "slug": "the-hate-u-give",
            "category": "movie_series",
            "description": "Raised in a poverty-stricken slum, a 16-year-old girl named Starr now attends a suburban prep school. After she witnesses a police officer shoot her unarmed best friend, she's torn between her two very different worlds as she tries to speak her truth.",
            "isOwnContent": false,
            "duration": 132,
            "creatorCinemaId": null,
            "posterImageRef": null,
            "posterImageUrl": null,
            "backdropImageRef": null,
            "backdropImageUrl": null,
            "ageRating": null,
            "trailerUrl": null,
            "isRegularEvent": false,
            "hasMarketingAssistantBooked": false,
            "cineamoMovie": null,
            "metrics": null,
            "_links": {
              "self": {
                "href": "https://api.cineamo.com/contents/362257"
              }
            }
           },
          "cinema": {
            "id": 563,
            "name": "Abaton",
            "shortName": "Abaton Hamburg",
            "slug": "abaton",
            "description": "",
            "phone": "+494041320320",
            "street": "Allendeplatz 3",
            "postalCode": "20146",
            "city": "Hamburg",
            "state": "",
            "stateAbbr": "HH",
            "country": "Deutschland",
            "countryCode": "DE",
            "currencyCode": "EUR",
            "longitude": 9.98219967,
            "latitude": 53.56790161,
            "distance": null,
            "profileImageRef": "1e7a336c-e3b2-4422-8300-4757fffb2461",
            "profileImageUrl": "https://cdn.cineamo.com/cinema-profile-image/1e7a336c-e3b2-4422-8300-4757fffb2461",
            "logoImageRef": "28dbfeb6-20a6-40ae-90fd-767e7a58231a",
            "logoImageUrl": "https://cdn.cineamo.com/cinema-logo-image/28dbfeb6-20a6-40ae-90fd-767e7a58231a",
            "logoWideImageRef": "bd46b386-4fed-4552-8537-232fb5e6a127",
            "logoWideImageUrl": "https://cdn.cineamo.com/cinema-logo-wide-image/bd46b386-4fed-4552-8537-232fb5e6a127",
            "priceTablePdfRef": null,
            "priceTablePdfUrl": null,
            "primaryColor": "#FFFFFF",
            "instagramLink": "https://www.instagram.com/abatonkino/",
            "facebookLink": "https://www.facebook.com/abatonkino",
            "ticketSystemId": "627",
            "ticketSystem": "international_showtimes",
            "email": "office@abatonkino.de",
            "isActive": true,
            "cinemaConfigurationId": 594,
            "showtimesUpdated": "2025-12-09T12:09:39Z",
            "isFavorite": null,
            "hasMarketingAssistantBooked": true,
            "cineamoTrailerConfirmedDatetime": "2025-06-11T11:49:05Z",
            "cinemaChainId": null,
            "cityId": 4086559,
            "openingHoursCustomText": null,
            "_links": {
              "self": {
                "href": "https://api.cineamo.com/cinemas/563"
              }
            }
          }
        }
      }
    ]
  }
}

HAL Structure Explained

_total_items - Total number of showings across all pages
_page - Current page number
_page_count - Total number of pages
_links - Hypermedia navigation (self, next, prev, last, first)
_embedded.showings - Array of showing objects

Best Practices

1. Always Use Embed Parameters Wisely

Only request the data you need:


Code
// Good: Only embed what you'll use
'embed[]=cinema'

// Avoid: Embedding everything unnecessarily
'embed[]=cinema&embed[]=content&embed[]=cinemaRoom'

2. Filter Early, Paginate Efficiently

Narrow down results with filters before paginating:


Code
// Good: Specific filters reduce total results
const params = {
  movieId,
  countryCode: 'DE',
  isImax: 'true',
  startDatetime: today,
  endDatetime: tomorrow
};

3. Handle Time Zones Correctly

API returns UTC times - convert to local cinema time zones:


Code
const showing = showings[0];
const localTime = new Date(showing.startDatetime).toLocaleString('de-DE', {
  timeZone: 'Europe/Berlin',
  dateStyle: 'medium',
  timeStyle: 'short'
});
console.log(`Showing at: ${localTime}`); // "9. Dez. 2025, 20:30"

4. Use Logical Days for Date Filtering

Cineamo uses logical days starting at 4:00 AM UTC:


Code
// Get showtimes for "today" (4 AM today to 4 AM tomorrow)
const startDatetime = new Date();
startDatetime.setUTCHours(4, 0, 0, 0);

const endDatetime = new Date(startDatetime);
endDatetime.setUTCDate(endDatetime.getUTCDate() + 1);

5. Implement Proper Error Handling

Handle rate limits, timeouts, and missing data:


Code
try {
  const response = await fetch(url, options);

  if (response.status === 429) {
    // Rate limit hit - implement exponential backoff
    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data = await response.json();

  // Check for empty results
  if (!data._embedded?.showings?.length) {
    console.log('No showings found for this filter combination');
    return [];
  }

  return data._embedded.showings;

} catch (error) {
  console.error('Error fetching showings:', error);
  throw error;
}

6. Performance Optimization

For location-based searches with many results:


Code
// Implement infinite scroll or "Load More" for subsequent pages
async function loadMoreShowings(nextPage) {
  params.set('page', nextPage);
  return fetch(`${baseUrl}/showings?${params}`, { headers });
}

Troubleshooting

Empty Results

Problem: _embedded.showings is empty or missing

Solutions:

Verify at least one required filter is provided (cinemaIds, contentId, movieId, countryCode, or location)
Check date filters - ensure startDatetime is not in the past
Try removing filters one by one to identify the issue
Verify the movie has scheduled showtimes

400 Bad Request

Problem: Invalid request parameters

Solutions:

Ensure at least one required filter is provided
Verify date format is ISO 8601 (e.g., 2025-12-09T04:00:00Z)
Check that location filters include all three parameters (longitude, latitude, distance)
Validate filter values (booleans should be true or false, not 1 or 0)

429 Too Many Requests

Problem: Rate limit exceeded

Solutions:

Implement exponential backoff delays
Reduce request frequency
Check X-RateLimit-* response headers
Consider caching results

Response Missing Embedded Data

Problem: _embedded.cinema or other embeds are null

Solutions:

Verify embed[] parameters in request
Use correct embed parameter format: embed[]=cinema (not embed=cinema)
Some showings may lack associated data

Last modified on July 9, 2026

Showtimes Finder Widget

Guides

Getting Showtimes for a Movie

Learn how to retrieve showtimes for a movie using the /showings endpoint with flexible filtering options including location, date ranges, technical features, and more.

Prerequisites

Before fetching showtimes, ensure:

you have Movie ID for the movie you want to search showings for. The Movie ID is a number, e.g. 699236.
there are showings in the database for this movie.

Environments:

Production: https://api.cineamo.com
Staging: https://api.staging.cineamo.com

Examples use production URLs. Replace with your target environment.

Required Headers

All API requests should include a User-Agent header to identify your application:

Header	Description	Example
`User-Agent`	Identifies your application	`YourAppName/1.0 (your-domain.com)`

User-Agent Format: Use the format AppName/Version (domain.com) where:

AppName - Your application or company name
Version - Your app version (optional)
domain.com - Your website domain or contact information

This helps us identify API usage patterns and contact you if there are issues with your integration.

Quick Start

Get started with a minimal example - fetch all showtimes for a specific movie:

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Important:

Always include a User-Agent header identifying your application (e.g., your app name and domain)

This returns all future showtimes for the movie across all cinemas.

Endpoint

Base Request

Code
GET /showings

Required Parameters

Parameter	Type	Description
`startDatetime`	string	Start of date range (ISO 8601 format)
`endDatetime`	string	End of date range (ISO 8601 format)

And at least one of the following parameters:

Parameter	Type	Description
`cinemaIds`	array	Array of cinema IDs
`movieId`	number	Specific movie ID (Movie.id)
`contentId`	number	Specific content/movie ID - not useful if searching by `movieId`
`countryCode`	string	Filter by country code (e.g., "DE", "AT") of the cinemas
`longitude` + `latitude` + `distance`	numbers	Location-based filtering (see details below)

Note: You must provide at least one of these filters. You can combine multiple filters for more specific results.

Legacy Alphanumeric Movie ID deprecation

Location-Based Filtering

Find showtimes within a geographic area:

Parameter	Type	Description
`longitude`	number	Longitude coordinate
`latitude`	number	Latitude coordinate
`distance`	number	Radius in meters (e.g., 50000 for 50km)

All three parameters are required when using location filtering.

Example: Find showtimes near Berlin

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&longitude=13.4050&latitude=52.5200&distance=50000&sort=distance&order=asc" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

When using location filters, you can sort results by distance using sort=distance.

Advanced Filters

Showing Technology Filters

Filter by technical features and premium cinema formats:

Parameter	Type	Description
`isThreeDimensional`	boolean	3D screenings
`isImax`	boolean	IMAX format
`isDolbyAtmos`	boolean	Dolby Atmos sound
`isDolbyVision`	boolean	Dolby Vision HDR
`isDolbyCinema`	boolean	Dolby Cinema
`is4DX`	boolean	4DX motion seats
`isScreenX`	boolean	ScreenX panoramic screens
`isHFR`	boolean	High Frame Rate
`isDbox`	boolean	D-BOX motion seats
`isLive`	boolean	Live event screenings

Example: Get only IMAX showtimes

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&isImax=true" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Language & Audio Filters

Filter by audio language, subtitles, and dubbing:

Parameter	Type	Description
`language`	string	Audio language code (ISO 639-3, e.g., "deu", "gsw")
`isOriginalLanguage`	boolean	Original language screenings
`isSubtitled`	boolean	Has subtitles
`subtitledLanguage`	string	Subtitle language code

Example: Get original language screenings with subtitles

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&isOriginalLanguage=true&isSubtitled=true" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Example: Get German subtitled screenings

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&isSubtitled=true&subtitledLanguage=deu" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Other Filters

Parameter	Type	Description
`cinemaRoomIds`	array	Filter by specific cinema rooms
`showingTagIds`	array	Filter by showing tags
`hasShowingTags`	boolean	Has any showing tags
`hasMovie`	boolean	Has associated movie
`isHighlightAfterDatetime`	string	Highlight after specific datetime

Sorting & Pagination

Sorting Parameters

Parameter	Type	Default	Description
`sort`	string	"startDatetime"	Sort field (e.g., "startDatetime", "distance")
`order`	string	"asc"	Sort order: "asc" or "desc"

Available sort fields:

startDatetime - Sort by showing start time (default)
distance - Sort by distance (only when using location filters)

Pagination Parameters

Parameter	Type	Default	Description
`page`	number	1	Current page number

Example: Paginated results sorted by distance

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&longitude=13.4050&latitude=52.5200&distance=50000&sort=distance&order=asc&page=2" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Embedded Resources

Use the embed[] parameter to include related data in the response. Only request embeds you need for better performance.

Embed Value	Description	Use When
`cinema`	Cinema details (name, location, logo, etc.)	Building showtimes finder or cinema listings
`content`	Movie/content information (title, poster, duration)	Need movie metadata with each showing

Example: Get showtimes with all embeds

Code
curl -X GET "https://api.cineamo.com/showings?movieId=699236&countryCode=DE&startDatetime=2025-12-09T04:00:00Z&endDatetime=2025-12-10T03:59:59Z&embed[]=cinema&embed[]=content" \
  -H "User-Agent: YourAppName/1.0 (your-domain.com)"

Response Structure

HAL Response Format

The API returns responses in HAL (Hypertext Application Language) format:


Code
{
  "_total_items": 156,
  "_page": 1,
  "_page_count": 8,
  "_links": {
    "self": {
      "href": "/showings?movieId=123&page=1"
    },
    "next": {
      "href": "/showings?movieId=123&page=2"
    },
    "last": {
      "href": "/showings?movieId=123&page=8"
    }
  },
  "_embedded": {
    "showings": [
      {
        "id": 39944966,
        "contentId": 362257,
        "eventRequestId": null,
        "cinemaRoomId": 1794,
        "name": "The Hate U Give",
        "startDatetime": "2025-12-09T09:30:00Z",
        "endDatetime": null,
        "state": "scheduled",
        "isThreeDimensional": null,
        "isRegularShowtime": true,
        "isDolbyAtmos": null,
        "language": "eng",
        "originalLanguage": "eng",
        "isOriginalLanguage": true,
        "isDubbed": null,
        "dubbedLanguage": null,
        "isSubtitled": true,
        "subtitledLanguage": "deu",
        "movieId": 470044,
        "onlineTicketUrl": "https://www.kinoheld.de/kino/hamburg/abaton-kino-hamburg?rb=0&mode=widget&appView=1&ref=cinepass&showId=551889",
        "cinemaId": 563,
        "eventRequest": null,
        "imageUrl": null,
        "priceOption": null,
        "highlightAfterDatetime": null,
        "highlightText": null,
        "endSaleDatetime": null,
        "isImax": null,
        "isDolbyVision": null,
        "isDolbyCinema": null,
        "is4DX": null,
        "isScreenX": null,
        "isLive": null,
        "isHFR": null,
        "isDbox": null,
        "ticketUrls": {
          "default": "https://www.kinoheld.de/kino/hamburg/abaton-kino-hamburg?rb=0&mode=widget&appView=1&ref=cinepass&showId=551889",
          "web": null,
          "ios": null,
          "android": null,
          "cinemaWebsite": null
        },
        "bookingUrlExternal": "https://www.kinoheld.de/kino/hamburg/abaton-kino-hamburg?rb=0&mode=widget&appView=1&ref=cinepass&showId=551889",
        "_links": {
          "self": {
            "href": "https://api.cineamo.com/showings/39944966"
          }
        },
        "_embedded": {
          "content": {
            "id": 362257,
            "name": "The Hate U Give",
            "slug": "the-hate-u-give",
            "category": "movie_series",
            "description": "Raised in a poverty-stricken slum, a 16-year-old girl named Starr now attends a suburban prep school. After she witnesses a police officer shoot her unarmed best friend, she's torn between her two very different worlds as she tries to speak her truth.",
            "isOwnContent": false,
            "duration": 132,
            "creatorCinemaId": null,
            "posterImageRef": null,
            "posterImageUrl": null,
            "backdropImageRef": null,
            "backdropImageUrl": null,
            "ageRating": null,
            "trailerUrl": null,
            "isRegularEvent": false,
            "hasMarketingAssistantBooked": false,
            "cineamoMovie": null,
            "metrics": null,
            "_links": {
              "self": {
                "href": "https://api.cineamo.com/contents/362257"
              }
            }
           },
          "cinema": {
            "id": 563,
            "name": "Abaton",
            "shortName": "Abaton Hamburg",
            "slug": "abaton",
            "description": "",
            "phone": "+494041320320",
            "street": "Allendeplatz 3",
            "postalCode": "20146",
            "city": "Hamburg",
            "state": "",
            "stateAbbr": "HH",
            "country": "Deutschland",
            "countryCode": "DE",
            "currencyCode": "EUR",
            "longitude": 9.98219967,
            "latitude": 53.56790161,
            "distance": null,
            "profileImageRef": "1e7a336c-e3b2-4422-8300-4757fffb2461",
            "profileImageUrl": "https://cdn.cineamo.com/cinema-profile-image/1e7a336c-e3b2-4422-8300-4757fffb2461",
            "logoImageRef": "28dbfeb6-20a6-40ae-90fd-767e7a58231a",
            "logoImageUrl": "https://cdn.cineamo.com/cinema-logo-image/28dbfeb6-20a6-40ae-90fd-767e7a58231a",
            "logoWideImageRef": "bd46b386-4fed-4552-8537-232fb5e6a127",
            "logoWideImageUrl": "https://cdn.cineamo.com/cinema-logo-wide-image/bd46b386-4fed-4552-8537-232fb5e6a127",
            "priceTablePdfRef": null,
            "priceTablePdfUrl": null,
            "primaryColor": "#FFFFFF",
            "instagramLink": "https://www.instagram.com/abatonkino/",
            "facebookLink": "https://www.facebook.com/abatonkino",
            "ticketSystemId": "627",
            "ticketSystem": "international_showtimes",
            "email": "office@abatonkino.de",
            "isActive": true,
            "cinemaConfigurationId": 594,
            "showtimesUpdated": "2025-12-09T12:09:39Z",
            "isFavorite": null,
            "hasMarketingAssistantBooked": true,
            "cineamoTrailerConfirmedDatetime": "2025-06-11T11:49:05Z",
            "cinemaChainId": null,
            "cityId": 4086559,
            "openingHoursCustomText": null,
            "_links": {
              "self": {
                "href": "https://api.cineamo.com/cinemas/563"
              }
            }
          }
        }
      }
    ]
  }
}

HAL Structure Explained

_total_items - Total number of showings across all pages
_page - Current page number
_page_count - Total number of pages
_links - Hypermedia navigation (self, next, prev, last, first)
_embedded.showings - Array of showing objects

Best Practices

1. Always Use Embed Parameters Wisely

Only request the data you need:


Code
// Good: Only embed what you'll use
'embed[]=cinema'

// Avoid: Embedding everything unnecessarily
'embed[]=cinema&embed[]=content&embed[]=cinemaRoom'

2. Filter Early, Paginate Efficiently

Narrow down results with filters before paginating:


Code
// Good: Specific filters reduce total results
const params = {
  movieId,
  countryCode: 'DE',
  isImax: 'true',
  startDatetime: today,
  endDatetime: tomorrow
};

3. Handle Time Zones Correctly

API returns UTC times - convert to local cinema time zones:


Code
const showing = showings[0];
const localTime = new Date(showing.startDatetime).toLocaleString('de-DE', {
  timeZone: 'Europe/Berlin',
  dateStyle: 'medium',
  timeStyle: 'short'
});
console.log(`Showing at: ${localTime}`); // "9. Dez. 2025, 20:30"

4. Use Logical Days for Date Filtering

Cineamo uses logical days starting at 4:00 AM UTC:


Code
// Get showtimes for "today" (4 AM today to 4 AM tomorrow)
const startDatetime = new Date();
startDatetime.setUTCHours(4, 0, 0, 0);

const endDatetime = new Date(startDatetime);
endDatetime.setUTCDate(endDatetime.getUTCDate() + 1);

5. Implement Proper Error Handling

Handle rate limits, timeouts, and missing data:


Code
try {
  const response = await fetch(url, options);

  if (response.status === 429) {
    // Rate limit hit - implement exponential backoff
    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data = await response.json();

  // Check for empty results
  if (!data._embedded?.showings?.length) {
    console.log('No showings found for this filter combination');
    return [];
  }

  return data._embedded.showings;

} catch (error) {
  console.error('Error fetching showings:', error);
  throw error;
}

6. Performance Optimization

For location-based searches with many results:


Code
// Implement infinite scroll or "Load More" for subsequent pages
async function loadMoreShowings(nextPage) {
  params.set('page', nextPage);
  return fetch(`${baseUrl}/showings?${params}`, { headers });
}

Troubleshooting

Empty Results

Problem: _embedded.showings is empty or missing

Solutions:

Verify at least one required filter is provided (cinemaIds, contentId, movieId, countryCode, or location)
Check date filters - ensure startDatetime is not in the past
Try removing filters one by one to identify the issue
Verify the movie has scheduled showtimes

400 Bad Request

Problem: Invalid request parameters

Solutions:

Ensure at least one required filter is provided
Verify date format is ISO 8601 (e.g., 2025-12-09T04:00:00Z)
Check that location filters include all three parameters (longitude, latitude, distance)
Validate filter values (booleans should be true or false, not 1 or 0)

429 Too Many Requests

Problem: Rate limit exceeded

Solutions:

Implement exponential backoff delays
Reduce request frequency
Check X-RateLimit-* response headers
Consider caching results

Response Missing Embedded Data

Problem: _embedded.cinema or other embeds are null

Solutions:

Verify embed[] parameters in request
Use correct embed parameter format: embed[]=cinema (not embed=cinema)
Some showings may lack associated data

Last modified on July 9, 2026

Showtimes Finder Widget