GeoNames City Search and Nearby Cities

Search city-name prefixes, look up GeoNames IDs and find nearby cities using daily refreshed GeoNames data.

原始信息汇总

数据集概述

GeoNames City Search and Nearby Cities 是一个基于 GeoNames 数据的城市搜索与邻近城市发现 API，提供城市自动补全、城市详情查询和基于地理坐标的周边城市搜索功能。该API无需构建地理索引，数据每日自动刷新，并附带来源与快照元数据。

---

主要功能

• 城市前缀搜索：对城市的主要名称、ASCII 名称和替代名称进行大小写与口音不敏感的模糊匹配，支持国家过滤和分页。
• 城市详情查询：通过 GeoNames ID 获取城市详细信息。
• 邻近城市搜索：基于大圆距离计算，支持极点和反经线处理，查找坐标周围指定半径内的城市（半径不超过 500 km）。

---

可用接口（API端点）

方法	路径	功能说明
GET	/v1/cities	按前缀搜索城市；可选国家过滤；每页 1–100 条，偏移量 0–10,000。
GET	/v1/cities/{city_id}	按 GeoNames ID 获取城市信息；ID 不在当前快照中时返回 404。
GET	/v1/nearby	按经纬度查找周边城市；半径 >0 且 ≤500 km；结果按距离和 ID 排序。

---

技术特性

• 数据来源：GeoNames（遵循 CC BY 4.0 许可），每日自动摄取。
• 覆盖范围：GeoNames cities1000 数据集及行政驻地；并非所有聚落都包含。
• 搜索行为：结果按规范化名称和 ID 排序；分页时需关注 next_offset 及快照版本。
• 冷启动：长时间无活动后首个请求可能需要数十秒的响应时间。

---

限制与错误处理

• 输入限制：前缀最长 128 字符；页面大小 1–100；偏移量 0–10,000；邻近搜索半径 0–500 km（不含0）。
• 不包含功能：街道地址地理编码、路线规划、地图瓦片、实时 GPS 及语言选择端点。
• 错误处理：无效输入返回 400/413/415/422；需要认证或订阅时检查 Key、Host 和方案；瞬时 429/503/504 建议使用带抖动的指数退避重试，并遵循 Retry-After 请求头。

---

订阅方案

• BASIC：$0 / 月，包含 20 次请求（用于集成测试）。
• PRO：$14 / 月，每日 30,000 次请求，含硬每日配额，最多 10 次请求/秒。

---

数据模型关键字段

• City：包含 ID、名称、国家、国家名称、纬度、经度、人口、时区、修改日期、可选距离（用于邻近搜索）。
• Results：包含城市列表、next_offset、数据来源与快照元数据。
• Attribution：数据来源信息（名称、URL、许可及许可 URL）。
• Metadata：快照结构版本、记录数、创建时间、版本标识及源文件哈希。
• ErrorEnvelope：错误代码与请求 ID（32 位十六进制）。

---

数据归属与许可

数据来源于 GeoNames，遵循 CC BY 4.0 许可。响应中会包含数据来源与快照元数据，用户在使用数据时需保留归属与许可信息。