# 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:

```bash
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

```
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](/upgrade-movie-id) for migration steps.

:::warning{title="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](/changelog/2026-07-01).

:::

---

### 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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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:

```json
{
  "_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:

```javascript
// 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:

```javascript
// 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:

```javascript
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:

```javascript
// 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:

```javascript
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:

```javascript
// 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