Watch-IP

访问者地理位置 API 参考

GET/v1/geo

返回当前连接客户端可用的位置与补充信息数据。从访问者的浏览器调用它,描述的就是该访问者的连接;而从您的应用服务器发起的请求,描述的则是服务器自身的连接。

身份验证

通过 X-Api-Key 请求头提供一个来源锁定的公开可用密钥,或使用 key 查询参数作为替代方式。访问控制来自为该密钥配置的允许来源列表(会与请求的 Origin/Referer 请求头进行比对),而不是依靠对密钥保密——因为它本就设计为出现在浏览器源代码中。

响应字段

ip
当前连接客户端的 IP 地址。
country、region、regionCode、city、postalCode、continent
近似位置信息,当底层边缘数据无法解析时为 null。
latitude、longitude
解析出的位置的近似坐标,并非设备或 GPS 位置。
timezone
IANA 时区名称,不可用时为 null。
isEUCountry
布尔值;是一个位置标记,并非法律意义上的判定。
asn、asOrganization
当底层数据提供该信息时,返回所连接的网络及其运营方;否则为 null。
currency、callingCode
根据解析出的国家得出的区域上下文信息,不可用时为 null。
locale、holidays、compliance、tax、ageVerification
可选的派生补充信息分组,均可独立为 null。这些均不构成法律、税务或身份方面的判定。
hostname
仅在通过 ?include=hostname 请求时才会出现;为反向 DNS 查询结果,查询失败时为 null。
security
在不包含该功能的方案中会被完全省略。如存在:isTor、isVpn、isDatacenter、isThreat、isSanctionedNetwork——均为基于名单的指标。目前尚未实现 IPv6 的 Tor 检测;值为 false 仅表示在可用数据中未找到匹配项,并不代表不存在风险。

错误

401
API 密钥缺失或无效。
403
该请求的 Origin/Referer 不在该密钥的允许来源列表中。此响应不会设置 CORS 请求头,因此无论 JSON 响应体如何,浏览器都会拦截该响应。
429
当前固定一分钟窗口内的速率限制已超出。

示例

请求

curl https://api.watch-ip.com/v1/geo \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY"

响应 — 仅为示例;字段会因方案与可用数据而异

{
  "ip": "203.0.113.1",
  "country": "US",
  "region": "Texas",
  "regionCode": "TX",
  "city": "Austin",
  "postalCode": "78701",
  "latitude": 30.2672,
  "longitude": -97.7431,
  "continent": "NA",
  "timezone": "America/Chicago",
  "isEUCountry": false,
  "asn": 12345,
  "asOrganization": "Example ISP",
  "currency": { "code": "USD", "name": "US Dollar", "symbol": "$" },
  "callingCode": "+1"
}

限制

受您所在方案的月度请求上限与每分钟速率限制约束——详见定价页面。每次成功调用都会被记录为一次 geo 用量事件。

相关页面