id-verne iGPSPORT 路书下载器
输入 iGPSPORT 路书编号(或关键词),自动登录 → 搜索 → 拉取航点 → 生成 GPX 文件,可直接导入 OsmAnd / Garmin / 两步路 / Strava 等地图软件。
核心事实(必须告知用户)
- 中国站与国际站是两套独立系统:账号不通用、路书编号不互通、数据也不一样。同一个编号在两个站可能指向完全不同的路书。
- 小红书等平台分享的国内路书,通常是中国站的编号,必须用中国站账号登录才能拉到。
- 登录接口报
code:1002 "Password error"时,可能是密码错,也可能是该账号根本没在对应站注册(接口不区分)。 - iGPSPORT 没有公开 API,以下接口是逆向自网页版的私有接口,可能失效,失效时需要重新用 bb-browser 抓包确认。
- token 持久化:默认登录后 token 缓存在
~/.cache/igpsport/(按 api+邮箱分文件,权限 600),有效期内复用,不重复登录。要强制重新登录用--clear-token。
环境要求
- Python 3 +
requests库(pip install requests) - 一个 iGPSPORT 账号及密码(中国站账号和国际站账号要分开记)
使用方法
脚本位置:scripts/igpsport_download.py(本 skill 目录下)。
1. 按路书编号下载(推荐,精确)
python scripts/igpsport_download.py \
--route 123456 \
--email "你的邮箱" \
--password "你的密码" \
--api "https://prod.zh.igpsport.com" \
--outdir ./downloads
2. 按关键词搜索后再下载
python scripts/igpsport_download.py \
--search "某路线名" \
--email "你的邮箱" \
--password "你的密码" \
--api "https://prod.zh.igpsport.com"
搜索模式会列出所有匹配路书(id / 标题 / 距离 / 区域 / 作者),选取目标 id 后用 --route 精确定位下载。
3. 国际站(若目标路书在国际站)
python scripts/igpsport_download.py \
--route 123456 \
--email "国际站邮箱" \
--password "国际站密码" \
--api "https://prod.en.igpsport.com"
参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
--route |
与 --search 二选一 |
路书编号(数字) |
--search |
与 --route 二选一 |
关键词搜索 |
--email |
是 | iGPSPORT 账号邮箱/手机号 |
--password |
是 | 账号密码 |
--api |
否 | 默认国际站 https://prod.en.igpsport.com;中国站填 https://prod.zh.igpsport.com |
--outdir |
否 | 输出目录,默认当前工作目录(Claude Code 的启动位置,即 os.getcwd())。生成的文件在 {outdir}/{routeId}-{标题}.gpx |
--clear-token |
否 | 清除该 api+邮箱的缓存 token 后退出(换账号/强制重新登录时用) |
支持的操作 & 判定
- 登录成功判断:
code == 0且返回access_token - 搜索接口:
GET /service/web/api/Routes/RouteListForWeb?type=find&key={关键词或编号} - 详情接口:
GET /service/web/api/Routes/DetailsRoutesWeb?routeId={编号}(返回routeInfo.tracks航点数组,含 latitude / longitute / alt) - 生成 GPX 1.1:每个航点为
<trkpt><ele>…</ele></trkpt>,起点终点为<wpt> - 输出文件名:
{routeId}-{标题}.gpx - 验证产物:
grep -c "<trkpt" *.gpx与路书航点数一致;python -c "import xml.dom.minidom as m; m.parse('文件')"校验 XML
常见失败 & 处理
| 现象 | 原因 | 处理 |
|---|---|---|
code:1002 Password error |
密码错 / 账号不在该站注册 | 让用户确认站别和密码;或让用户把密码重置成已知值(重置是即时生效的) |
| HTTP 403 | 被风控或站别错误 | 加浏览器 UA + Referer https://app.igpsport.cn/;确认用的是对应站的 API |
| 搜索 0 条 | 编号属于另一站 / 路书已删 | 换另一个站试;或改用关键词 --search |
| 接口 404 | 私有接口已变更 | 用 bb-browser 打开 https://app.igpsport.cn/login,登录后进"Routes"→搜索,抓包看最新接口路径 |
备选:用 bb-browser 交互式抓取(接口失效时)
bb-browser open https://app.igpsport.cn/login(中国站)或https://app.igpsport.com/login(国际站)- 让用户在 bb-browser 的可见窗口里手动登录(避免处理 React 表单状态)
bb-browser eval "localStorage.getItem('IGSTOKEN')"拿到 token- 用该 token 直接调详情接口或让脚本复用 token
注意:bb-browser 启动的是独立 Chrome 实例,不会自动带上用户个人 Chrome 的登录态;登录必须在 bb-browser 自己的窗口内完成。