Skip to main content
GET
IP 地理定位 API
API 操作极其简单:只需提供 API 密钥和 IP 地址,即可获取包括邮政编码、城市名称、地区信息、国家详情以及精确经纬度坐标在内的全面位置数据。

快速开始

REST 架构

与所有 Cleariflow API 一样,IP 地理定位 API 遵循 REST 原则。它采用可预测的资源导向 URL,并使用 HTTP 状态码指示错误。

HTTPS 安全

与 IP 地理定位 API 的所有通信必须使用 TLS 1.2 或更高版本的协议进行保护。

API 版本控制

所有 Cleariflow API 均包含版本控制。IP 地理定位 API 当前运行在第 1 版。

使用 API 密钥进行身份验证

API 密钥是访问 Cleariflow IP 地理定位 API 的唯一身份验证凭证。请注意,每个 Cleariflow API 需要独立的 API 密钥,这意味着 IP 地理定位和邮箱验证等不同服务需要不同的密钥。要对请求进行身份验证,需将 API 密钥附加到基础 URL。

基础 URL

地理定位端点

Cleariflow IP 地理定位 API 只需您的唯一 API 密钥,并自动从请求客户端检测 IP 地址。或者,您可以包含 “ip_address” 参数来指定要分析的特定 IP:
这表示一次成功的请求,返回的 IP 地址及关联详情如下:

请求参数

String
必填
您的唯一 API 密钥。请注意,每个用户为每个 Cleariflow API 拥有独立的 API 密钥,因此您的 IP 地理定位 API 密钥无法用于邮箱验证 API,例如。
String
要定位的 IP 地址。支持 IPv4 和 IPv6 地址。请注意,若留空此参数,服务将定位发起请求的 IP 地址。
String
要返回的顶级键的逗号分隔列表(例如 ?fields=country,security)。要包含 VPN/代理标志,使用 security——将返回整个对象(is_vpnis_proxy 以及存在时的 vpn_provider)。不支持单独使用 is_vpn 等嵌套键。

响应参数

API 响应以通用、轻量的 JSON 格式 返回。
String
提交进行地理定位的 IP 地址。
String
城市名称。
String
城市的 geoname ID。
String
城市所在的州或省。
Char[2]
州或省的 ISO 3166-2 代码。
String
州或省的 geoname ID。
String
邮政编码。
String
国家名称。
Char[2]
国家的 ISO 3166-1 alpha-2 代码。
String
国家的 geoname ID。
Boolean
若国家在欧盟内则为 true,否则为 false。
String
大洲名称。
Char[2]
两字母大洲代码:AF、AS、EU、NA、OC、SA、AN。
String
大洲的 geoname ID。
Float
经度的小数值。
Float
纬度的小数值。
Boolean
当 IP 匹配枚举的 VPN 出口节点数据库(IP-to-VPN MMDB)时为 true
Boolean
当 IP 匹配代理数据库(IP-to-VPN MMDB)时为 true
String
MMDB 中的 VPN 服务名称(例如 NordVPN)。当 is_vpnfalse 时省略。
String
IANA 时区数据库中的时区名称。
String
时区缩写,同样来自 IANA 时区数据库。
String
时区相对于格林威治标准时间 (GMT) 的偏移。
String
本地时区的当前时间。
Boolean
若该位置当前处于夏令时 (DST) 则为 true。
String
托管的国家 SVG 格式国旗链接。
String
托管的国家 PNG 格式国旗链接。
String
国家国旗的表情符号。
String
国家国旗的 unicode 表示。
String
货币名称。
String
ISO 4217 格式的货币代码。
String
从 ASN 组织名称推断(例如 Cellular、Cable/DSL、Corporate、Cloud、Hosting)。VPN 和代理在 security 中报告,而非此处。
Uint32
自治系统编号。
String
自治系统组织名称。
String
互联网服务提供商 (ISP) 名称。
String
组织名称。

限制响应字段

您可以选择仅接收 JSON 响应中的部分字段。为此,可在查询参数中包含 fields 值,列出要返回的顶级键的逗号分隔列表。 例如,仅获取 IP 的国家和城市的请求如下:
响应如下:

使用场景

定位网站访客

要从 IP 地址请求地理定位,只需在下方模板中包含您的唯一 API 密钥。 请注意,发起请求时无需知道访客的 IP。
这就是从访客获取地理定位和其他数据所需的全部内容!只有一个必需参数:您的唯一 API 密钥。

响应和错误代码

当请求因某种原因失败时,也会以 JSON 格式返回错误。错误包含错误代码和描述,详见下文。

国家代码

以下是响应中使用的两字母 ISO 3166 Alpha 2 国家代码列表。在 CSV 中查看此列表。

其他说明

重要计费信息:您处理的每个 IP 地址消耗一次积分。按请求提交计费,无论响应是否成功。因此,即使提交无效 IP 地址如 “fda3346ds”,仍会从您的账户扣除一次积分。