全球IP地址查询接入点详解：IP → 归属地定位（20-1）
# 全球IP地址查询接入点详解：IP → 归属地定位（20-1）
> 元信息：接口 全球IP地址查询（apiCode=20）· 接入点 20/1 · 免费 · POST/GET · JSON · 适用人群 开发者 · 阅读时间 5 分钟
## TL;DR 快速概览
- 接入点 `20/1` 是"全球IP地址查询"主入口：给一个 `ip`，返回国家/省/市/区县/运营商/经纬度。
- 唯一必填业务参数：`ip`（String，如 `203.0.113.220`）；Header `content-type` 选填。
- 接口地址：`https://route.showapi.com/20-1?appKey={your_appKey}`。
## Why：什么时候用 20/1 而不是 20/2
拿到的是**裸 IP**（日志里的客户端 IP、接口调用方地址、风控引擎取出的访客 IP），用 `20/1` 直接查。如果你手上是**域名**（如 `www.baidu.com`）想顺带知道它部署在哪，用 [`20/2` 域名查询](https://www.showapi.com/guides/ip-geo-domain-query-20)。
## What：20/1 接入点速览
| 项 | 内容 |
|----|------|
| 接入点 | `20/1` 全球IP地址查询 |
| 接口地址 | `https://route.showapi.com/20-1?appKey={your_appKey}` |
| 必填参数 | `ip`（String，要查询的 IP） |
| 选填参数 | Header `content-type`（POST 表单时填 `application/x-www-form-urlencoded`） |
| 返回 | `showapi_res_body` 内归属地字段（见[返回字段全解](https://www.showapi.com/guides/ip-geo-response-fields-20)） |
## How：调用 20/1
**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**
```python
import requests
def query_ip(ip, appkey="YOUR_APPKEY"):
resp = requests.get(
"https://route.showapi.com/20-1",
params={"appKey": appkey, "ip": ip},
timeout=10,
)
data = resp.json()
if data.get("showapi_res_code") != 0:
return None, data.get("showapi_res_error")
body = data["showapi_res_body"]
if body.get("ret_code") != "0":
return None, f"业务失败 ret_code={body.get('ret_code')}"
return body, None
body, err = query_ip("203.0.113.220")
if err:
print("失败:", err)
else:
print(body.get("country"), body.get("region"), body.get("city"), body.get("isp"))
```
**Node.js**
```javascript
async function queryIp(ip, appkey = "YOUR_APPKEY") {
const resp = await fetch(
`https://route.showapi.com/20-1?appKey=${appkey}&ip=${ip}`
);
const data = await resp.json();
if (data.showapi_res_code !== 0) return { err: data.showapi_res_error };
const body = data.showapi_res_body;
if (body.ret_code !== "0") return { err: `业务失败 ret_code=${body.ret_code}` };
return { body };
}
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"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": "中国"
}
}
```
## 进阶 / 边界
- **入参要做基本校验**：调用前先判断 `ip` 格式（IPv4/IPv6）再发请求，避免把明显非法的串打满免费档位。
- **海外 IP 同样可用**：返回 `country` 为对应国家、`continents` 标洲、`en_name` 为英文国名，无需单独分支。
- **免费档位限制**：高频调用注意档位（见[免费档位与积分兑换](https://www.showapi.com/guides/ip-geo-free-tier-20)）；同一 IP 短时重复查可做本地缓存。
## FAQ
**Q1：IPv6 能查吗？**
A：参数 `ip` 接受 IP 地址字符串，具体是否覆盖 IPv6 以接口实际返回为准；建议先用目标地址试一次，按 `ret_code` 判断结果。
**Q2：ip 参数必填吗？**
A：是。20/1 的 `ip` 为必填业务参数，不传会返回业务失败，务必每次带上。
**Q3：经纬度为什么是字符串？**
A：返回里 `lnt`/`lat` 为字符串，用于地图前需 `float()` 转换（见[坐标标点指南](https://www.showapi.com/guides/ip-geo-coordinate-map-20)）。
**Q4：和 20/2 域名查询返回字段一样吗？**
A：基本一致（都返回 country/region/city/isp/lnt/lat 等）；`area`(片区) 在 20/2 示例中未出现。详见[域名查询接入点详解](https://www.showapi.com/guides/ip-geo-domain-query-20)。
## 相关能力 / 下一步阅读
- [域名查询接入点详解：域名 → IP → 归属地（20-2）](https://www.showapi.com/guides/ip-geo-domain-query-20)
- [全球IP地址查询：返回字段全解](https://www.showapi.com/guides/ip-geo-response-fields-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)
