Watch-IP

从您的后端查询 IP 地址

将提供的 IP 地址解析为可用的国家、地区、城市及大致坐标数据。Watch-IP 的 IP 查询 API 接受 IPv4 与 IPv6 输入，并返回由第三方 IP 地理定位数据库支持的 JSON 结果。请在您的服务器上使用私密 API 密钥，并围绕明确的匹配结果、缺失的记录以及可能为空的位置字段来构建您的应用。

查看查询方案沟通查询接入 →

提供您想要解析的地址

使用您应用收集到的 IP 地址调用 GET /v1/lookup/{ip}，并通过 Authorization: Bearer 携带私密密钥进行身份验证。该查询解析的是 URL 中的地址，而不是发起该请求所使用的连接，这使其适用于已经包含 IP 地址的后端流程，包括报表统计与区域补充信息。在依赖转发请求头之前，请先核实您的应用是如何获取终端用户 IP 的；只信任您自己控制的代理路径。对于普通的网站访问者集成场景，浏览器地理位置端点提供了另一条路径，使用公开可用密钥并附带区域补充信息。

从单个地址扩展到批量查询

如果您的流程中包含多个 IP 地址，批量端点在单次请求中最多可接受 100 个地址，并按相同顺序返回结果。它使用与单个查询相同的结果结构，以及相同的服务器端私密密钥身份验证模型。批量处理改变的只是您发送请求的方式——查询用量仍按每个 IP 计算，因此一次批量请求并不等于一个查询用量单位。

围绕近似数据进行设计

一个 IP 地址可能代表一个共享网关、托管网络、VPN 出口或移动运营商连接。位置记录可能并不完整，也可能在不同数据提供商之间存在差异。请将查询结果作为您所提供地址的上下文信息使用，而不是作为某个人居住地或身份的证明。

响应字段

ip
与该结果关联的输入地址。
found
是否找到匹配的数据库记录。False 也可能意味着数据库不可用或尚未加载完成——并不能证明该地址没有位置数据。
country, continent
国家与大洲代码（如果可用）。
region
来自当前映射关系的一个次级行政区划标识符，并不总是完整的地区名称。
city, latitude, longitude
大致的城市与坐标（如果源数据库中存在）。
postalCode, timezone
当前的来源数据库不会填充这两个字段——始终为 null。

发起一次服务器端请求

cURL — GET /v1/lookup/{ip}

curl --fail-with-body \
  'https://api.watch-ip.com/v1/lookup/8.8.8.8' \
  --header "Authorization: Bearer ${WATCH_IP_SECRET_KEY}"

请先在您服务器的环境变量中设置 WATCH_IP_SECRET_KEY。8.8.8.8 只是一个语法上有效的示例地址；本示例并不保证其对应特定的国家、城市或响应结果。

常见问题

我可以使用该 API 查询别人的 IP 地址吗？

该端点接受一个提供的 IP 地址，并返回数据库中可用的位置数据，而不是某个人的姓名、确切地址或身份信息。请仅处理您有权处理的数据。

它支持 IPv6 吗？

该端点会校验 IPv4 与 IPv6 输入。一个有效的地址仍然可能缺少数据库记录，或缺少部分位置字段。

查询结果是否包含时区、ASN 或 VPN 检测？

不包含。当前的查询响应不包含 ASN 或安全指标，其来源数据库也不会填充 timezone 或 postalCode 字段。如果访问者地理位置那种基于发起连接客户端的模型适合您的应用，请另行了解该功能。

我可以从浏览器 JavaScript 发起该请求吗？

不可以——切勿在浏览器代码中暴露查询用的私密密钥。请从您的后端发起查询调用；如需在浏览器中直接获取地理位置，请使用带公开可用密钥的访问者端点。

免费的访问者密钥是否包含该功能？

不包含。查询使用单独的私密密钥与方案系列；访问者免费方案不授予服务器端查询的访问权限。

found: false 表示什么？

表示查询未返回匹配记录。在当前实现中，这种情况也可能发生在数据库不可用或尚未加载完成时，因此请展示“位置不可用”，并将这一结果与无效输入、身份验证失败和速率限制错误区分开来。

相关页面