Watch-IP

批量查询 IP 地址

将一份 IP 地址列表发送到一个端点，即可获得与之对应的一份位置结果列表。Watch-IP 的批量 IP 查询 API 每次请求最多接受 100 个 IPv4 与 IPv6 地址，适用于后端补充信息流程。请将私密密钥保存在服务器端，按输入顺序处理响应，并在处理缺失记录时不丢失与原始数据的对应关系。

查看查询方案对比单个 IP 查询 →

一次请求，最多 100 个地址

使用 POST /v1/lookup，并传入一个包含 ips 数组的 JSON 对象。每个被接受的批次至少包含一个地址，最多包含 100 个，且同一列表中可以混合使用有效的 IPv4 与 IPv6 地址。响应会将按顺序排列的查询结果封装在 results 数组中；每个结果都采用与单个 IP 查询相同的结构，包括 found 与可能为空的位置字段。

使结果与您的源记录保持对齐

对于成功的批量请求，API 会按相同顺序为每个输入地址返回一条结果。请在提交列表的同时保留您自己的记录标识符，以便将结果重新关联回原始数据行。当某条记录未找到时，请保留该行并标记位置不可用；当仅有某个字段缺失时，请保留结果中其余的部分。请勿用零来替代缺失的坐标，这会把数据缺失变成一个具有误导性的地图位置。

提交前先进行校验

空列表、超过 100 个地址的列表，或格式错误的 IP，都会产生请求错误——一个格式错误的地址会导致整个批次被拒绝，而不是为其余输入生成部分成功的结果。请在发送前校验输入，并将较长的列表拆分为多个批次，同时记录已完成的批次，以避免重试时意外重复整个任务。

理解批量处理改变了什么

批量处理减少的是提交一份列表所需的 HTTP 请求数量。它不会改变数据来源，不会添加安全字段，也不会把 100 次查询变成一个用量单位——对于被接受的请求，查询用量是按每个提交的 IP 记录的，因此在选择方案时应同时考虑总查询量与请求速率。每分钟速率限制按 HTTP 调用次数计算，而不是按条目计算：一个最多包含 100 个 IP 或邮箱地址的批量请求只算一次请求，而其中每个条目仍会分别计入每月请求上限。

请求与响应结构

ips
请求体：一个包含 1 至 100 个 IPv4 或 IPv6 地址的 JSON 数组。
results
响应：一个按提交顺序排列的数组，每个输入地址对应一条记录。
results[].found, results[].country, ...
每条结果都与单个 IP 查询响应采用相同的结构与可空性——请参阅 IP 查询产品页面。

发送一次批量请求

cURL — POST /v1/lookup

curl --fail-with-body \
  'https://api.watch-ip.com/v1/lookup' \
  --header "Authorization: Bearer ${WATCH_IP_SECRET_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"ips":["8.8.8.8","2001:4860:4860::8888"]}'

这些示例地址并不代表特定的实际位置数值。请先在您服务器的环境变量中设置 WATCH_IP_SECRET_KEY。

常见问题

一个批次最多能容纳多少个 IP 地址？

当前上限为 100 个。请将较长的列表拆分为多个请求，每个请求包含 1 至 100 个地址。

一个批次中可以同时包含 IPv4 与 IPv6 吗？

可以。每个地址都必须有效，且不同地址的数据库覆盖情况可能有所不同。

结果是否按输入顺序返回？

是的。一个成功被接受的批次，会按相同顺序为每个输入地址返回一条结果。

如果其中一个 IP 格式错误会怎样？

整个请求都会被拒绝。请在提交前校验您的输入——该端点不会对格式错误的输入提供部分成功的结果。

一个批次是否按一次查询计费？

不是。用量按每个 IP 计算。在估算大批量任务的成本之前，请查看当前的查询定价与已验证的计费示例。

我可以上传 CSV 文件吗？

该文档化端点接受的是一个地址的 JSON 数组。您的应用可以自行读取 CSV 文件并提交批次；托管式的 CSV 上传界面并不属于该 API 的一部分。

批量查询是否包含 VPN 或 Tor 检测？

不包含。当前的批量响应只是第三方地理定位数据库的位置结果。访问者地理位置的安全指标是一项独立的能力，不会出现在查询响应中。

相关页面