适用场景与业务价值

实时电影票房 API 为开发者提供当日猫眼票房 Top 10 的实时数据，覆盖累计票房、实时票房、票房占比、排片占比、上座率等核心指标。数据源来自猫眼专业版，按 60 秒缓存刷新。

典型的应用场景包括：

• 影视数据看板：搭建内部或面向公众的电影票房实时监控大屏，展示当日排行榜及各影片关键指标。
• 内容创作与自媒体：为影评、票房分析类文章或视频提供自动化的数据支撑，减少人工采集维护复杂度。
• 辅助决策工具：影院运营方根据排片占比与上座率优化排片策略；宣发团队追踪竞品票房走势。
• 教育与演示：在编程教学、API 调试演示中作为真实案例接口，展示 JSON 数据处理与可视化。

接口能力边界

在接入前需要明确该接口的约束与限制：

需要注意，接口返回的是“当日实时数据”，并非历史或预测数据，且数据每 60 秒更新一次，不适合对秒级实时性有极端要求的场景。匿名额度有限，生产环境建议携带 API Key 使用。

鉴权与请求参数

鉴权方式

接口采用可选鉴权机制，通过 HTTP Header 传递 API Key：

X-API-Key: your_api_key_here

• 若不携带该 Header，请求将消耗匿名额度，适合开发调试与小流量场景。
• 若携带有效API Key，请求计入已认证额度，通常更稳定且享有更高调用上限（具体以文档为准）。
• 若携带无效API Key，服务端会返回鉴权错误，无法获取数据。

请求参数

本接口为 GET 请求，无需 Query 参数或 Body 参数。全部配置通过 Header 完成：

请求时无需拼接任何额外查询字符串，直接 GET 即可。

curl 接入示例

基础请求（匿名）

curl -sS -X GET "https://v1.apizero.cn/api/movie-box"

该命令会返回当前票房 Top 10 的 JSON 数据。-sS参数用于静默模式并显示错误。

携带 API Key 的请求

# 请将 YOUR_API_KEY 替换为实际密钥 curl -sS \ -X GET \ -H "X-API-Key: YOUR_API_KEY" \ "https://v1.apizero.cn/api/movie-box"

建议将 API Key 保存在环境变量中，避免硬编码。例如：

export APIZERO_API_KEY="your_key_here" curl -sS -X GET -H "X-API-Key: $APIZERO_API_KEY" "https://v1.apizero.cn/api/movie-box"

格式化输出

如需在终端中查看格式化的 JSON，可结合jq工具：

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

多语言代码接入

Python（requests）

import requests import os # 从环境变量读取 API Key，允许匿名 api_key = os.getenv("APIZERO_API_KEY", "") url = "https://v1.apizero.cn/api/movie-box" headers = {} if api_key: headers["X-API-Key"] = api_key try: response = requests.get(url, headers=headers, timeout=10) response.raise_for_status() data = response.json() # 处理返回数据 if data.get("code") == 0: movies = data["data"]["list"] print(f"更新时间: {data['data']['update_time']}") for movie in movies: print(f"{movie['rank']}. {movie['name']} - 实时票房: {movie['box_office']}万") else: print(f"接口异常: {data.get('msg')}") except requests.exceptions.RequestException as e: print(f"请求失败: {e}")

Node.js（axios）

const axios = require('axios'); const API_KEY = process.env.APIZERO_API_KEY || ''; const url = 'https://v1.apizero.cn/api/movie-box'; const headers = {}; if (API_KEY) { headers['X-API-Key'] = API_KEY; } axios.get(url, { headers, timeout: 10000 }) .then(response => { const data = response.data; if (data.code === 0) { const movies = data.data.list; console.log(`更新时间: ${data.data.update_time}`); movies.forEach(m => { console.log(`${m.rank}. ${m.name} - 实时票房: ${m.box_office}万`); }); } else { console.error('接口异常:', data.msg); } }) .catch(err => { console.error('请求失败:', err.message); });

Go（net/http）

package main import ( "encoding/json" "fmt" "io" "net/http" "os" ) type MovieBoxResponse struct { Code int `json:"code"` Msg string `json:"msg"` Data struct { List []struct { Rank int `json:"rank"` Name string `json:"name"` BoxOffice float64 `json:"box_office"` BoxRate float64 `json:"box_rate"` ShowRate float64 `json:"show_rate"` SeatRate float64 `json:"seat_rate"` TotalBox string `json:"total_box"` ReleaseDays string `json:"release_days"` } `json:"list"` UpdateTime string `json:"update_time"` } `json:"data"` } func main() { apiKey := os.Getenv("APIZERO_API_KEY") url := "https://v1.apizero.cn/api/movie-box" req, _ := http.NewRequest("GET", url, nil) if apiKey != "" { req.Header.Set("X-API-Key", apiKey) } client := &http.Client{} resp, err := client.Do(req) if err != nil { fmt.Printf("请求失败: %v\n", err) return } defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var result MovieBoxResponse json.Unmarshal(body, &result) if result.Code == 0 { fmt.Printf("更新时间: %s\n", result.Data.UpdateTime) for _, m := range result.Data.List { fmt.Printf("%d. %s - 实时票房: %.2f万\n", m.Rank, m.Name, m.BoxOffice) } } else { fmt.Printf("接口异常: %s\n", result.Msg) } }

返回值字段解读

接口返回的标准 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亿" } ], "total": 10, "update_time": "2026-05-06 07:30:00" }, "msg": "成功", "request_id": "mot9..." }

顶层字段

data 对象

list 子项字段

注意：box_office单位为万元，取数值即可用于计算；total_box为字符串，可能包含“亿”或“万”单位，数值计算前需要自行解析转换。

常见错误及处理

典型错误处理代码片段：

# Python 示例：带重试与退避的请求 import time import requests def fetch_movie_box(retries=3): url = "https://v1.apizero.cn/api/movie-box" headers = {} api_key = os.getenv("APIZERO_API_KEY", "") if api_key: headers["X-API-Key"] = api_key for attempt in range(retries): try: resp = requests.get(url, headers=headers, timeout=10) if resp.status_code == 429: wait = 2 ** attempt print(f"触发限流，等待 {wait}s 后重试...") time.sleep(wait) continue resp.raise_for_status() return resp.json() except requests.exceptions.RequestException as e: if attempt == retries - 1: raise time.sleep(2 ** attempt) return None

工程化注意事项

1. API Key 安全管理

• 不要将 API Key 硬编码在代码中或提交到版本控制系统。
• 推荐使用环境变量或密钥管理服务（如 Vault、AWS Secrets Manager）进行管理。
• 前端代码中不应直接暴露 API Key，建议通过后端代理转发请求。

2. 缓存策略

接口本身有 60 秒缓存，但在客户端层面仍然建议：

• 前端展示层可每 60 秒轮询一次，避免更高频率的无效请求。
• 若需要构建看板，可服务端缓存 30~60 秒，减少对上游接口的调用压力。
• 缓存键建议包含update_time字段，数据未变更时不更新视图。

3. QPS 与并发控制

接口 QPS 上限为 10/s，多个业务线共享时容易超限。建议：

• 使用令牌桶或信号量限制请求速率。
• 在分布式环境中，通过 Redis 等中间件做集中式限流。
• 对于非实时场景（如每日报告），将请求分散到低峰时段。

4. 数据解析注意事项

• total_box字段为字符串，包含中文单位（亿/万），数值运算前需统一转为数字。
• release_days格式固定为 "上映X天"，如需提取天数需正则解析。
• box_office单位是万元，与total_box单位不一致，对比时需注意换算。

5. 异常兜底

• 接口可能因数据源问题返回空列表或异常 code，前端应展示占位数据而非崩溃。
• 建议设置合理的超时时间（如 10s），避免请求卡死。
• 关键业务监控request_id与update_time，及时发现数据异常。

参考文档

• 实时电影票房 API 文档
• 原始 Markdown 文档