API 参考

单 IP 查询的端点、响应格式与 HTTP 错误。

端点

基础 URLhttps://api.ipquery.io无需 API 密钥

调用者 IP

GET/默认： text/plain

返回发起请求的地址。浏览器 fetch 识别浏览器连接；服务器端 fetch 识别服务器。

请求

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/?format=json"

单 IP

GET/:ip默认： application/json

将一个 IPv4 或 IPv6 地址放入路径中。结果描述该地址，与调用者的连接无关。

请求

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/1.1.1.1"

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/2606:4700:4700::1111"

使用 HTTPS。添加 ?format=json ，以满足应用获取结构化本机 IP 结果的需要。

响应格式

设置 format 查询值以选择响应表示形式。

JSON: ?format=jsonapplication/json
XML: ?format=xmlapplication/xml
YAML: ?format=yamlapplication/x-yaml
文本: ?format=texttext/plain

文本仅返回地址。JSON、XML 和 YAML 返回结构化查询结果。

错误与批量查询

读取成功查询结果前，请检查 HTTP 状态。错误响应体遵循已识别的 format 查询参数；省略格式或使用不支持的格式会返回纯文本。

无效地址

HTTP 404

检查地址语法。路径接受一个 IPv4 或 IPv6 地址。

请求

curl -i "https://api.ipquery.io/not-an-ip?format=json"

HTTP 404

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error":"IP address not-an-ip not found"}

不支持的格式

HTTP 400

使用 json、xml、yaml 或 text。CSV 不是 API 响应格式。

请求

curl -i "https://api.ipquery.io/1.1.1.1?format=csv"

HTTP 400

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Invalid format

批量查询已禁用

HTTP 400

为访客使用本机 IP 端点，或请求单个地址。重试相同的批量请求不会使其启用。

请求

curl -i "https://api.ipquery.io/1.1.1.1,8.8.8.8?format=json"

HTTP 400

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"Bulk lookups are disabled due to abuse. For your own IP, embed fetch(\"https://api.ipquery.io/?format=json\") in your app, or use a single-IP lookup at https://api.ipquery.io/<ip>."}

处理失败的请求

浏览器 GET 请求支持跨域访问。网络故障会导致 fetch返回的 Promise 被拒绝；HTTP 错误仍会使 Promise 兑现为响应。请检查 response.ok 后再解析 JSON。

检查 HTTP 状态

const response = await fetch(
  "https://api.ipquery.io/1.1.1.1?format=json",
  { signal: AbortSignal.timeout(5000) }
);
if (!response.ok) {
  const message = await response.text();
  throw new Error("IPQuery " + response.status + ": " + message);
}
const data = await response.json();
console.log(data.ip);

连接错误与服务器故障

超时或 5xx 响应不是 IP 记录。请保留明确的不可用状态，并限制重试次数。上游错误响应体可能是文本或 HTML，因此不要假定每个响应都包含 JSON。

缺失的来源字符串可能为空。false 标记表示未匹配，并非安全结论。阅读字段定义

实际响应

1.1.1.1

实时单 IP 响应

{
  "ip": "1.1.1.1",
  "isp": {
    "asn": "AS13335",
    "org": "Cloudflare, Inc.",
    "isp": "Cloudflare, Inc."
  },
  "location": {
    "country": "Australia",
    "country_code": "AU",
    "city": "Brisbane",
    "state": "Queensland",
    "zipcode": "",
    "latitude": -27.474848400186662,
    "longitude": 153.00996200912815,
    "timezone": "Australia/Brisbane",
    "localtime": "2026-11-03T14:32:36"
  },
  "risk": {
    "is_mobile": false,
    "is_vpn": false,
    "is_tor": false,
    "is_proxy": false,
    "is_datacenter": true,
    "risk_score": 20
  }
}