当前位置：首页 > news >正文

零基础快速上手实时电影票房 API：接口调用与数据解读

news 2026/7/28 10:43:05

适用场景

在影视行业、数据分析或内容运营中，需要获取电影票房的实时数据。例如：电影发行方监控自家影片的票房表现；自媒体制作每日票房榜单；数据爱好者分析市场趋势。该API提供猫眼专业版实时票房Top10，包含累计票房、实时票房、票房占比、排片占比、上座率等关键指标，按60秒缓存更新，适合非高频轮询的场景。

接口能力边界

接口名称：实时电影票房
请求方法：GET
请求地址：https://v1.apizero.cn/api/movie-box
QPS：10次/秒（匿名额度与API Key额度共用此限制）
数据来源：猫眼专业版
更新频率：60秒缓存

注意：该接口仅返回当日票房Top10，不支持指定日期查询或历史数据。如需分析历史趋势，需自行定时采集并存储。

鉴权与请求参数

Header参数

参数名	类型	必填	说明
`X-API-Key`	string	否	API Key，不传则使用匿名额度（QPS较低）

Query参数

当前接口无需任何query参数，直接使用GET请求即可。

提示：传API Key可获得更高的匿名QPS（具体以文档为准）。建议正式环境中携带Key。

curl 调用示例

以下示例使用环境变量$YOUR_API_KEY存储API Key。如果没有Key，可以直接去掉-H行，使用匿名调用（QPS可能受限）。

curl -sS \ -X GET \ -H "X-API-Key: $YOUR_API_KEY" \ "https://v1.apizero.cn/api/movie-box"

响应示例（JSON）：

{ "code": 0, "data": { "list": [ { "box_office": 163.25, "box_rate": 35.5, "name": "消失的人", "rank": 1, "release_days": "上映6天", "seat_rate": 33, "show_rate": 28.8, "total_box": "2.66亿" }, { "box_office": 98.85, "box_rate": 21.5, "name": "给阿嬷的情书", "rank": 2, "release_days": "上映7天", "seat_rate": 6.1, "show_rate": 7.3, "total_box": "6205.9万" } ], "total": 10, "update_time": "2026-05-06 07:30:00" }, "msg": "成功", "request_id": "mot9..." }

返回字段解读

字段	类型	说明
`code`	int	业务状态码，0表示成功
`msg`	string	提示信息
`request_id`	string	请求唯一标识，用于排查问题
`data.list`	array	票房排行列表，最多10条
`data.total`	int	当前列表总数（固定10）
`data.update_time`	string	数据更新时间，格式`YYYY-MM-DD HH:mm:ss`
`rank`	int	当前排名
`name`	string	电影名称
`box_office`	float	实时票房（单位由返回决定，通常为万元）
`box_rate`	float	票房占比（百分比，如35.5表示35.5%）
`show_rate`	float	排片占比（百分比）
`seat_rate`	float	上座率（百分比）
`release_days`	string	上映天数，如"上映6天"
`total_box`	string	累计票房（含单位字符串，如"2.66亿"）

注意：box_office是浮点数，可能表示万元；但为了避免误解，可以在代码中不做单位假设，直接使用原值。实际业务开发时可结合total_box字符串中的单位进行换算。

代码接入（Python）

以下Python示例演示如何调用接口并解析返回数据：

import requests import os api_url = "https://v1.apizero.cn/api/movie-box" headers = { "X-API-Key": os.environ.get("YOUR_API_KEY", "") } def fetch_movie_box(): resp = requests.get(api_url, headers=headers) resp.raise_for_status() data = resp.json() if data["code"] != 0: raise Exception(f"API error: {data['msg']} (request_id: {data['request_id']})") return data["data"] if __name__ == "__main__": box_data = fetch_movie_box() print(f"更新时间: {box_data['update_time']}") for movie in box_data["list"]: print(f"{movie['rank']}. {movie['name']} - 实时票房: {movie['box_office']}, 累计: {movie['total_box']}")