中国行政区划下载（china-admin-divisions）

通过瑞朵豹 map.ruiduobao.com 的免费公开 API，下载中国五级行政区划矢量数据 （省/市/县/乡/村）。无需任何凭据。

Quickstart

# 1) 搜索
python scripts\china_admin_divisions.py search 锦江
python scripts\china_admin_divisions.py search 510104 --level xian

# 2) 树状下钻
python scripts\china_admin_divisions.py cities --province 四川省
python scripts\china_admin_divisions.py counties --province 四川省 --city 成都市
python scripts\china_admin_divisions.py towns --province 四川省 --city 成都市 --county 锦江区
python scripts\china_admin_divisions.py villages \
    --province 四川省 --city 成都市 --county 锦江区 --town 锦华路街道

# 3) 元信息（含 bbox + 1 km 扩展）
python scripts\china_admin_divisions.py info --code 510104 --expand-km 1
python scripts\china_admin_divisions.py bbox --name 海淀区 --province 北京市 --expand-km 2

# 4) 下载单个矢量
python scripts\china_admin_divisions.py download --code 510104 --format geojson
python scripts\china_admin_divisions.py download --code 510104 --format shp --out jinjiang.zip
python scripts\china_admin_divisions.py download --code 510104 --format kml

# 4b) 乡/村级 code 没有 geojson 边界？跳过拉取，仅返回元信息
python scripts\china_admin_divisions.py info --code 510104017 --no-geojson

# 5) 批量下载某省所有市
python scripts\china_admin_divisions.py download-children \
    --province 四川省 --level shi --format shp --out ./sichuan_shp

子命令

子命令	用途	主要参数
search	模糊搜索	keyword [--province] [--level] [--limit]
cities	列出某省所有市	--province
counties	列出某市所有县	--province --city
towns	列出某县所有乡	--province --city --county
villages	列出某乡所有村	--province --city --county --town
info	单个区划元信息	--code 或 --name [--province] [--city] [--level]
bbox	仅看 bbox + 面积	同上 + --expand-km
download	下载单个矢量	--code 或 --name + --format + --out
download-children	批量下辖下载	--province + --level + [--city] [--county] [--out]

支持的下载格式

--format	输出后缀	备注
geojson	.geojson	标准 GeoJSON，单文件（gson 是历史别名，仍可用）
shp	.zip	ESRI Shapefile（zip 内含 .shp/.shx/.dbf/.prj）
kml	.kml	Google Earth
gpkg	.gpkg	GeoPackage，OGC 标准
svg	.svg	矢量图
png	.png	纯形状 PNG（无任何文字标注），需要 Pillow

不同用户群体怎么选：

• GIS / 数据分析：geojson 或 shp（最通用，QGIS / ArcGIS / GeoPandas 直接吃）
• 前端可视化 / Web 制图：svg（矢量缩放无损，可在浏览器内交互）
• 日常看图 / 报告插图：png（位图，PPT / Word 直接贴，纯形状不标文字）
• OGC 互操作 / 数据库：gpkg

Permissions

• 网络出口：https://map.ruiduobao.com（国内主机，默认直连绕过代理）。 通过 RUIDUOBAO_USE_PROXY=1 强制走系统代理。
• 环境变量读取：
  • RUIDUOBAO_USE_PROXY（决定是否使用系统代理）
• 文件读取：无（除脚本自身）。
• 文件写入：CLI 输出目录（--out 指定的路径或当前目录）。

Notes

• 1 km bbox 扩展使用平面近似（1° lat ≈ 110.574 km，1° lon ≈ 111.320·cos(mid_lat) km）。 极地 / 跨 180° 经线会失真，五级区划范围通常不会触发。
• 乡/村级 code（9/12 位）在上游 API 端可能没有面边界。默认情况下 info 仍会返回 name/code/level/province/city/... 元信息，但 bbox_wgs84 / area_km2 为 null，并带 vector_available: false
  • vector_error 字段。也可以用 --no-geojson 完全跳过矢量拉取。
• 瑞朵豹 API 是免费公共服务，调用请勿过频。
• 默认所有网络调用不走代理（瑞朵豹在国内 + VPN 不稳）。如确实需要代理请设置 RUIDUOBAO_USE_PROXY=1。
• --format 历史别名：gson 等价于 geojson，仍可继续使用以兼容旧脚本。

Output Contract

info / bbox 子命令返回的 JSON 字段：

{
  "name": "锦江区",
  "code": "510104",
  "level": "xian",
  "province": "四川省",
  "city": "成都市",
  "year": 2023,
  "source": "ruiduobao",
  "bbox_wgs84": [104.05, 30.62, 104.16, 30.71],
  "bbox_wgs84_expanded": [104.04, 30.61, 104.17, 30.72],
  "area_km2": 60.32,
  "area_km2_expanded": 76.18,
  "vector_available": true
}

乡/村级（无矢量边界）时：bbox_wgs84 / area_km2 为 null，并附 vector_available: false 与 vector_error: "..." 字段；退出码仍为 0。