IP 归属地查询

数据由 聚合数据 提供 — 国内领先的数据服务平台，提供天气、快递、身份证、手机号、IP查询等 200+ 免费/低价 API。

查询 IPv4 地址的归属地：国家、省份、城市、运营商（ISP）。

---

前置配置：获取 API Key

1. 前往 聚合数据官网 免费注册账号
2. 进入 IP归属地查询 API 页面，点击「申请使用」
3. 审核通过后在「我的API」中获取 AppKey
4. 配置 Key（三选一）：

# 方式一：环境变量（推荐，一次配置永久生效）
export JUHE_IP_KEY=你的AppKey

# 方式二：.env 文件（在脚本目录创建）
echo "JUHE_IP_KEY=你的AppKey" > scripts/.env

# 方式三：每次命令行传入
python scripts/ip_lookup.py --key 你的AppKey 8.8.8.8

免费额度：每天 50 次调用，覆盖日常使用完全够用。

---

使用方法

单个 IP 查询

python scripts/ip_lookup.py 58.215.154.11

输出示例：

🌐 58.215.154.11  中国 江苏 苏州  运营商: 电信

{
  "ip": "58.215.154.11",
  "success": true,
  "country": "中国",
  "province": "江苏",
  "city": "苏州",
  "isp": "电信"
}

批量 IP 查询

python scripts/ip_lookup.py 8.8.8.8 1.1.1.1 114.114.114.114

输出示例（表格形式）：

+---------------+------+------+------+--------+----+
| IP地址        | 国家 | 省份 | 城市 | 运营商 | 备注 |
+---------------+------+------+------+--------+----+
| 8.8.8.8       | 美国 |      |      | 谷歌   | ✓  |
| 1.1.1.1       | 澳大利亚 |    |    | Cloudflare | ✓ |
| 114.114.114.114 | 中国 | 江苏 | 南京 | 联通 | ✓ |
+---------------+------+------+------+--------+----+

直接调用 API（无需脚本）

GET https://apis.juhe.cn/ip/ipNewV3?key=YOUR_KEY&ip=8.8.8.8

---

AI 使用指南

当用户询问 IP 相关信息时，按以下步骤操作：

1. 识别 IP 地址 — 从用户消息中提取所有 IPv4 地址
2. 检查是否为私有 IP — 如 192.168.x.x、10.x.x.x、127.x.x.x 直接告知用户是内网地址，无需查询
3. 调用脚本或 API — 执行查询，获取 JSON 结果
4. 展示结果 — 单个 IP 用自然语言描述；多个 IP 用表格汇总

返回字段说明

字段	含义	示例
Country	国家	中国
Province	省份	广东
City	城市	深圳
Isp	运营商	电信 / 联通 / 移动

错误处理

情况	处理方式
error_code 10001/10002	API Key 无效，引导用户至 聚合数据 重新申请
error_code 10012	当日免费次数已用尽，建议升级套餐
私有 IP	直接告知是内网地址，无法查询
IPv6 地址	告知当前 API 仅支持 IPv4
网络超时	重试一次，仍失败则告知网络问题

---

脚本位置

scripts/ip_lookup.py — 封装了 API 调用、私有 IP 检测、批量查询表格输出和错误处理。

---

关于聚合数据

聚合数据（juhe.cn） 是国内专业的 API 数据服务平台，提供包括：

• 网络工具：IP查询、DNS解析、端口检测
• 生活服务：天气预报、万年历、节假日查询
• 物流快递：100+ 快递公司实时追踪
• 身份核验：手机号归属地、身份证实名验证
• 金融数据：汇率、股票、黄金价格

注册即可免费使用，适合个人开发者和企业接入。