团队如何使用
BI 看板
每日数据导入 Power BI、Tableau、Looker 或您的数据仓库，与您自己的销售数据并列。
预测模型
将预售曲线和可比影片作为模型输入，预测首周末及整个放映周期的表现。
另类数据
上市影院运营商的每日观影人次及其背后的影片，比季度报告早数月。
端点
下列每条路径都是 SEATmio 仪表板本身所用的端点。除非某行另有说明，均接受通用参数，且只在您的套餐范围内返回数据。
市场与排名
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/overview | 该时段的合计、每日票数以及热门影片、院线和国家。 |
| GET | /v1/rank/{film|chain|market|cinema|distributor} | 按影片、院线、国家、影院或公司的完整排名，含占比、上座率、场均观影人次和同口径变化。可用 chain= 或 film= 缩小范围。 |
| GET | /v1/detail/{film|chain|market|cinema|distributor}/{key} | 单个影片、院线、国家或影院：合计、每日序列、细分、星期 x 小时、制式，以及影片的预售曲线。 |
| GET | /v1/compare?dim=film&keys=a,b,c&align=release | 并排显示两到五部影片、院线、国家或影院的每日曲线；align=release 让每部影片从首映日开始对齐。 |
| GET | /v1/weekend?friday=YYYY-MM-DD | 周末票房（按票数），周五至周日按影片统计，对比上一个周末，含上映周次、单影院票数和累计。 |
| GET | /v1/live | 今日至今：合计、按开场时间的票数、热门影片和当天最畅销的场次。 |
| GET | /v1/legs | 持续放映影片：最近七个放映日的上映周次、与前一周同口径的跌幅以及倍数。 |
| GET | /v1/search?q= | 按名称查找影片、影院和公司。 |
单部影片
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/film/{key}/presale?country=xx | 单个国家的预售：尚未放映场次已售出的票数。 |
| GET | /v1/film/{key}/presale-start | 各院线何时开始售卖该片、各国哪家院线最先开售，以及哪些院线尚未开售。 |
| GET | /v1/film/{key}/forecast | 预计首周成绩，仅在模型已证明其准确度的地区发布。 |
| GET | /v1/legs/film/{key} | 影片在各国的上映周次及周环比跌幅。 |
| GET | /v1/film/{key}/programming | 各影院的排片质量：场次、上座率、该片在该影院按上座率和按场次的排名、黄金时段占比和影厅大小。 |
| GET | /v1/film/{key}/lost-slots | 谁占了影片的档期：按影院、影厅和时段，列出获得其流失场次的影片及双方上座率。 |
| GET | /v1/film/{key}/missing-cinemas | 影片所在国家中未放映该片的影院，而同类影片在那里卖得很好。 |
| GET | /v1/demand/film?film={key} | 影片在各国的需求指数：票数占比除以场次占比（高于 1.2 场次不足，低于 0.8 场次过多）。 |
| GET | /v1/audience/film/{key}?part=versions|timing | 语言版本（场次占比对比票数占比，逐城市）或观众提前多久购票，对比市场和同类影片。 |
| GET | /v1/film/{key}/interest | 各国上映前的关注度指数，含其信号和 60 天历史。 |
| GET | /v1/film/{key}/social | 影片社交账号的逐日数据及话题标签计数。 |
上映规划
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/premieres | 未来 120 天内或过去 7 天内上映的影片及其预售票数。 |
| GET | /v1/release-calendar?weeks=16 | 各国未来数周：上映影片、其预售、相互竞争的大规模上映数量和节假日，以及提前最多一年公布的片目。 |
| GET | /v1/demand | 范围内每部影片及其需求指数：哪些影片的销量超出其银幕数，哪些不及。 |
| GET | /v1/free-screens?country=xx&weeks=YYYY-MM-DD,... | 某国每周预计空出的银幕与新片所需银幕的对比，附估算的实测误差。 |
| GET | /v1/cut-risk?film=&chain= | 各院线通常在上座率低于多少时削减影片场次（按上映周次），以及该片本周的风险。 |
| GET | /v1/calendar | 范围内国家在所选日期内的公共假日和学校假期。 |
影院、场次与排片
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/screenings?dim={film|chain|market|cinema}&key= | 某部影片、院线、国家或影院的单个场次：影厅、版本、票数、座位数和上座率；未来场次显示当前已售。 |
| GET | /v1/screening/{id} | 单个场次：开场前逐日售票情况，对比当天该片和该影院的平均场次。 |
| GET | /v1/schedule?days=7 | 未来几天（最多 21 天）已公布的排片，按影片和院线，对比一周前的同一星期几。 |
| GET | /v1/schedule/film/{key} | 单部影片的排片：未来 14 天的院线 x 日期、前一周以及近期取消的场次。 |
| GET | /v1/cancellations?days=7 | 最近几天（最多 14 天）开场前被撤下的场次，按影片和院线。 |
| GET | /v1/cinema/{id}/programming | 单家影院的所有影片，按上座率和场次排名。 |
| GET | /v1/cinema/{id}/nearby?km=5|10|25 | 商圈：范围内的影院、本影院在其票数中的占比，以及竞争对手卖得更好的影片。 |
| GET | /v1/cinema/{id}/benchmark | 单家影院与其商圈和所在国家的对比。 |
| GET | /v1/cities | 范围内的城市排名，附地图坐标。 |
公司与人物
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/company/{id}/films?role= | 发行商、制片方或销售代理的影片及其在您所选国家的成绩。 |
| GET | /v1/people?category=&q= | 按其影片票数排名的人物：导演、演员、编剧等。 |
| GET | /v1/person/{id} | 人物档案：其影片在您所选国家的成绩、作品年表和奖项。 |
背景与数据质量
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/events?country=xx | 所选期间影院附近的大型演唱会和比赛，以及自然灾害。 |
| GET | /v1/weather?country=xx | 观众所在地的每日天气：单家影院，或按票数加权的国家。 |
| GET | /v1/coverage | 各国在最近 7 天内读取到销售数据的影院。 |
| GET | /v1/freshness | 数据最近一次更新的时间，以及各院线今天最新的读取。 |
| GET | /v1/status | 各国家和院线：已读取影院、最近读取、起始时间及任何未解决问题。 |
通用参数
- from
- 起始日，YYYY-MM-DD（默认：30 天前）
- to
- 结束日，YYYY-MM-DD（默认：今天）
- countries
- 以逗号分隔的 ISO 国家代码，如 de,fr,br（默认：套餐内全部）
- chains
- 以逗号分隔的院线键（默认：套餐内全部）
- compare
- period | year | none：添加上一周期或去年同期
- own
- 1：仅显示标记为您所有的影片、院线和影院
身份验证
每个请求都需在 Authorization 标头中携带您组织的密钥。密钥可访问的范围与您的套餐完全一致：与控制台相同的国家、院线和历史数据。
限制与格式
通过 HTTPS 传输 JSON，UTF-8 编码，日期采用各国家当地时间。每个密钥每分钟 60 次请求。数据每 30 分钟刷新一次；昨日数据于 06:00 UTC 起完整。
示例
curl -H "Authorization: Bearer $SEATMIO_KEY" \
"https://seatmio.com/api/v1/rank/film?from=2026-09-28&to=2026-10-04&countries=de,fr"
{
"range": ["2026-09-28", "2026-10-04"],
"rows": [
{
"key": "film x|2026",
"title": "Film X",
"tickets": 412380,
"screenings": 9214,
"occupancy": 0.312,
"share": 0.221,
"prevTickets": 351904,
"matchedTickets": 369720,
"change": 0.0506,
"perScreening": 44.8,
"venues": 611,
"countries": 2,
"firstShow": "2026-10-02"
}
]
}变化按可比口径计算：本期每一天与上期同一天配对（按周比较即同一星期几），只统计在配对两天都读取到的影院。prevTickets 和 previous 是这些配对上的上期数值，matchedTickets 和 currentMatched 是本期数值；change 是两者之间的变化，若配对覆盖的票数不足本期的十分之一则为 null。tickets 和 current 始终涵盖全部影院。
API 权限包含在 API 套餐中。经过简短沟通后，由我们的团队签发密钥。
申请 API 权限