Сеансы ў кінатэатрах

Атрыманне сеансаў фільма

GET /3/movie/{movie_id}/showtimes?country=RU вяртае кінатэатры, што паказваюць фільм у адной краіне, са сеансамі па датах у кожным. Параметр country прымае двухлітарны код у верхнім або ніжнім рэгістры. Пакрыццё залежыць ад краіны і назвы, таму даныя ёсць там, дзе яны вядомыя, і адсутнічаюць там, дзе не. Вяртаюцца толькі дні, пачынаючы з сённяшняга.

У прыкладзе запытваюцца сеансы Fight Club у Расіі і апрацоўваецца пусты адказ.

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

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);
  }
}

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
$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;
    }
}

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.

Палі адказу

Чытайце патрэбныя вам ключы па назве і прапускайце лішнія ключы ўнутры аб’екта кінатэатра або сеанса. Многія палі сёння роўныя null, бо не кожны кінатэатр іх адпраўляе.

Прыклад адказу

{
  "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 краін, дзе яшчэ ёсць сеанс, першай ідзе краіна з найбольшай колькасцю сеансаў. Выкарыстоўвайце яго, каб даведацца, дзе назва ідзе ў кінатэатрах, перш чым запытваць кінатэатры.

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

{
  "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"
    }
  ]
}

Код краіны без даных, напрыклад country=US для гэтага фільма, адказвае country са значэннем US, пустым results і тым жа спісам countries. Назва без сеансаў нідзе, напрыклад серыял 1396, мае "countries": [].

Дадаванне сеансаў да выкліку дэталяў

append_to_response=showtimes далучае той жа блок да адказу дэталяў пад ключом showtimes. Адпраўце код country у тым жа запыце. Блок захоўвае ўласныя ключы id, country, results і countries.

Гэта лічыцца адным запытам, таму старонцы фільма з акцёрамі і сеансамі патрэбны адзін выклік. Той жа эндпоінт ёсць для серыялаў: GET /3/tv/{tv_id}/showtimes.

Спалучэнне з now_playing і region

Спіс now playing дае назвы. Эндпоінт сеансаў дае сеансы для адной назвы. Злучайце іх у сваім кодзе.

Цыкл ніжэй паўтарае запыт адзін-два разы, калі дасягнуты ліміт плана, чакаючы колькасць секунд з Retry-After.

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 запытамі ў хвіліну гэта ўсё акно, таму кэшуйце вынік на сваім баку. Параметры спісаў гл. на старонцы трэнды і спісы.

Памылкі

Цела памылкі адпавядае TMDB: success, status_code і status_message. Дрэнны ключ дае status_code 7.

Адсутнасць сеансаў не памылка: чакайце статус 200 і пусты масіў results. Адсутны або няправільны country таксама не памылка. Гл. памылкі і ліміты запытаў.

Практычныя заўвагі

• Пакрыццё залежыць ад краіны і назвы. Лічыце пусты масіў results невядомасцю, а не адсутнасцю ў пракаце.
• Паказвайце start дакладна так, як вярнулася. Гэта мясцовы час кінатэатра без зруху UTC, а гадзіннік самога кінатэатра і чакаюць наведвальнікі.
• Сеансы кэшуюцца на edge на 30 хвілін. Не запытвайце іх на кожны прагляд старонкі і трымайце ўласны кэш кароткім.
• Выкарыстоўвайце адзін спіс now playing для ўсіх наведвальнікаў рэгіёна. Ён таксама кэшуецца на edge на 30 хвілін.
• Выкарыстоўвайце booking_url, каб адправіць наведвальніка на старонку бранавання кінатэатра. Ён роўны null, калі кінатэатр не дае спасылкі.
• Агляд з боку выпадку выкарыстання гл. на старонцы API сеансаў у кінатэатрах, а іншыя даныя фільма на старонцы фільмы.