# 影院场次 API > 影院场次 API 即 GET /3/movie/{movie_id}/showtimes?country=US，返回影院的地址和时区，以及每场放映的开场时间、格式和订票链接（已知时）。覆盖范围因作品而异，results 为空表示暂无数据。 ## 获取一部电影的放映场次 `GET /3/movie/{movie_id}/showtimes?country=US` 返回在某个国家放映一部电影的影院，每家影院附带一组放映场次。`country` 是 2 位字母代码。不带它时 `results` 为空，你只会得到各国的数量。覆盖范围因国家和作品而异，`results` 数组为空表示该组合下没有已知数据。 你会得到影院名称、院线、地址和时区，以及每场放映的开场时间、影厅、格式、标签和订票链接（已知时）。只返回今天及以后的场次。响应描述的是放映场次，它不是售票服务。 ## 可获取的数据 | 接口 | 返回内容 | | ----------------------------------------------------------- | ---------------------------------------------------- | | `GET /3/movie/{movie_id}/showtimes` | 一部电影在 `country` 的影院和放映场次，不带它时返回各国数量 | | `GET /3/movie/now_playing` | 当前在影院上映的电影，可用 `region` 缩小范围 | | `GET /3/movie/{movie_id}`，配合 `append_to_response=showtimes` | 一次请求获取详情和场次，见[放映场次](https://amodb.dev/zh/showtimes/) | showtimes 响应中的字段： | 字段 | 类型 | 含义 | | ---------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------- | | `id` | integer | 电影 ID | | `country` | string 或 null | 你请求的 2 位字母代码，没有有效值时为 `null` | | `results` | array | 每家影院一项，没有已知数据或缺少 `country` 时为空 | | `countries` | array | 各国数量：`country`、`name`、`venues`、`cities`、`showtimes`、`first_day`、`last_day` | | `results[].id`、`name`、`city`、`address` | integer、strings | 影院 ID、名称、城市和街道地址 | | `results[].chain` | object 或 null | 院线的 `key` 和 `name` | | `results[].timezone` | string 或 null | 影院所在的 IANA 时区，例如 `Europe/Moscow` | | `results[].latitude`、`longitude` | number 或 null | 位置（已知时） | | `results[].region`、`postal_code`、`phone`、`url` | string 或 null | 影院的其他信息，常为 null | | `results[].showtimes` | array | 该影院的放映场次 | | `showtimes[].date` | string | 当地日期，例如 `2026-10-18` | | `showtimes[].start` | string | 当地开场时间，例如 `2026-10-18T21:40`，不带偏移 | | `showtimes[].auditorium` | string 或 null | 影厅名称或编号 | | `showtimes[].formats` | array | 放映格式，例如 `2D`、`IMAX` 或 `Dolby Atmos` | | `showtimes[].tags` | array | 额外标签，例如 `Reserved Seating` | | `showtimes[].booking_url` | string 或 null | 购票链接（已知时） | | `showtimes[].sold_out` | boolean | 数据源标记该场次售罄时为 `true` | | `showtimes[].end`、`audio`、`subtitles`、`language`、`price`、`currency`、`prices` | 多种类型，常为 null | 仅在影院数据源提供时才有值 | 一个响应最多包含 1,500 个场次，按影院排序，再按开场时间排序。 ## 三步开始 1. 打开[定价](https://amodb.dev/zh/pricing/)页并选择套餐。每个套餐都包含放映场次。 2. 在账户后台创建密钥。 3. 请求 `/3/movie/{movie_id}/showtimes` 并带上 `country` 代码，密钥通过 `api_key` 或 Bearer 请求头传递。 ## 请求示例 bash 示例读取《搏击俱乐部》（ID `550`）在俄罗斯的放映场次，amodb 目前有该片在俄罗斯的场次。JS 示例取俄罗斯 `now_playing` 列表的前五部电影，并为每家影院打印最多三场放映，没有已知数据时则给出提示。 ```bash curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const BASE = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path, params = {}) { const res = await fetch(`${BASE}${path}?${new URLSearchParams(params)}`, { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const country = 'RU'; const playing = await get('/movie/now_playing', { region: country, page: 1 }); for (const movie of playing.results.slice(0, 5)) { const { results } = await get(`/movie/${movie.id}/showtimes`, { country }); if (results.length === 0) { console.log(`${movie.title}: no showtimes known`); continue; } for (const cinema of results) { const times = cinema.showtimes .slice(0, 3) .map((s) => `${s.start.slice(5, 10)} ${s.start.slice(11, 16)} ${s.formats.join('/')}`) .join(', '); console.log(`${movie.title} at ${cinema.name}, ${cinema.city}: ${times}`); } } ``` `country=RU` 的精简响应：第一家影院及其 2 场放映。 ```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" } ] } ``` ## 覆盖范围与空结果 并非每个国家或每部作品都有影院数据。请围绕这一点规划你的界面。 | 情况 | 你看到的内容 | 应对方式 | | -------------- | ----------------------------------------------- | -------------------- | | 有已知场次 | `results` 每家影院一项 | 显示列表 | | 该国家和作品没有已知数据 | `results` 为空数组，`countries` 列出有数据的国家 | 显示中性提示，而不是空表格 | | 没有发送 `country` | `results` 为空，`country` 为 `null`，`countries` 有数量 | 让用户从 `countries` 中选择 | | 未知的电影 ID | 404，`status_code` 为 34 | 检查 ID | | 超出速率 | 429，`status_code` 为 25 | 等待 `Retry-After` 秒 | 空数组不是错误，也不表示这部电影没有在影院上映。它的意思是没有已知的放映数据。完整的响应体格式见[错误](https://amodb.dev/zh/errors/)。 ## 构建当前上映影片的列表页 组合两个接口。列表告诉你哪些电影正在上映，场次接口补全放映信息。 | 步骤 | 请求 | 说明 | | -- | ---------------------------------------------- | --------------------------- | | 1 | `GET /3/movie/now_playing?region=US&page=1` | 每页最多 20 部电影，缓存 30 分钟 | | 2 | `GET /3/movie/{movie_id}/showtimes?country=US` | 每部电影一次调用，缓存 30 分钟 | | 3 | 在你的代码中筛选 | 按 `city`、`formats` 或 `tags` | 一页 20 部电影需要 21 个请求。热门大片的响应可能达到几百 KB，因为它最多包含 1,500 个场次。在每分钟 20 个请求的套餐上，这要占满整整一分钟的额度，所以请在后台任务中获取，并用你保存的副本为访客提供服务。每分钟 40 和 120 个请求的套餐能从容完成同样的任务。窗口和响应头见[速率限制](https://amodb.dev/zh/rate-limits/)，其他列表接口见[热门趋势与列表](https://amodb.dev/zh/trending-lists/)。 ## 保持副本新鲜 放映场次每天都会变化，不像电影详情。请把每个响应连同电影 ID、国家和获取时间一起保存。对多数列表页来说，30 分钟到几小时的 TTL 就可以，已经开场的场次可以通过把 `start` 与影院 `timezone` 下的当前时间比较来隐藏。由于 `start` 不带偏移，请不要把它转换到访客的时区。 ## 对比 | 能力 | 抓取影院网站 | 不含场次的元数据 API | amodb | | ------- | ---------- | ------------ | ----------------------------------- | | 搭建 | 每个影院网站一个爬虫 | 不提供 | 一个接口，一种 JSON 结构 | | 匹配电影 ID | 按片名文本匹配 | 不提供 | 路径中直接是电影 ID | | 覆盖范围 | 取决于你能抓到什么 | 无 | 因国家和作品而异，未知时返回空数组 | | 格式与订票 | 解析标签和链接 | 不提供 | `formats`、`tags` 和 `booking_url` 字段 | | 维护 | 网站改版就会失效 | 无 | 所有国家都是同一种 JSON 结构 | ## 定价 预付套餐为 1、3、6、12 或 24 个月，周期越长折扣越大，分别为 0、10、20、30 或 40%。没有任何内容会自动续费。套餐分别允许每分钟 20、40 和 120 个请求，每个套餐都包含放映场次以及所有其他数据。一个每 30 分钟刷新几个国家的列表页，用最小的速率就够了。没有免费额度。请在[定价](https://amodb.dev/zh/pricing/)页选择套餐。 ## 常见问题 ### 如何获取一部电影的放映场次？ 带上密钥发送 GET /3/movie/{movie_id}/showtimes?country=US。country 参数是 2 位字母代码，region 可作为别名。响应会列出影院，每家影院下有各场放映，已知时包含开场时间、格式、标签和订票链接。 ### results 数组为空是什么意思？ 表示 amodb 没有该电影在该国家的放映数据。这不是错误，也不表示这部电影没有在影院上映。同一个响应中的 countries 数组仍会列出有数据的国家，因此你可以提供其他国家供选择。 ### 覆盖哪些国家？ 覆盖范围因国家和作品而异。每个响应都包含一个 countries 数组，给出影院数、城市数和场次数，最多 60 个国家，场次最多的排在前面。请按电影读取它，而不是硬编码国家列表。 ### 能列出当前正在影院上映的电影吗？ 能。带 region 参数调用 GET /3/movie/now_playing 即可列出当前上映的影片，缓存 30 分钟。从列表中取每部电影的 ID，再用同样的国家代码请求它的场次。 ### start 值使用什么时区？ start 值形如 2026-10-18T21:40，不带 UTC 偏移。请把它当作影院当地的挂钟时间。每家影院也有 timezone，例如 Europe/Moscow。不要把 start 转换成观众所在的时区。 ## 相关页面 - [影院放映时间](https://amodb.dev/zh/showtimes/): 返回某国家某部电影的影院和放映时间的 API，也可只取国家汇总。可并入详情调用，或与 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/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/cinema-showtimes-api/