Country State City - Search REST API

Countries, states, and cities API with search, autocomplete, stable IDs, ISO codes, coverage metadata, and bulk lookup.

原始信息汇总

数据集概述：Country State City - Search REST API

数据集名称：Country State City - Search REST API
提供者：Open APIs
类别：Location
版本：1.0.1（当前）
简介：该API是一个生产级的位置数据接口，提供标准化且稳定的国家、州/省和城市数据。它专为地址表单、结账流程、用户注册、CRM、市场平台、旅游产品、物流工具、目录和位置智能等功能设计。

核心数据特性：

• 稳定公共ID：为国家、州和城市提供稳定、公共的唯一标识符。
• 标准编码：包含ISO2和ISO3国家代码，以及州/省代码（如有）。
• 地理位置信息：提供经纬度坐标和时区数据。
• 数据覆盖元数据：指明哪些国家没有州或城市，帮助应用处理现实中的特殊情况。
• 数据集同步：提供周级数据集同步可见性和变更日志端点，便于监控数据新鲜度。

主要功能与端点（共10个）：

• 国家：
  • GET /countries：获取所有国家列表。
  • GET /countries/{countryCode}：根据国家代码获取单个国家详情。
  • GET /countries/{countryCode}/coverage：获取特定国家的覆盖元数据（如是否有州/城市）。
  • GET /countries/search：全文搜索国家。
• 州/省：通过相关“States”端点获取。
• 城市：通过相关“Cities”端点获取，支持自动补全（typeahead UI）。
• 查找：
  • 按经纬度查找附近城市（nearby-city lookup）。
  • 批量查找（bulk lookup）：支持批量处理多个位置查询。
  • 单点查找（single-location lookup）。
• 元数据：通过“Metadata”端点获取数据集同步信息和变更日志。
• 健康检查：提供API健康状态端点。

常见应用场景：

• 实现国家、州、城市的下拉选择框。
• 地址和结账表单的自动填充与验证。
• 用户注册表单中的位置选择。
• CRM系统中位置数据的丰富与补充。
• 市场平台买家和卖家档案中的位置信息。
• 旅游和预订搜索功能（如目的地筛选）。
• 物流和航运应用中的区域定位。
• 目录和列表网站按位置分类展示。
• 搜索栏中的城市自动补全（如“纽约”快速显示）。
• 验证用户输入的位置数据是否有效。

技术支撑：

• 数据来源：Countries States Cities Database。
• 部署平台：Cloudflare Workers，确保全球低延迟访问。
• 文档：提供OpenAPI规范文档，便于集成。
• 定价模式：支持免费 BASIC 套餐（$0.00/月），以及 PRO（$8.00/月）、ULTRA（$15.00/月）、MEGA（$45.00/月）等订阅计划。