获取一部电影的放映场次

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一次请求获取详情和场次，见放映场次

showtimes 响应中的字段：

字段类型含义
idinteger电影 ID
countrystring 或 null你请求的 2 位字母代码，没有有效值时为 null
resultsarray每家影院一项，没有已知数据或缺少 country 时为空
countriesarray各国数量：country、name、venues、cities、showtimes、first_day、last_day
results[].id、name、city、addressinteger、strings影院 ID、名称、城市和街道地址
results[].chainobject 或 null院线的 key 和 name
results[].timezonestring 或 null影院所在的 IANA 时区，例如 Europe/Moscow
results[].latitude、longitudenumber 或 null位置（已知时）
results[].region、postal_code、phone、urlstring 或 null影院的其他信息，常为 null
results[].showtimesarray该影院的放映场次
showtimes[].datestring当地日期，例如 2026-10-18
showtimes[].startstring当地开场时间，例如 2026-10-18T21:40，不带偏移
showtimes[].auditoriumstring 或 null影厅名称或编号
showtimes[].formatsarray放映格式，例如 2D、IMAX 或 Dolby Atmos
showtimes[].tagsarray额外标签，例如 Reserved Seating
showtimes[].booking_urlstring 或 null购票链接（已知时）
showtimes[].sold_outboolean数据源标记该场次售罄时为 true
showtimes[].end、audio、subtitles、language、price、currency、prices多种类型，常为 null仅在影院数据源提供时才有值

一个响应最多包含 1,500 个场次，按影院排序，再按开场时间排序。

三步开始

  1. 打开定价页并选择套餐。每个套餐都包含放映场次。
  2. 在账户后台创建密钥。
  3. 请求 /3/movie/{movie_id}/showtimes 并带上 country 代码，密钥通过 api_key 或 Bearer 请求头传递。

请求示例

bash 示例读取《搏击俱乐部》（ID 550）在俄罗斯的放映场次，amodb 目前有该片在俄罗斯的场次。JS 示例取俄罗斯 now_playing 列表的前五部电影，并为每家影院打印最多三场放映，没有已知数据时则给出提示。

bashjs 
curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -H "Authorization: Bearer $AMODB_KEY"
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 列出有数据的国家显示中性提示，而不是空表格
没有发送 countryresults 为空，country 为 null，countries 有数量让用户从 countries 中选择
未知的电影 ID404，status_code 为 34检查 ID
超出速率429，status_code 为 25等待 Retry-After 秒

空数组不是错误，也不表示这部电影没有在影院上映。它的意思是没有已知的放映数据。完整的响应体格式见错误。

构建当前上映影片的列表页

组合两个接口。列表告诉你哪些电影正在上映，场次接口补全放映信息。

步骤请求说明
1GET /3/movie/now_playing?region=US&page=1每页最多 20 部电影，缓存 30 分钟
2GET /3/movie/{movie_id}/showtimes?country=US每部电影一次调用，缓存 30 分钟
3在你的代码中筛选按 city、formats 或 tags

一页 20 部电影需要 21 个请求。热门大片的响应可能达到几百 KB，因为它最多包含 1,500 个场次。在每分钟 20 个请求的套餐上，这要占满整整一分钟的额度，所以请在后台任务中获取，并用你保存的副本为访客提供服务。每分钟 40 和 120 个请求的套餐能从容完成同样的任务。窗口和响应头见速率限制，其他列表接口见热门趋势与列表。

保持副本新鲜

放映场次每天都会变化，不像电影详情。请把每个响应连同电影 ID、国家和获取时间一起保存。对多数列表页来说，30 分钟到几小时的 TTL 就可以，已经开场的场次可以通过把 start 与影院 timezone 下的当前时间比较来隐藏。由于 start 不带偏移，请不要把它转换到访客的时区。

对比

能力抓取影院网站不含场次的元数据 APIamodb
搭建每个影院网站一个爬虫不提供一个接口，一种 JSON 结构
匹配电影 ID按片名文本匹配不提供路径中直接是电影 ID
覆盖范围取决于你能抓到什么无因国家和作品而异，未知时返回空数组
格式与订票解析标签和链接不提供formats、tags 和 booking_url 字段
维护网站改版就会失效无所有国家都是同一种 JSON 结构

定价

预付套餐为 1、3、6、12 或 24 个月，周期越长折扣越大，分别为 0、10、20、30 或 40%。没有任何内容会自动续费。套餐分别允许每分钟 20、40 和 120 个请求，每个套餐都包含放映场次以及所有其他数据。一个每 30 分钟刷新几个国家的列表页，用最小的速率就够了。没有免费额度。请在定价页选择套餐。