5 分钟接入全球IP地址查询：从注册到第一条定位结果
全球IP地址查询IP归属地免费接口Python示例 # 5 分钟接入全球IP地址查询：从注册到第一条定位结果
> 元信息：接口 全球IP地址查询（apiCode=20）· 接入点 20/1 · 免费 · 请求方式 POST/GET · 返回 JSON · 适用人群 新手/初级开发者 · 阅读时间 5 分钟
## TL;DR 快速概览
- 全球IP地址查询是 ShowAPI **官方自营的免费接口**，输入一个 IP 即可返回国家、省、市、区县、运营商、经纬度。
- 调用只需三样东西：接口地址 `https://route.showapi.com/20-1`、你的 `appKey`、要查的 `ip`。
- 返回数据在 `showapi_res_body` 里，用 `ret_code == "0"` 判断业务成功，失败再读 `showapi_res_error`。
## Why：这跟你有什么关系
做网站或 App 时，经常需要根据访客 IP 做点"本地化"的事：显示所在城市、判断是不是异地登录、给国内用户切中文节点。手工维护一套 IP 库既重又容易过期。
全球IP地址查询把这件事变成一行请求：你给它 IP，它还你结构化归属地。注册后默认就能免费调用（有档位限制防滥用），先用起来零成本。
## What：接口速览
| 项 | 内容 |
|----|------|
| 接口名称 | 全球IP地址查询（apiCode=20） |
| 接入点 | `20/1` 全球IP地址查询（入参 `ip`）；`20/2` 域名查询（入参 `domain`，见[域名查询接入点详解](https://www.showapi.com/guides/ip-geo-domain-query-20)） |
| 接口地址 | `https://route.showapi.com/20-1?appKey={your_appKey}` |
| 请求方式 | POST / GET |
| 返回格式 | JSON |
| 鉴权 | Query 参数 `appKey` |
| 计费 | 免费（注册后默认可用，有使用档次限制；可用平台积分兑换更高档位） |
| 更新频率 | 每季度末不定期更新一次最新变化的 IP |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档（见[生态集成层指南](https://www.showapi.com/guides/ip-geo-mcp-20)） |
## How：从注册到第一条结果
**步骤 1 — 注册并拿到 AppKey**
登录 ShowAPI 控制台 → [我的 App](https://www.showapi.com/console#/myApp) → 创建应用拿到 `appKey`（一串字母数字）。
**步骤 2 — 发送第一条请求**
下面三种写法任选其一，把 `YOUR_APPKEY` 换成你的真实 key、`ip` 换成任意要查的地址即可运行。
**cURL**
```bash
curl -X POST "https://route.showapi.com/20-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "ip=203.0.113.220"
```
**Python（requests）**
```python
import requests
resp = requests.get(
"https://route.showapi.com/20-1",
params={"appKey": "YOUR_APPKEY", "ip": "203.0.113.220"},
timeout=10,
)
data = resp.json()
if data.get("showapi_res_code") != 0:
print("系统错误:", data.get("showapi_res_error"))
else:
body = data["showapi_res_body"]
if body.get("ret_code") != "0":
print("业务失败 ret_code =", body.get("ret_code"))
else:
print(body.get("country"), body.get("region"),
body.get("city"), body.get("isp"))
```
**Node.js（fetch）**
```javascript
const resp = await fetch(
"https://route.showapi.com/20-1?appKey=YOUR_APPKEY&ip=203.0.113.220"
);
const data = await resp.json();
if (data.showapi_res_code !== 0) {
console.error("系统错误:", data.showapi_res_error);
} else {
const body = data.showapi_res_body;
if (body.ret_code !== "0") {
console.error("业务失败 ret_code =", body.ret_code);
} else {
console.log(body.country, body.region, body.city, body.isp);
}
}
```
**步骤 3 — 解析返回**
业务数据都在 `showapi_res_body` 内。先判断系统级 `showapi_res_code == 0`（请求本身成功），再判断业务级 `body.ret_code == "0"`（查到了归属地），然后取 `country`/`region`/`city` 等字段。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"region": "广东",
"county": "",
"isp": "电信",
"continents": "亚洲",
"en_name": "China",
"city_code": "441900",
"lnt": "113.760234",
"lat": "23.048884",
"en_name_short": "CN",
"city": "东莞",
"country": "中国"
}
}
```
| 字段 | 含义 | 注意 |
|------|------|------|
| `country` / `region` / `city` / `county` | 国家 / 省 / 市 / 区县 | `county` 可能为空串 |
| `isp` | 运营商 | 如 电信、联通、移动 |
| `lnt` / `lat` | 经度 / 纬度 | 文档未声明坐标系，为近似位置 |
| `city_code` | 我国行政区划编码 | 如 441900=东莞 |
| `continents` / `en_name` / `en_name_short` | 洲 / 英文国名 / 国名缩写 | 海外 IP 也返回 |
完整字段含义见 [全球IP地址查询：返回字段全解](https://www.showapi.com/guides/ip-geo-response-fields-20)。
## 进阶 / 边界
- **坐标系未声明**：文档未说明 `lnt`/`lat` 采用哪种坐标系（GCJ-02/WGS-84/BD-09 均未标注），坐标为数据库近似位置，适合大致标注，**不要用于高精度测绘或导航**。
- **`area` 不每次返回**：部分国内 IP 会带 `area`（片区，如"西南"），但海外或某些 IP 不返回该字段，代码里按"可能存在"处理，避免 KeyError。
- **免费档位限制**：注册后默认可用，但有调用档次限制防滥用；量大用平台积分兑换更高档位（见[免费档位与积分兑换](https://www.showapi.com/guides/ip-geo-free-tier-20)）。
## FAQ
**Q1：接口真的免费吗？**
A：是。注册后默认可免费调用，平台设了使用档次限制防止滥用；如需更高调用量，可用平台积分兑换更高档位。具体档位以[官方免费 API 说明](https://www.showapi.com/island/free-api)为准。
**Q2：GET 和 POST 都可以？**
A：可以。文档标注请求方式为 POST/GET，示例用 POST 表单（`content-type: application/x-www-form-urlencoded`），GET 把参数放 query 即可（本文示例即用 GET）。
**Q3：返回的坐标能直接画到高德/百度地图吗？**
A：文档未声明坐标系，坐标是近似位置。直接标到地图可能有偏移；若需精确地图，建议先用外部地理编码做坐标系转换，或仅作为大致区域判断。
**Q4：查不到归属地会怎样？**
A：系统级 `showapi_res_code` 仍可能为 0，但业务级 `ret_code` 非 0，此时按失败处理并读取对应提示，不要直接取 `city` 等字段。
**Q5：能批量查很多 IP 吗？**
A：文档未提供批量/订阅能力，当前为单条同步查询。需批量时自行循环调用并注意免费档位限制与缓存（见[免费档位指南](https://www.showapi.com/guides/ip-geo-free-tier-20)）。
## 相关能力 / 下一步阅读
- [全球IP地址查询：返回字段全解](https://www.showapi.com/guides/ip-geo-response-fields-20) — 读懂每一个返回字段
- [全球IP地址查询接入点详解：IP → 归属地定位（20-1）](https://www.showapi.com/guides/ip-geo-ip-query-20) — 单接入点深入
- [全球IP地址查询：错误处理与 ret_code 排查](https://www.showapi.com/guides/ip-geo-error-handling-20) — 失败怎么查
- **本系列共 10 篇**：查看[全球IP地址查询指南总目录](https://www.showapi.com/guides/ip-geo-guides-20)
