适用场景公交到站信息常见于出行类应用、站点大屏、小程序线路页等场景。用户关心的是「这站还有几站来车」「车牌是多少」「票价多少」「开往哪个方向」。实时公交到站接口按官方城市名和官方站名查询该站各公交线路的实时到站信息返回车牌、预计到站时间、剩余站数、票价和终点方向。它的核心约束在于名称城市名、站名必须与本接口给出的官方名称一致。地图软件里的「五一广场地铁站」这类带括号的写法不能直接用于到站查询。因此接入的第一步不是发请求而是先把名称对齐。接口能力边界该接口通过type参数切换六种查询模式理解这一点比记住单个参数更重要。type 取值作用说明query到站查询默认值返回指定站台各线路的实时车辆cities覆盖城市列表查询前先在此核对城市短名stations按关键词搜索官方站名queryable为 true 的站点可用于到站查询line静态线路详情含全程站点、首末班和票价line-live线路实时车辆一条线路当前方向上的全部实时车辆line-search按路号搜索本地线路line可留空留空时列出该城市可查线路接口只提供到站与线路数据不提供路径规划、换乘建议或地图渲染。具体的鉴权方式、请求头、返回字段名与 QPS 限制以文档为准。准备事项与参数填写第一次调用前按下面顺序准备用typecities核对城市短名不要用自己习惯的城市称呼用typestations按关键词搜索官方站名确认queryable为 true若已知线路可先用typeline-search找到本地线路再查line或line-live最后用typequery查实时到站。参数方面type决定查询模式city填官方城市短名station填官方站名direction用于区分同一站名对应的多个站台line用于指定线路。同一站名可能对应多个站台到站查询时direction的取值需要结合站台信息确认具体写法以文档为准。curl 接入示例下面以到站查询为例给出可复制的请求模板。API Key 与鉴权字段请按文档要求替换。curl -X POST https://v1.apizero.cn/api/bus-realtime \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d { type: query, city: 城市短名, station: 官方站名, direction: 方向值, line: }先查城市列表的请求只需切换typecurl -X POST https://v1.apizero.cn/api/bus-realtime \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {type: cities}搜索站名时把type换成stations并在请求体里带上关键词参数参数名以文档为准。用代码接入以 Python 的requests为例import requests URL https://v1.apizero.cn/api/bus-realtime API_KEY YOUR_API_KEY # 按文档要求替换 def bus_realtime(payload: dict) - dict: headers { Content-Type: application/json, Authorization: fBearer {API_KEY}, # 以文档为准 } resp requests.post(URL, jsonpayload, headersheaders, timeout10) resp.raise_for_status() return resp.json() if __name__ __main__: print(bus_realtime({type: cities}))超时一定要设置公交数据具有时效性长时间挂起的请求对业务没有价值。返回值解读到站查询返回的核心信息包括车牌、预计到站时间、剩余站数、票价和终点方向。阅读时建议按以下顺序核对先确认返回是否成功错误码含义以文档为准再看该站台返回了几条线路是否覆盖你关心的线路逐条核对车牌、剩余站数与预计到站时间是否自洽终点方向用于区分同线路的不同行驶方向不要忽略。stations查询的返回中queryable为 true 才表示该站可用于到站查询。这个字段是接入时最容易漏看的一项建议在代码里显式判断。常见错误现象可能原因排查方向查不到站站名与官方名称不一致先用stations搜索官方站名城市不识别城市短名写错先用cities核对到站结果为空站点queryable不为 true换用可查询站点方向混淆同名站台对应多个方向结合direction区分站台线路找不到路号写法不一致先用line-search搜索本地线路请求超时网络或服务波动设置超时并做有限重试错误码的具体数值与含义以文档为准不要凭经验判断。工程化注意事项名称缓存官方城市名与站名变化不频繁可缓存cities与stations结果减少重复查询。时效性处理到站数据本身有时效前端展示应带时间戳避免用户看到过期结果。限流意识QPS 与调用配额以文档为准接入前确认业务峰值。失败兜底查询失败时保留站点信息不要直接清空页面。参数校验type取值做白名单校验避免拼写错误导致无效请求。参考文档实时公交到站文档
