country 参数是必填的吗？

不是必填，但要获取影院就需要它。请传入两位代码，例如 RU 或 DE。不带 country，或代码不是两位字母时，results 为空，countries 列表会显示哪些国家有放映数据。region 参数可作为别名使用。

results 为空数组表示什么？

表示从今天起，该国家没有该影片的已知放映时间。这并不证明影片没有在上映。countries 列表仍会显示有数据的其他国家。可改为展示电影详情中的上映日期。

如何找到正在影院上映的电影？

用 region 参数调用 GET /3/movie/now_playing，再对你关心的 ID 请求放映时间。该列表缓存 30 分钟，所以可以为所有访客重复使用。

时间是按访客所在时区显示的吗？

不是。start 的值是影院当地时间，没有 UTC 偏移。每个影院还带有 timezone，例如 Europe/Moscow。请按返回值原样展示 start，不要用访客的时区转换它。

电影放映时间 API：按国家和影片查询影院场次

获取电影的放映时间

GET /3/movie/{movie_id}/showtimes?country=RU 返回在某个国家放映该电影的影院，以及各影院带日期的场次。country 参数接受两位代码，大小写均可。覆盖范围因国家和影片而异，所以已知的地方有数据，未知的地方缺失。只返回从今天起的日期。

示例请求俄罗斯的《搏击俱乐部》，并处理空结果。

curl JavaScript Python PHP Go

bashjspyphpgo

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 请求头。

响应字段

字段	类型	说明
`id`	integer	电影 ID。
`country`	string 或 null	你请求的大写代码；`country` 缺失或不是两位字母时为 `null`。
`results`	array	每个影院一个对象，按影院排序。没有已知数据或未传国家时为空。场次总数最多 1500。
`results[].id`	integer	影院 ID。
`results[].name`	string	影院名称。
`results[].chain`	object	`key` 是院线键，`name` 是院线名称或 `null`。
`results[].city`	string 或 null	城市。
`results[].region`	string 或 null	地区。
`results[].address`	string 或 null	街道地址。
`results[].postal_code`	string 或 null	邮政编码。
`results[].country`	string	影院所在国家的代码。
`results[].timezone`	string 或 null	IANA 时区，例如 `Europe/Moscow`。
`results[].latitude`、`results[].longitude`	number 或 null	影院位置。
`results[].phone`	string 或 null	电话号码。
`results[].url`	string 或 null	影院页面。
`results[].showtimes`	array	该影院的场次，按开始时间排序。
`results[].showtimes[].date`	string	日期，形如 `2026-10-18`。
`results[].showtimes[].start`	string	影院当地时间的开始时间，形如 `2026-10-18T21:40`，没有 UTC 偏移。
`results[].showtimes[].end`	string 或 null	影院当地时间的结束时间。
`results[].showtimes[].auditorium`	string 或 null	影厅名称。
`results[].showtimes[].formats`	array of strings	放映格式，例如 `2D`。
`results[].showtimes[].tags`	array of strings	额外标签。通常为空。
`results[].showtimes[].audio`、`subtitles`、`language`	string 或 null	已知时的音轨、字幕和语言信息。
`results[].showtimes[].price`	number 或 null	票价。
`results[].showtimes[].currency`	string 或 null	`price` 的币种。
`results[].showtimes[].prices`	any 或 null	影院有多种价格时的价格详情。
`results[].showtimes[].booking_url`	string 或 null	订座链接。
`results[].showtimes[].sold_out`	boolean	场次售罄时为 `true`。
`countries`	array	各国汇总，见下文。

请按名称读取你用到的键，并跳过影院或场次对象中的额外键。目前许多字段为 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"
    }
  ]
}

列表已缩减为 2 个影院中的 1 个、4 个场次中的 2 个。场次只存在于尚未过去的日期，所以这个响应每天都会变化。

获取各国汇总

不带 country 时，响应只有数量。results 保持为空，country 为 null。countries 数组最多列出 60 个仍有场次的国家，场次最多的排在最前。在请求影院之前，可用它了解某部作品在哪里上映。

curl

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`	string	两位代码，可直接用作 `country` 参数。
`countries[].name`	string	英文国家名称。
`countries[].venues`	integer	有场次的影院数。
`countries[].cities`	integer	有场次的城市数。
`countries[].showtimes`	integer	从今天起的场次数。
`countries[].first_day`、`countries[].last_day`	string	有场次的第一天和最后一天。

没有数据的国家代码，例如这部电影的 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 搭配

正在上映列表给你作品。放映时间接口给你某部作品的场次。在你的代码中把两者连起来。

步骤	请求	结果
1	`GET /3/movie/now_playing?region=RU&page=1`	每页最多 20 部电影，缓存 30 分钟
2	对每个 ID 调用 `GET /3/movie/{id}/showtimes?country=RU`	影院和时间（已知时）

下面的循环在达到套餐上限时重试一两次，等待 Retry-After 中的秒数。

JavaScript

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。

HTTP	status_code	何时出现
401	7	密钥缺失或错误。
402	36	套餐周期已结束。
404	34	没有该 ID 的电影。
429	25	超过每分钟请求数。请等待 `Retry-After` 秒。

没有放映时间不是错误：预期是状态 200 和空的 results 数组。缺失或无效的 country 也不是错误。见错误和速率限制。

实用说明

覆盖范围因国家和影片而异。把空的 results 数组视为未知，而不是没有上映。
原样展示 start。它是影院的当地时间，没有 UTC 偏移，访客期望看到的正是影院自己的时钟时间。
放映时间在边缘缓存 30 分钟。不要为每次页面浏览都请求，并让你自己的缓存保持较短。
同一地区的所有访客复用一份正在上映列表。它同样在边缘缓存 30 分钟。
用 booking_url 把访客送到影院的订票页面。影院没有提供链接时它为 null。
用例概览见影院放映时间 API，电影的其他数据见电影。