Skip to content

FAQ

Jump to bottom
Justintunsday edited this page Sep 14, 2026 · 3 revisions

常见问题

为什么返回 502 upstream_error / 504 upstream_timeout？

上游 web.chelaile.net.cn 偶发不稳定。504 表示单次请求超过 15 秒超时，重试通常即可； 502 表示上游返回了异常结构，可带上响应里的 error.message 反馈问题。

/v1/lines/detail 返回 empty: true？

多半是地铁线路（该接口不覆盖地铁）或线路已停运。按响应里的 hint 改用 /v1/stops/detail（地铁线名、站点线路）或 /v1/transit/plan（换乘方案）。

为什么 /v1/lines/realtime 里大多数车的 eta 是 null？

上游只为最近一辆驶向目标站的车辆预测 ETA；其余车辆依然返回位置、速度、拥挤度， 这是上游行为，不是接口 bug。取 buses.find(b => b.eta) 即可。

sId、physicalStId、namesakeStId、targetOrder 有什么区别？

  • sId：线路 × 站点的实例 ID，实时查询用（station_id）
  • physicalStId：物理站台 ID，站点详情用
  • namesakeStId：同名站点 ID，站点详情的可选参数
  • targetOrder：站点在线路上的序号

/v1/stops/nearby 与 /v1/search 会同时返回这些字段，可以直接串联。

为什么换乘要 GCJ-02，别的接口要 WGS-84？

这是上游接口的约定。/v1/search 的 pois[].lat/lng 本身就是 GCJ-02，可直接用于 /v1/transit/plan；stations[].lat/lng 是 WGS-84，用于周边站点与实时查询。

/v1/my-location 定位不准？

IP 定位精度本来就是城市级，且 VPN / 代理会返回出口 IP 所在地。省略 ip 参数时返回的是 服务器出口 IP 的位置，因此部署在大陆的服务器更准确。

/v1/lines/timetable 的 mode 是 interval，没有逐班时间？

上游对多数线路（尤其上海）只提供发车间隔而非逐班时刻。首末班与票价请查 /v1/lines/detail 的 firstTime / lastTime / price。

冷启动很慢？

  • Render 免费套餐：15 分钟无请求休眠，冷启动约 30–60 秒。
  • Vercel：容器服务通常常驻，但长时间无流量后首次请求也可能较慢。
  • Cloudflare Workers：无冷启动（推荐）。
  • 线上实例：https://ts-api.tundrey.com

怎么开启鉴权防止滥用？

部署平台设置环境变量 API_KEY=<你的随机字符串>，重启后所有 /v1/* 请求需要：

X-API-Key: <API_KEY>

或 Authorization: Bearer <API_KEY>，或 ?key=<API_KEY>。

能不能直接用 GitHub Pages / Actions 当服务器？

不能。Pages 只提供静态文件；Actions 没有常驻公网端口。API 必须部署到 Vercel、Render、 Railway、VPS 等能运行 Node/Docker 的平台，详见 Deployment。

返回的城市只有 12 个？

默认只返回热门城市。需要全量 480 个城市用：

curl "https://ts-api.tundrey.com/v1/cities?hot_only=false"

数据可以商用吗？

数据来自车来了公开接口，本项目仅做协议适配，仅供学习研究。请遵守上游服务条款， 避免高频抓取与商业使用。

还有问题？

Clone this wiki locally