Watch-IP

面向您网站的访问者地理位置

直接从访问者的浏览器调用 GET /v1/geo，获取该连接可用的国家、城市、时区及区域上下文信息。配置您允许的来源，添加您的公开可用密钥，并决定您的应用应如何处理响应。

获取免费的访问者 API 密钥阅读快速入门 →

请求来自访问者的浏览器

GET /v1/geo 始终描述的是连接它的那个客户端。从访问者的浏览器调用它，即可获得该连接的位置数据；若从您的应用服务器发起请求，得到的则是服务器自身连接的信息，而非访问者的信息。如果您已经在后端持有终端用户的 IP 地址并需要解析它，请改用单独的 IP 查询 API。访问者密钥是公开可用的——它本就设计为出现在浏览器代码中——因此真正的访问控制在于为其配置的允许来源列表，而非密钥本身的保密性。

设计为建议，而非强制跳转

旅行者可能身处一个国家的网络环境中，却更偏好另一种语言，而 VPN 甚至可能将连接完全置于其他地方。请为访问者提供可见的方式来更改建议的语言、国家或货币，并保留该选择，而不是在每次访问时都重新根据位置进行推断。

安全上下文仅适用于符合条件的方案

在包含该功能的方案中，响应可携带基于名单的 VPN/Tor/威胁指标。未包含 security 对象，仅表示该字段不在您的方案范围内，并不代表该网络已被判定为安全；值为 false 仅表示在可用的数据源中未找到匹配项，这与“确认安全”并不相同。不同指标及 IP 版本的覆盖范围也有所不同——例如，目前尚未实现 IPv6 的 Tor 检测。

响应中的实用上下文

country、region、city、latitude、longitude
当前连接请求的近似位置。并非设备或 GPS 定位，也不能作为某个具体人员所在位置的证据。
timezone、currency、callingCode
根据解析出的位置得出的区域上下文信息，可作为初始建议使用。
asn、asOrganization
在可用的情况下，提供连接所用网络及其运营方信息。组织名称并不代表某个人的身份。
security
除非您的方案包含该功能，否则完全不会出现。如存在：isVpn、isTor、isDatacenter、isThreat、isSanctionedNetwork——均为基于名单的指标，并非安全保证。

添加第一个请求

浏览器 JavaScript

async function loadVisitorLocation() {
  const response = await fetch('https://api.watch-ip.com/v1/geo', {
    headers: { 'X-Api-Key': 'YOUR_PUBLISHABLE_KEY' },
  });

  if (!response.ok) {
    throw new Error(`Visitor geolocation failed (${response.status})`);
  }

  const geo = await response.json();
  return { country: geo.country ?? null, city: geo.city ?? null, timezone: geo.timezone ?? null };
}

将占位符替换为您的访问者密钥，并从该密钥允许的来源运行此页面。当请求失败或字段缺失时，请确保您网站的默认体验仍然可用。

常见问题

这会请求设备位置权限吗？

不会。基于 IP 的请求不会使用浏览器的设备地理位置 API——它是根据连接来估算位置，而非请求设备提供的坐标。您自身的隐私与同意义务仍取决于您的应用如何使用该结果。

我可以向 /v1/geo 传入一个 IP 地址吗？

不可以。该端点始终描述的是当前连接的客户端。如果您想提供一个地址进行查询，请从后端使用 /v1/lookup/{ip}。

为什么服务器端渲染的请求会显示我的托管服务商所在的位置？

对于该请求而言，服务器本身就是连接的客户端。请将访问者请求迁移到浏览器代码中，或从后端使用 IP 查询端点，并配合可信的终端用户 IP 来源。

城市或坐标是精确的吗？

不是。IP 地理位置是与该连接相关联的一种估算，并非某个人的精确位置。

我可以在浏览器中使用密钥吗？

不可以。该端点请使用公开可用的访问者密钥，并将密钥仅保存在您的后端环境中。

相关页面