全球IP地址查询：返回字段全解（area/country/city/lnt/lat 一文读懂）
# 全球IP地址查询：返回字段全解（area/country/city/lnt/lat 一文读懂）
> 元信息：接口 全球IP地址查询（apiCode=20）· 接入点 20/1、20/2 · 免费 · 返回 JSON · 适用人群 开发者/数据分析 · 阅读时间 6 分钟
## TL;DR 快速概览
- 所有业务字段都在 `showapi_res_body` 内；系统级字段（`showapi_res_code` 等）在外层。
- 核心字段：`country`(国家)、`region`(省)、`city`(市)、`county`(区县)、`isp`(运营商)、`lnt`/`lat`(经纬度)、`city_code`(行政区划编码)。
- 文档返回体表格**漏列**了 `continents`/`en_name`/`en_name_short`，实际返回里会有；`area`(片区)仅部分国内 IP 返回。
## Why：为什么要把字段读透
字段读错 = 线上 bug。比如把 `lnt` 当纬度、把 `county` 空串当异常、以为每个 IP 都有 `area`……这些都会让前端显示错位或报警误发。本文把实测返回结构一次讲清，并标注文档与示例不一致的地方。
## What：返回结构速览
系统级（外层）与业务级（`showapi_res_body`）两层：
| 层级 | 字段 | 说明 |
|------|------|------|
| 系统级 | `showapi_res_code` | 0 成功，非 0 系统错误 |
| 系统级 | `showapi_res_error` | 系统错误信息 |
| 系统级 | `showapi_res_id` | 本次请求 id |
| 业务级 | `showapi_res_body` | 归属地数据对象，见下 |
`showapi_res_body` 字段（含文档表未列、但示例实际返回的字段）：
| 字段 | 类型 | 示例 | 说明 | 是否每次返回 |
|------|------|------|------|------|
| `country` | String | 中国 | 国家 | 是 |
| `region` | String | 广东 | 省级 | 是 |
| `city` | String | 东莞 | 市级 | 是 |
| `county` | String | (空串) | 区县级/乡镇级 | 是（可为空串） |
| `isp` | String | 电信 | 运营商 | 是 |
| `area` | String | 西南 | 片区 | 否（部分国内 IP 才有） |
| `city_code` | String | 441900 | 我国行政区划编码 | 是 |
| `lnt` | String | 113.760234 | 经度 | 是 |
| `lat` | String | 23.048884 | 纬度 | 是 |
| `continents` | String | 亚洲 | 所在洲 | 是（文档表未列） |
| `en_name` | String | China | 英文国家名 | 是（文档表未列） |
| `en_name_short` | String | CN | 英文国名缩写 | 是（文档表未列） |
| `ret_code` | String | 0 | 0 成功，其他失败 | 是 |
## How：解析时怎么写才稳
```python
body = data["showapi_res_body"]
# 1) 先判断业务成功
if body.get("ret_code") != "0":
print("查询失败:", body.get("ret_code"))
# 2) 字段按"可能缺失"取，避免 KeyError
country = body.get("country", "")
region = body.get("region", "")
city = body.get("city", "")
isp = body.get("isp", "")
area = body.get("area") # 可能为 None
lng = body.get("lnt") # 经度
lat = body.get("lat") # 纬度
code = body.get("city_code", "")
# 3) 海外 IP 同样有 continents/en_name/en_name_short
print(area, country, region, city, isp, lng, lat, code)
```
## 返回示例（20/1，含文档表外字段）
```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": "中国"
}
}
```
> 注：文档返回体表格还列了 `area`(片区，示例"西南")，但上例未出现，说明 `area` 仅部分 IP 返回；`county` 文档在 20/1 标"县级"、在 20/2 标"乡镇"，属同一字段的两种描述，统一按"区县级"理解即可。
## 进阶 / 边界
- **坐标系未声明**：`lnt`/`lat` 文档未说明采用 GCJ-02 / WGS-84 / BD-09 哪一套，是数据库近似坐标。画地图前请先做坐标系确认或转换（见[如何用 lnt/lat 在地图上标点](https://www.showapi.com/guides/ip-geo-coordinate-map-20)）。
- **经纬度是字符串**：返回里 `lnt`/`lat` 是字符串类型，画图前需 `float()` 转换。
- **`county` 空串常态**：大量 IP 精确到市级即止，`county` 为空串，不要当错误。
## FAQ
**Q1：为什么有时候没有 `area` 字段？**
A：`area`(片区) 仅部分国内 IP 返回，海外或某些 IP 不返回。代码用 `body.get("area")` 容错，不要假设它一定存在。
**Q2：`lnt` 和 `lat` 哪个是经度？**
A：`lnt` 是经度（longitude），`lat` 是纬度（latitude）。二者都是字符串，需转 float 再用于地图。
**Q3：文档表格没写的 continents/en_name 是什么？**
A：它们确实在真实返回里（示例 JSON 已包含）：`continents` 是所在洲、`en_name` 是英文国名、`en_name_short` 是国名缩写（如 CN）。这是文档返回体表格的遗漏，实际调用会返回。
**Q4：返回的经纬度准吗？**
A：文档未声明坐标系，坐标为 IP 库近似位置，适合大致区域判断与标注，不适合高精度测绘或导航。
**Q5：`city_code` 是什么编码？**
A：我国行政区划编码（如 441900=东莞、110100=北京），可与国标行政区划表对照做区县聚合。
## 相关能力 / 下一步阅读
- [5 分钟接入全球IP地址查询](https://www.showapi.com/guides/ip-geo-quickstart-20) — 先跑通再回来读字段
- [全球IP地址查询：如何用 lnt/lat 在地图上标点](https://www.showapi.com/guides/ip-geo-coordinate-map-20) — 坐标实战
- [全球IP地址查询接入点详解：IP → 归属地定位（20-1）](https://www.showapi.com/guides/ip-geo-ip-query-20) — 单接入点深入
- **本系列共 10 篇**：查看[全球IP地址查询指南总目录](https://www.showapi.com/guides/ip-geo-guides-20)
