# Прожекции в кината

> GET /3/movie/{movie_id}/showtimes?country=RU връща кината, които прожектират филм в една държава, с прожекции по дати във всяко. Без country връща само бройки по държави в списък countries. Покритието зависи от държавата и заглавието, а празен масив results означава, че за тази двойка нищо не е известно.

## Ендпойнт

`GET /3/movie/{movie_id}/showtimes`

```bash
curl "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -H "Authorization: Bearer $AMODB_KEY"
```

Отговор:

```json
{
  "id": 550,
  "country": "RU",
  "results": [
    {
      "id": 1114,
      "name": "Мираж Синема НА БОЛЬШОМ",
      "chain": {
        "key": "mirage-ru",
        "name": "Мираж Синема"
      },
      "city": "Санкт-Петербург",
      "region": null,
      "address": "Большой пр. П.С., д. 35А",
      "postal_code": null,
      "country": "RU",
      "timezone": "Europe/Moscow",
      "latitude": null,
      "longitude": null,
      "phone": null,
      "url": "https://www.mirage.ru/spb/cinema/1/",
      "showtimes": [
        {
          "date": "2026-10-19",
          "start": "2026-10-19T22:20",
          "end": null,
          "auditorium": "Зал №4",
          "formats": [
            "2D"
          ],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/0c32e190-890a-4c81-a754-3300fefc4d5e/",
          "sold_out": false
        },
        {
          "date": "2026-10-20",
          "start": "2026-10-20T21:40",
          "end": null,
          "auditorium": null,
          "formats": [
            "2D"
          ],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/7f18e423-4a40-40f3-b68f-8664f4e3fa75/",
          "sold_out": false
        },
        {
          "date": "2026-10-21",
          "start": "2026-10-21T21:40",
          "end": null,
          "auditorium": null,
          "formats": [
            "2D"
          ],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/5ad6b82b-82b3-4ea6-9e65-79388d71b230/",
          "sold_out": false
        }
      ]
    },
    {
      "id": 1115,
      "name": "Мираж Синема ПИК",
      "chain": {
        "key": "mirage-ru",
        "name": "Мираж Синема"
      },
      "city": "Санкт-Петербург",
      "region": null,
      "address": "ул. Ефимова, д.2",
      "postal_code": null,
      "country": "RU",
      "timezone": "Europe/Moscow",
      "latitude": null,
      "longitude": null,
      "phone": null,
      "url": "https://www.mirage.ru/spb/cinema/27/",
      "showtimes": [
        {
          "date": "2026-10-19",
          "start": "2026-10-19T20:10",
          "end": null,
          "auditorium": "Зал №4",
          "formats": [
            "2D"
          ],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/1d143ca6-1bbe-48ee-954a-063b6088a32a/",
          "sold_out": false
        },
        {
          "date": "2026-10-20",
          "start": "2026-10-20T20:10",
          "end": null,
          "auditorium": "Зал №4",
          "formats": [
            "2D"
          ],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/8b2e0f6a-5b62-41eb-a398-1b709539f03d/",
          "sold_out": false
        },
        {
          "date": "2026-10-21",
          "start": "2026-10-21T20:10",
          "end": null,
          "auditorium": "Зал №4",
          "formats": [
            "2D"
          ],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/3723875b-a7df-426f-968a-4bdaa1a8bdd7/",
          "sold_out": false
        }
      ]
    }
  ],
  "countries": [
    {
      "country": "RU",
      "name": "Russia",
      "venues": 2,
      "cities": 1,
      "showtimes": 6,
      "first_day": "2026-10-19",
      "last_day": "2026-10-21"
    }
  ]
}
```

## Вземане на прожекциите на филм

`GET /3/movie/{movie_id}/showtimes?country=RU` връща кината, които прожектират филм в една държава, с прожекциите по дати във всяко. Параметърът `country` приема двубуквен код с главни или малки букви. Покритието зависи от държавата и заглавието, така че данните присъстват там, където са известни, и липсват там, където не са. Връщат се само дни от днес нататък.

Примерът иска Fight Club в Русия и обработва празен отговор.

```bash
curl -sf "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
const url = 'https://api.amodb.dev/3/movie/550/showtimes?country=RU';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const data = await res.json();
if (data.results.length === 0) console.log('no showtimes known');
for (const venue of data.results) {
  for (const s of venue.showtimes) {
    console.log(venue.name, venue.city, s.start, s.formats.join(','), s.booking_url);
  }
}
```

```python
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/550/showtimes",
    params={"country": "RU"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
results = r.json()["results"]
if not results:
    print("no showtimes known")
for venue in results:
    for s in venue["showtimes"]:
        print(venue["name"], venue["city"], s["start"], ",".join(s["formats"]))
```

```php
<?php
$url = 'https://api.amodb.dev/3/movie/550/showtimes?country=RU';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$results = json_decode($body, true)['results'];
if (!$results) {
    echo 'no showtimes known', PHP_EOL;
}
foreach ($results as $venue) {
    foreach ($venue['showtimes'] as $s) {
        echo $venue['name'], ' ', $s['start'], ' ', implode(',', $s['formats']), PHP_EOL;
    }
}
```

```go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"strings"
	"time"
)

type Venue struct {
	Name      string `json:"name"`
	City      string `json:"city"`
	Showtimes []struct {
		Start      string   `json:"start"`
		Formats    []string `json:"formats"`
		BookingURL string   `json:"booking_url"`
	} `json:"showtimes"`
}

func main() {
	url := "https://api.amodb.dev/3/movie/550/showtimes?country=RU"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var body struct {
		Results []Venue `json:"results"`
	}
	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
		panic(err)
	}
	if len(body.Results) == 0 {
		fmt.Println("no showtimes known")
	}
	for _, v := range body.Results {
		for _, s := range v.Showtimes {
			fmt.Println(v.Name, v.City, s.Start, strings.Join(s.Formats, ","))
		}
	}
}
```

### Параметри

| Параметър  | Къде   | Задължителен  | Описание                                                                                                   |
| ---------- | ------ | ------------- | ---------------------------------------------------------------------------------------------------------- |
| `movie_id` | път    | да            | Числов id на филма, например `550`.                                                                        |
| `country`  | заявка | не            | Двубуквен код на държава като `RU`. Без него получавате само обобщението по държави. `region` е псевдоним. |
| `api_key`  | заявка | един от двата | Вашият ключ. Ползвайте него или заглавката `Authorization: Bearer`.                                        |

### Полета на отговора

| Поле                                                   | Тип                     | Бележки                                                                                                                             |
| ------------------------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                                   | цяло число              | Id на филма.                                                                                                                        |
| `country`                                              | низ или null            | Кодът с главни букви, който сте поискали, или `null`, когато `country` липсва или не е от две букви.                                |
| `results`                                              | масив                   | Един обект на кино, подредени по кино. Празен, когато нищо не е известно или не е изпратена държава. Най-много 1500 прожекции общо. |
| `results[].id`                                         | цяло число              | Id на киното.                                                                                                                       |
| `results[].name`                                       | низ                     | Име на киното.                                                                                                                      |
| `results[].chain`                                      | обект                   | `key` е ключът на веригата, `name` е името на веригата или `null`.                                                                  |
| `results[].city`                                       | низ или null            | Град.                                                                                                                               |
| `results[].region`                                     | низ или null            | Регион.                                                                                                                             |
| `results[].address`                                    | низ или null            | Пощенски адрес.                                                                                                                     |
| `results[].postal_code`                                | низ или null            | Пощенски код.                                                                                                                       |
| `results[].country`                                    | низ                     | Код на държавата на киното.                                                                                                         |
| `results[].timezone`                                   | низ или null            | Часова зона по IANA като `Europe/Moscow`.                                                                                           |
| `results[].latitude`, `results[].longitude`            | число или null          | Позиция на киното.                                                                                                                  |
| `results[].phone`                                      | низ или null            | Телефонен номер.                                                                                                                    |
| `results[].url`                                        | низ или null            | Страница на киното.                                                                                                                 |
| `results[].showtimes`                                  | масив                   | Прожекции в това кино, подредени по начало.                                                                                         |
| `results[].showtimes[].date`                           | низ                     | Ден като `2026-10-18`.                                                                                                              |
| `results[].showtimes[].start`                          | низ                     | Начало в местното време на киното като `2026-10-18T21:40`, без UTC отместване.                                                      |
| `results[].showtimes[].end`                            | низ или null            | Край в местното време на киното.                                                                                                    |
| `results[].showtimes[].auditorium`                     | низ или null            | Име на залата.                                                                                                                      |
| `results[].showtimes[].formats`                        | масив от низове         | Формати като `2D`.                                                                                                                  |
| `results[].showtimes[].tags`                           | масив от низове         | Допълнителни етикети. Често празен.                                                                                                 |
| `results[].showtimes[].audio`, `subtitles`, `language` | низ или null            | Данни за звук, субтитри и език, когато са известни.                                                                                 |
| `results[].showtimes[].price`                          | число или null          | Цена на билета.                                                                                                                     |
| `results[].showtimes[].currency`                       | низ или null            | Валута на `price`.                                                                                                                  |
| `results[].showtimes[].prices`                         | произволен тип или null | Подробности за цената, когато киното има няколко.                                                                                   |
| `results[].showtimes[].booking_url`                    | низ или null            | Връзка за резервиране на място.                                                                                                     |
| `results[].showtimes[].sold_out`                       | булева стойност         | `true`, когато прожекцията е разпродадена.                                                                                          |
| `countries`                                            | масив                   | Обобщение по държави, вижте по-долу.                                                                                                |

Четете ключовете, които ползвате, по име и пропускайте допълнителните ключове в обект на кино или прожекция. Много полета днес са `null`, защото не всяко кино ги изпраща.

### Примерен отговор

```json
{
  "id": 550,
  "country": "RU",
  "results": [
    {
      "id": 1114,
      "name": "Мираж Синема НА БОЛЬШОМ",
      "chain": {
        "key": "mirage-ru",
        "name": "Мираж Синема"
      },
      "city": "Санкт-Петербург",
      "region": null,
      "address": "Большой пр. П.С., д. 35А",
      "postal_code": null,
      "country": "RU",
      "timezone": "Europe/Moscow",
      "latitude": null,
      "longitude": null,
      "phone": null,
      "url": "https://www.mirage.ru/spb/cinema/1/",
      "showtimes": [
        {
          "date": "2026-10-18",
          "start": "2026-10-18T21:40",
          "end": null,
          "auditorium": null,
          "formats": ["2D"],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/aca7b114-d587-4fc5-9df6-28568e8fa9b3/",
          "sold_out": false
        },
        {
          "date": "2026-10-19",
          "start": "2026-10-19T22:20",
          "end": null,
          "auditorium": "Зал №4",
          "formats": ["2D"],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/0c32e190-890a-4c81-a754-3300fefc4d5e/",
          "sold_out": false
        }
      ]
    }
  ],
  "countries": [
    {
      "country": "RU",
      "name": "Russia",
      "venues": 2,
      "cities": 1,
      "showtimes": 7,
      "first_day": "2026-10-18",
      "last_day": "2026-10-21"
    }
  ]
}
```

Списъкът е съкратен до 1 от 2 кина и 2 от 4 прожекции. Прожекции има само за дни, които не са минали, така че този отговор се променя всеки ден.

## Вземане на обобщението по държави

Пропуснете `country` и отговорът съдържа само бройки. `results` остава празен, а `country` е `null`. Масивът `countries` изброява до 60 държави, които още имат прожекция, първо тази с най-много прожекции. Ползвайте го, за да научите къде върви заглавието, преди да поискате кината.

```bash
curl -sf "https://api.amodb.dev/3/movie/550/showtimes" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```json
{
  "id": 550,
  "country": null,
  "results": [],
  "countries": [
    {
      "country": "RU",
      "name": "Russia",
      "venues": 2,
      "cities": 1,
      "showtimes": 7,
      "first_day": "2026-10-18",
      "last_day": "2026-10-21"
    }
  ]
}
```

| Поле                                            | Тип        | Бележки                                       |
| ----------------------------------------------- | ---------- | --------------------------------------------- |
| `countries[].country`                           | низ        | Двубуквен код, готов за параметъра `country`. |
| `countries[].name`                              | низ        | Име на държавата на английски.                |
| `countries[].venues`                            | цяло число | Кина с прожекция.                             |
| `countries[].cities`                            | цяло число | Градове с прожекция.                          |
| `countries[].showtimes`                         | цяло число | Прожекции от днес нататък.                    |
| `countries[].first_day`, `countries[].last_day` | низ        | Първият и последният ден с прожекция.         |

Код на държава без данни, като `country=US` за този филм, отговаря с `country` със стойност `US`, празен `results` и същия списък `countries`. Заглавие без прожекции никъде, като сериала 1396, има `"countries": []`.

## Добавяне на прожекции към извикване за детайли

`append_to_response=showtimes` слива същия блок в отговор за детайли под ключа `showtimes`. Изпратете кода `country` в същата заявка. Блокът пази собствените си ключове `id`, `country`, `results` и `countries`.

| Заявка                                                         | Резултат                                      |
| -------------------------------------------------------------- | --------------------------------------------- |
| `/3/movie/550?append_to_response=showtimes&country=RU`         | Запис на филма плюс блок `showtimes` за Русия |
| `/3/movie/550?append_to_response=credits,showtimes&country=RU` | Добавя участници към същото извикване         |

Брои се като една заявка, така че страница на филм с актьори и прожекции иска едно извикване. Същият ендпойнт съществува за сериали като `GET /3/tv/{tv_id}/showtimes`.

## Комбиниране с now_playing и region

Списъкът now playing ви дава заглавия. Ендпойнтът за прожекции ви дава прожекциите на едно заглавие. Свържете ги във вашия код.

| Стъпка | Заявка                                               | Резултат                               |
| ------ | ---------------------------------------------------- | -------------------------------------- |
| 1      | `GET /3/movie/now_playing?region=RU&page=1`          | До 20 филма на страница, кеш 30 минути |
| 2      | `GET /3/movie/{id}/showtimes?country=RU` за всяко id | Кина и часове, където са известни      |

Цикълът по-долу повтаря веднъж или два пъти, когато е достигнат лимитът на плана, като чака броя секунди от `Retry-After`.

```js
const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };

async function get(path, retries = 2) {
  const res = await fetch(base + path, { headers });
  if (res.status === 429 && retries > 0) {
    const wait = Number(res.headers.get('Retry-After') ?? 60);
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    return get(path, retries - 1);
  }
  if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`);
  return res.json();
}

const playing = await get('/movie/now_playing?region=RU&page=1');
for (const movie of playing.results) {
  const data = await get(`/movie/${movie.id}/showtimes?country=RU`);
  if (data.results.length > 0) console.log(movie.title, data.results.length, 'venues');
}
```

Страница с 20 заглавия са 20 заявки за прожекции. При плана с 20 заявки в минута това изчерпва целия прозорец, затова кеширайте резултата при себе си. Вижте [тенденции и списъци](https://amodb.dev/bg/trending-lists/) за параметрите на списъците.

## Грешки

Тялото на грешката следва TMDB: `success`, `status_code` и `status_message`. Лош ключ дава `status_code` 7.

| HTTP | status_code | Кога                                                                      |
| ---- | ----------- | ------------------------------------------------------------------------- |
| 401  | 7           | Ключът липсва или е грешен.                                               |
| 402  | 36          | Периодът на плана е изтекъл.                                              |
| 404  | 34          | Няма филм с това id.                                                      |
| 429  | 25          | Надхвърлен е лимитът на заявки в минута. Изчакайте `Retry-After` секунди. |

Липсата на прожекции не е грешка: очаквайте статус 200 и празен масив `results`. Липсващ или невалиден `country` също не е грешка. Вижте [грешки](https://amodb.dev/bg/errors/) и [лимити на заявките](https://amodb.dev/bg/rate-limits/).

## Практически бележки

- Покритието зависи от държавата и заглавието. Третирайте празен масив `results` като неизвестно, а не като „не се дава“.
- Показвайте `start` точно както е върнато. Това е местното време на киното без UTC отместване, а часовникът на самото кино е това, което посетителите очакват.
- Прожекциите се кешират на edge за 30 минути. Не ги искайте при всеки преглед на страница и дръжте собствения си кеш кратък.
- Ползвайте един списък now playing за всички посетители в регион. Той също се кешира на edge за 30 минути.
- Ползвайте `booking_url`, за да изпратите посетителя на страницата за резервации на киното. Той е `null`, когато киното не дава връзка.
- За прегледа от гледна точка на случая на употреба вижте [API за прожекции в кината](https://amodb.dev/bg/cinema-showtimes-api/), а за другите данни за филм вижте [филми](https://amodb.dev/bg/movies/).

## Въпроси и отговори

### Задължителен ли е параметърът country?

Не, но ви трябва, за да получите кина. Подайте двубуквен код като RU или DE. Без country или с код, който не е от две букви, results е празен, а списъкът countries показва къде има прожекции. Параметърът region работи като псевдоним.

### Какво означава празен масив results?

Означава, че не са известни прожекции на това заглавие в тази държава от днес нататък. Не доказва, че филмът не върви в кината. Списъкът countries пак показва други държави с данни. Предложете вместо това датата на излизане от детайлите на филма.

### Как да намеря филмите, които се дават в кината сега?

Извикайте GET /3/movie/now_playing с параметъра region, после поискайте прожекциите на интересуващите ви id. Списъкът се кешира за 30 минути, така че можете да го ползвате повторно за всеки посетител.

### Часовете в часовата зона на посетителя ли са?

Не. Стойността start е местното време в киното и няма UTC отместване. Всяко кино има и timezone, например Europe/Moscow. Показвайте start както е върнато и не го преобразувайте с часовата зона на посетителя.

## Свързани страници

- [API за прожекции в кината](https://amodb.dev/bg/cinema-showtimes-api/): API за прожекции: GET /3/movie/{movie_id}/showtimes с код на държава връща кина, начални часове и формати, където са известни. Съчетайте с now_playing.
- [Ендпойнти за тенденции и списъци](https://amodb.dev/bg/trending-lists/): API за филми в тенденция с пътища на TMDB v3: класации за ден и седмица, списъци в кината, популярни, най-добри и предстоящи, кеш 30 минути.
- [API за детайли на филм](https://amodb.dev/bg/movies/): API за детайли на филм със същите пътища и JSON като TMDB v3. Един филм по id, а актьори, рейтинги и настроения през append_to_response, на 14 езика.
- [Рейтинги на филми и сериали](https://amodb.dev/bg/ratings/): API за рейтинги на филми връща оценки от IMDb, Kinopoisk, Metacritic, Rotten Tomatoes и TMDB за заглавие с едно извикване, с null за неизвестен източник.
- [Лимити на заявките](https://amodb.dev/bg/rate-limits/): amodb ограничава всеки ключ по заявки в минута в плъзгащ се прозорец от 60 секунди: 20, 40 или 120. Заглавки за лимита и обработка на 429 с Retry-After.
- [Бърз старт](https://amodb.dev/bg/quickstart/): Първата ви заявка към amodb: вземете ключ, поискайте детайли за филм с curl, JavaScript, Python, PHP или Go и заредете постера от img.amodb.dev. До 2 минути.

Обновено: 2026-10-18. Source: https://amodb.dev/bg/showtimes/