# 影院放映时间 > GET /3/movie/{movie_id}/showtimes?country=RU 返回某国家放映该电影的影院及各场次。不带 country 时只返回各国数量。覆盖因国家和影片而异，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` 参数接受两位代码，大小写均可。覆盖范围因国家和影片而异，所以已知的地方有数据，未知的地方缺失。只返回从今天起的日期。 示例请求俄罗斯的《搏击俱乐部》，并处理空结果。 ```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 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` | 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 个仍有场次的国家，场次最多的排在最前。在请求影院之前，可用它了解某部作品在哪里上映。 ```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` | 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` 中的秒数。 ```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/zh/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/zh/errors/)和[速率限制](https://amodb.dev/zh/rate-limits/)。 ## 实用说明 - 覆盖范围因国家和影片而异。把空的 `results` 数组视为未知，而不是没有上映。 - 原样展示 `start`。它是影院的当地时间，没有 UTC 偏移，访客期望看到的正是影院自己的时钟时间。 - 放映时间在边缘缓存 30 分钟。不要为每次页面浏览都请求，并让你自己的缓存保持较短。 - 同一地区的所有访客复用一份正在上映列表。它同样在边缘缓存 30 分钟。 - 用 `booking_url` 把访客送到影院的订票页面。影院没有提供链接时它为 `null`。 - 用例概览见[影院放映时间 API](https://amodb.dev/zh/cinema-showtimes-api/)，电影的其他数据见[电影](https://amodb.dev/zh/movies/)。 ## 常见问题 ### country 参数是必填的吗？ 不是必填，但要获取影院就需要它。请传入两位代码，例如 RU 或 DE。不带 country，或代码不是两位字母时，results 为空，countries 列表会显示哪些国家有放映数据。region 参数可作为别名使用。 ### results 为空数组表示什么？ 表示从今天起，该国家没有该影片的已知放映时间。这并不证明影片没有在上映。countries 列表仍会显示有数据的其他国家。可改为展示电影详情中的上映日期。 ### 如何找到正在影院上映的电影？ 用 region 参数调用 GET /3/movie/now_playing，再对你关心的 ID 请求放映时间。该列表缓存 30 分钟，所以可以为所有访客重复使用。 ### 时间是按访客所在时区显示的吗？ 不是。start 的值是影院当地时间，没有 UTC 偏移。每个影院还带有 timezone，例如 Europe/Moscow。请按返回值原样展示 start，不要用访客的时区转换它。 ## 相关页面 - [影院场次 API](https://amodb.dev/zh/cinema-showtimes-api/): 影院场次 API：带国家代码调用 GET /3/movie/{movie_id}/showtimes，获取影院、开场时间和格式，可搭配 now_playing。 - [热门与榜单接口](https://amodb.dev/zh/trending-lists/): 兼容 TMDB v3 路径的热门电影 API：日榜与周榜，以及电影和电视剧的正在上映、热门、高分、即将上映榜单，缓存 30 分钟。 - [电影详情 API](https://amodb.dev/zh/movies/): 路径和 JSON 与 TMDB v3 相同的电影详情 API：按 ID 取电影，用 append_to_response 加入演职员和评分，支持 14 种语言。 - [电影与电视剧评分](https://amodb.dev/zh/ratings/): 一次调用返回作品的 IMDb、Kinopoisk、Metacritic、Rotten Tomatoes 和 TMDB 评分，来源未知时为 null。 - [速率限制](https://amodb.dev/zh/rate-limits/): amodb 按滑动 60 秒窗口内每分钟请求数限制每个密钥：按套餐为 20、40 或 120。读取速率限制响应头，并用 Retry-After 处理 429。 - [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。 更新于: 2026-10-18. Source: https://amodb.dev/zh/showtimes/