实时公交到站API参数精讲：从请求体到响应字段的完整解析

适用场景

实时公交到站API适用于需要展示公交车辆实时位置、预计到站时间和剩余站数的应用。典型场景包括：公交出行助手App、公交站牌电子显示屏、城市交通信息平台、智能语音播报系统等。通过输入城市和站名，即可获取该站点所有路线的实时到站数据，包括车牌、预计到达时间、剩余站数、票价和终点方向。该接口采用RESTful风格，请求体为JSON，响应结构清晰，适合快速集成到后端服务或微服务架构中。

接口能力边界

• 请求方法：POST
• 请求地址：https://v1.apizero.cn/api/bus-realtime
• 数据格式：JSON
• QPS限制：单API Key上限为10次/秒，超出会返回限流错误（HTTP 503）。开发阶段建议设计客户端限速，避免触发阈值。
• 覆盖范围：支持全国数百个城市，但具体每个城市的公交数据完整性需在集成前通过少量测试请求验证。接口支持双向查询（direction参数），可获取同一站点两个方向的数据。
• 数据实时性：响应中的 updated_at 字段标示数据更新时间，通常延迟在数十秒以内，具体取决于城市公交系统数据推送频率。

请求参数详解

鉴权方式

使用HTTP Header字段 X-API-Key 传递密钥。每个开发者需在平台上申请独立的API Key，并在每次请求中携带。同时必须设置 Content-Type: application/json。

请求体参数

请求体为JSON对象，包含以下字段：

参数最佳实践：

• city 应使用正确的官方名称，避免使用“长沙市”多一个“市”字可能导致的匹配问题。建议在UI中提供下拉选择或自动补全。
• station 支持关键词，因此可以设计搜索框让用户输入部分站名，后端调用接口后对返回结果做二次筛选（注意接口目前只返回一个station下的线路，若多个站匹配需自行处理）。该字段建议进行URL编码处理。
• direction 参数对往返线路至关重要。例如查询“五一广场”站，401路默认方向终点是“汽车西站”，反方向可能终点是“火车站”。应用可提供切换按钮，分别用1和2调用，展示两种方向的到站信息。

使用 curl 进行请求

以下示例使用环境变量 APIZERO_API_KEY 代替实际密钥，确保密钥不暴露在脚本中。

curl -sS \\
-X POST \\
-H "X-API-Key: $APIZERO_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"city":"长沙","station":"五一广场","direction":"1"}' \\
"https://v1.apizero.cn/api/bus-realtime"

若使用Windows命令提示符，可将换行符替换为 ^ 或写为单行。确保请求体JSON严格合法，字符串内不能有多余空格。成功响应将以JSON格式返回。

响应字段解读

成功响应示例（HTTP 200）：

{
"code": 0,
"msg": "成功",
"request_id": "a1b2c3d4",
"data": {
"city": "长沙",
"station": "五一广场",
"direction": 1,
"line_count": 2,
"lines": [
{
"line": "401路",
"price": "2",
"terminal": "汽车西站",
"bus_count": 1,
"buses": [
{
"bus_id": "湘A02882D",
"arrival_time": "2026-07-01 12:34",
"arrival_timestamp": 1751344440000,
"status": "5站",
"stops_remaining": 5,
"travel_minutes": 6
}
]
}
],
"updated_at": "2026-07-01 12:30:00"
}
}

顶层字段

data 对象

lines 数组元素

buses 数组元素

字段处理最佳实践

• 时间优先使用时间戳：arrival_timestamp 是毫秒级Unix时间戳，可用于精确计算剩余秒数。如果仅在UI显示，可以格式化 arrival_time。
• status 与 stops_remaining：虽然大多数情况下 status 如“5站”对应 stops_remaining:5，但某些情况下 status 可能是“进站中”等文本，此时 stops_remaining 可能为0。建议优先使用 stops_remaining 做数值逻辑，status 用于展示。
• 多条车辆显示：当 bus_count > 1 时，说明该线路有多辆车即将到达，可以按 arrival_timestamp 排序后展示前3辆，让用户了解后续车辆间隔。
• 票价处理：price 是字符串，如需计算总价或比较，请使用 parseFloat 转换。

常见错误及处理

401 Unauthorized

• 原因：API Key缺失、无效或过期。
• 排查：检查请求头是否包含 X-API-Key，以及值是否正确。可在平台重新生成Key。

400 Bad Request

• 原因：请求体JSON格式错误、必填参数（city/station）为空、direction不是1或2。
• 排查：用 jq . 校验请求体JSON合法性；确保city和station非空字符串。

503 Service Unavailable / Rate Limit

• 原因：QPS超过10次/秒，或服务暂时过载。
• 排查：检查客户端请求频率，添加本地限流（如令牌桶）。推荐配合指数退避重试：首次等待1秒，再次2秒，第三次4秒，最多重试3次。

业务错误（code != 0）

• 例如城市不支持、站点不存在等。通过 msg 字段获取详情，并在UI中向用户展示友好提示。

工程化注意事项

1. 安全性：API Key 管理

严禁将API Key硬编码在前端页面或客户端二进制文件中。建议：

• 后端服务作为代理，前端通过自身接口转发请求。
• 使用环境变量或安全配置中心存储Key，如 .env 文件（应加入 .gitignore）。
• 不同环境（开发/测试/生产）使用独立的Key。

2. 缓存策略

公交数据更新频繁，缓存时间不宜过长。推荐方案：

• 本地内存缓存（如LRU Cache），有效期为30秒。同一站点同一方向在30秒内重复请求时直接返回缓存。
• 对于热门站点（如市中心换乘站），可设置更短的缓存（15秒）以减少数据延迟。
• 使用Redis等分布式缓存时，需注意设置合理的TTL。

3. 并发与限流

单Key QPS 10次/秒，若服务需要同时处理数百个用户，建议：

• 使用请求队列或线程池限制并发数。
• 对同一城市多个站点可串行化请求，避免突发流量。
• 在代码中集成 RateLimiter（如Google Guava或BurstyLimiter），控制全局调用速率。

4. 错误重试与降级

• 网络超时：设置合理的超时时间（如5秒），超时后重试。使用指数退避策略。
• 服务不可用：当连续失败3次，降级使用上次缓存数据并标记“数据可能延迟”。
• 空数据：若 line_count 为0，返回“当前无公交信息”提示。

5. 数据校验与字段类型处理

• 解析响应时对字段类型做防御性判断：direction 可能是number，但JSON中可能出现字符串，建议 Number(direction)。
• price 转为浮点数时需处理异常情况（如空字符串）。
• arrival_timestamp 是毫秒，与系统当前时间戳（毫秒）做减法得到剩余毫秒，避免使用错误的单位。

6. 双向查询交互设计

• 在UI中提供“去程/返程”切换按钮，分别调用 direction=1 和 direction=2，将两个方向的数据并排展示。
• 注意：某些线路可能只有一个方向的数据，此时需隐藏另一方向或显示空状态。
• 可合并同站点的两个方向请求到同一个异步调用中，待两个promise都返回后更新视图。

参考文档

• 原始接口文档（Markdown）：https://apizero.cn/aidocs/bus-realtime/raw.md
• 接口详情页：https://apizero.cn/aidocs/bus-realtime

以上文档仅作为开发者在集成过程中的参考资料，具体接口参数以实际JSON Schema为准。