IP Info（免费 IP 地理位置查询 API）

IP Info 是由 Shifter 维护的免费 IP 地理定位和 ASN API。一次 GET 请求即可以 JSON 格式返回某个 IP 地址的国家、地区、城市、坐标、时区、ISP、ASN 和连接类型。无需注册、无需 API 密钥、无需订阅。

它运行在 Shifter 自身代理池所使用的同一套 IP 位置和网络数据库之上,因此当你用 IP Info 检查某个 Shifter 出口 IP 时,你看到的位置正是我们网络所看到的位置。

在浏览器中试用查询你自己的 IP 或任意公共 IPv4 或 IPv6 地址。

完整 API 参考文档每个路由、字段和错误代码,均附有九种语言的示例。

端点

请求	返回内容
`GET http://ip-info.com/json`	发起请求的 IP(你的服务器,或通过代理发送时的代理出口)
`GET http://ip-info.com/json?ip=8.8.8.8`	指定的公共 IPv4 或 IPv6 地址
`GET http://ip-info.com/8.8.8.8/json`	相同的查询,路径形式

HTTP(http://ip-info.com/json)同样可用,且不会被重定向。在网页中请使用 HTTPS,以避免混合内容被阻止。响应允许跨域 GET,因此浏览器代码可以直接调用该 API。

curl --max-time 10 "http://ip-info.com/json?ip=94.204.59.232"

{
  "ip": "94.204.59.232",
  "city": "Motor City",
  "region": "Dubai",
  "region_code": "DU",
  "country": "AE",
  "country_name": "United Arab Emirates",
  "continent": "AS",
  "loc": "25.0459,55.241",
  "latitude": 25.0459,
  "longitude": 55.241,
  "postal": null,
  "timezone": "Asia/Dubai",
  "asn": 15802,
  "as_name": "Emirates Integrated Telecommunications Company PJSC",
  "isp": "Emirates Integrated Telecommunications Company PJSC",
  "org": "Emirates Integrated Telecommunications Company",
  "connection_type": "Corporate",
  "user_type": "business",
  "is_anycast": false
}

实际响应共有 29 个字段;上面的示例展示的是大多数集成会读取的字段。每个字段始终存在,数据库中没有的值会以 null 返回。

检查 Shifter 代理出口

通过你的代理发送不带参数的请求。IP Info 的响应描述的是出口 IP,因此你可以确认所定向的国家、城市或 ASN 是否与实际得到的一致。

curl --max-time 15 \
  --proxy http://p.shifter.io:443 \
  --proxy-user "customer-USERNAME-country-us-city-new_york:PASSWORD" \
  http://ip-info.com/json

import requests

proxy = "http://customer-USERNAME-country-us:PASSWORD@p.shifter.io:443"
r = requests.get(
    "http://ip-info.com/json",
    proxies={"http": proxy, "https": proxy},
    timeout=15,
)
r.raise_for_status()
exit_ip = r.json()
print(exit_ip["ip"], exit_ip["country"], exit_ip["city"], exit_ip["asn"])
assert exit_ip["country"] == "US", f"expected US, got {exit_ip['country']}"

import { HttpsProxyAgent } from "https-proxy-agent";
import fetch from "node-fetch";

const agent = new HttpsProxyAgent(
  "http://customer-USERNAME-country-de:PASSWORD@p.shifter.io:443"
);
const res = await fetch("http://ip-info.com/json", { agent });
const exit = await res.json();
console.log(exit.ip, exit.country, exit.city, `AS${exit.asn}`);

将 country(ISO 3166 两字母代码)与你所请求的国家进行比较,并将 asn(纯数字,不带 AS 前缀)与你所定向的网络进行比较。用户名标志请参见地理定向。

在 AI 代理中使用

IP Info 不需要任何身份验证流程,因此代理可以像调用任何其他 HTTP 端点一样调用它。它发布了机器可读的描述,供代理和工具开发者直接加载:

https://ip-info.com/llms.txt:为 LLM 编写的简短介绍
https://ip-info.com/llms-full.txt:以纯文本形式呈现的完整参考文档
https://ip-info.com/openapi.json:OpenAPI 3.1 契约(security 为空,不需要密钥)

无需 MCP 服务器。如果你的框架接受函数或工具定义,以下定义即可满足需求:

{
  "name": "ip_lookup",
  "description": "Approximate geolocation and network (ASN, ISP) for a public IP address. Omit ip to look up the agent's own network exit.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ip": { "type": "string", "description": "Public IPv4 or IPv6 literal. Leave empty for the caller's exit IP." }
    }
  }
}

当 ip 为空时,将其实现为 GET http://ip-info.com/json,否则实现为 GET http://ip-info.com/json?ip=<URL-encoded ip>。

请将以下规则与该工具一起提供给代理:

不带 ip 的调用描述的是代理自身的服务器或代理出口,并非人类用户。要查询用户的 IP,必须明确将该 IP 提供给代理。
使用 country 进行国家比较,使用 asn 进行网络检查。
将 null 视为未知。切勿自行补全缺失的字段。
位置是近似的,IP Info 不是 VPN 或代理检测工具。

代理的常见用途包括:在浏览代理抓取本地化页面之前确认其代理位于正确的国家,为采集到的数据标注其获取时所在的出口位置,以及用国家和 ASN 信息丰富日志或注册 IP 数据。

错误与重试

错误以 JSON 形式返回,并附带一个固定代码:

{ "error": { "code": "invalid_ip", "message": "Supply a literal IPv4 or IPv6 address." } }

状态码	代码	含义
400	`invalid_ip`	输入格式错误、为私有地址、保留地址或其他非公共地址,或参数存在冲突
404	`ip_not_found`	当前数据库中没有此 IP 的记录
405	`method_not_allowed`	请使用 `GET`
503	`database_unavailable`	临时性问题;请退避后重试
504	`timeout`	临时性问题;请退避后重试

在重试之前先修复 4xx 类输入错误。对于 503、504 及连接错误,请以较短的有限退避时间重试(例如 1、2 和 4 秒),之后放弃并报告失败。

数据与限制

免费,无配额限制。 没有按密钥或按应用的配额限制,也不需要 API 密钥。这是一项共享服务,容量有限:请只发出应用所需的请求,并遵守条款。允许自动化和商业用途。
设计上是近似值。 坐标指向的是一个区域,而非具体地址,并且绝不会识别到某个具体的人。
不是代理或 VPN 检测工具。 connection_type、user_type 和 is_anycast 是数据库的分类结果,并不能证明某个 IP 的实际使用方式。
隐私。 该 API 不保留任何查询历史记录。请参见隐私政策。

如有问题或数据不符:请发送邮件至 hi@shifter.io,并注明相关 IP 和你所预期的位置。

立即开始

代理

APIs

资源