无需第三方脚本，通过 IP 对访客进行地理定位

网络上的大多数 IP 地理定位都通过一个 JavaScript 标签实现，由访客的浏览器向第三方发起调用。这意味着要多加载一个脚本，浏览器要多等待一个请求，而且如果访客屏蔽了它，还会多一个可能悄无声息地失败的环节。

改用服务端查询

/v1/ip 端点接收一个 IP 地址并直接返回位置数据。如果您从自己的后端调用它，使用 Web 服务器在传入连接上已经看到的 IP 地址，访客的浏览器中就完全不会运行任何脚本。

GET /v1/ip?ip=203.0.113.42

{
  "status": "ok",
  "ip": "203.0.113.42",
  "version": 4,
  "found": true,
  "country": "France",
  "country_code": "FR",
  "region": "Ile-de-France",
  "city": "Paris",
  "postcode": "75001",
  "lat": 48.8566,
  "lon": 2.3522,
  "timezone": "Europe/Paris",
  "asn": 12345,
  "org": "Example Networks"
}

省略 IP 参数

如果调用该端点时不带 ip 参数，它会查询调用方自身的地址，当您的后端代表当前连接的访客发出请求时，这会很方便。当您已经记录了地址、打算稍后再查询时，就需要显式传入 ip 参数。

返回内容

国家、地区和城市足以满足大多数个性化场景。有了 timezone 字段，您通常无需为了知道该访客的当地时间而进行第二次查询。asn 和 org 字段标识该地址所属的网络，这对于简单个性化之外的用途很有帮助，例如识别托管服务商或企业网络。

一个值得处理的边缘情况

并非每个地址都能解析出位置。对于保留的、未分配的或根本不在数据集中的地址段，found 字段为 false，此时位置字段将缺失或为空。请在读取 country 或 city 之前先检查 found，而不要假定成功的 HTTP 响应总是意味着可用的位置，因为针对私有或保留地址的请求仍会返回 200，同时 found 为 false。

值得避免的错误

在每一次页面浏览时都调用该端点，而不是每个会话调用一次，是网站白白耗尽配额最常见的原因。在同一次访问中，访客的 IP 地址以及由此得出的大致位置，通常不会在页面之间发生变化。请在会话开始时查询一次，将结果与会话关联存储，之后的每个页面都从这份存储的副本中读取，而不是再次调用端点。

请求费用与缓存

每次 IP 查询计为一个请求。由于访客的位置在单个会话内很少变化，请只查询一次并在会话期间存储结果，而不是在每次页面浏览时都调用。这样一个典型网站的用量就能轻松保持在每个密钥附带的、或单个地址在不使用密钥时即可获得的每天 2,500 次免费请求之内。

一个相关的查询

同一个端点和同样的响应结构也适用于 IPv6 地址，无需对请求做任何修改，响应中的 version 字段会告诉您返回的是哪种地址族。如果您的流量中 IPv6 访客占有相当比例，请参阅 IPv6 查询文档。

在服务端运行查询，可以让第三方脚本完全不进入您的页面，这对速度和可靠性都很重要。完整的字段列表请参阅 IPv4 查询文档。

• X
• LinkedIn
• Facebook
• Reddit
• Hacker News
• Telegram
• WhatsApp
• Mastodon
• 电子邮件