列车位置为按当日时刻表插值推算,不是 GPS 实时定位;编组信息为自建库与用户众包,
线形与车站来自 OpenStreetMap(ODbL 许可)。
GET/api/config
前端运行时配置与数据覆盖量
{"ok":true,"site":"...","amap_key":"...","coverage":{"rail_ways":0,"stations":0,"trains":0}}
GET/api/lines
按视口返回铁路线 GeoJSON,前端的铁路线图层数据源
| bbox | 必填,minLon,minLat,maxLon,maxLat |
|---|---|
| zoom | 选填,3-16,决定返回层级与抽稀 |
{"ok":true,"type":"FeatureCollection","features":[{"type":"Feature","properties":{"c":1,"n":"京沪高铁"},"geometry":{"type":"LineString","coordinates":[[116.3,39.9]]}}]}
GET/api/stations
视口内车站点,或按关键字搜索车站
| bbox | 视口范围 |
|---|---|
| q | 站名关键字(优先) |
| zoom | 选填 |
| limit | 默认 1200,最大 3000 |
{"ok":true,"type":"FeatureCollection","features":[{"properties":{"n":"北京南","k":"station"},"geometry":{"type":"Point","coordinates":[116.37,39.86]}}]}
GET/api/search
站站查询(代理上游并缓存 10 分钟)
| start | 出发站 |
|---|---|
| end | 到达站 |
| ishigh | 1 只看高铁 |
{"ok":true,"data":{"list":[{"trainno":"G33","typename":"高铁","costtime":"4小时35分"}]}}
GET/api/train
车次经停明细(含坐标匹配与累计里程)
| no | 车次,如 G1 |
|---|---|
| refresh | 1 强制刷新缓存 |
{"ok":true,"train":{"trainno":"G1","stops":[{"name":"北京南","dep":"06:30","lat":39.86,"lon":116.37,"km":0}]}}
GET/api/position
按时刻表推算列车当前位置、区间、速度、下一站预计到达
| no | 车次 |
|---|---|
| t | 选填,unix 时间戳 |
{"ok":true,"status":"running","lon":117.1,"lat":39.2,"speed_kmh":286.4,"segment":{"from":"沧州西","to":"德州东","progress":0.42},"next":{"name":"德州东","arr":"07:45","in_sec":930}}
GET/api/live
视口内在途列车推算位置(仅已缓存车次,非实时定位)
| bbox | 必填 |
|---|---|
| t | 选填时间戳 |
{"ok":true,"count":12,"trains":[{"trainno":"G1","lon":117.1,"lat":39.2,"class":"emu","status":"running"}]}
GET/api/consist
车次编组、机车、涂装、类型(自建库 + 用户众包 + 车型参考)
| no | 车次 |
|---|---|
| model | 选填,直接查车型标准编组 |
{"ok":true,"summary":{"train_model":"CR400AF","cars":8,"loco":"...","source":"用户上传·已审核"},"model_ref":{"CR400AF":{"cars":8,"formation":"4M4T"}}}
GET/api/depots
动车所/机务段/车辆段点位
| bbox | 选填 |
|---|
{"ok":true,"depots":[{"name":"北京动车段","kind":"depot","lon":116.3,"lat":39.8}]}
GET/api/reports
地图上的用户情报点
| bbox | 选填 |
|---|---|
| status | approved / pending,留空为全部 |
| limit | 默认 300 |
{"ok":true,"reports":[{"trainno":"2222","cars":8,"category":"检测车","status":"pending"}]}
POST/api/report
提交现场情报;缺坐标时用车站名匹配,再用访问者定位兜底
| trainno | 必填,如 2222 |
|---|---|
| train_model | 选填,CR450 |
| cars | 选填,0-40 |
| category | 选填,检测车/旅客列车… |
| formation | 选填,如 4M4T |
| livery | 选填,彩绘描述 |
| loco | 选填,机车型号 |
| station | 必填,通过的车站 |
| passed_at | 必填,Y-m-d H:i |
| lat | 选填,纬度 |
| lon | 选填,经度 |
| user_lat | 选填,访问者定位纬度 |
| user_lon | 选填,经度 |
| note | 选填,补充说明 |
{"ok":true,"id":12,"status":"pending","placed":{"lon":109.49,"lat":36.59}}
GET/api/docs
本页
HTML
GET/api/openapi.json
OpenAPI 3.0 描述文件
JSON
错误约定
{"ok":false,"error":"车次获取失败:..."} // HTTP 4xx / 5xx
{"ok":false,"error":"提交过于频繁,请稍后再试"} // 429