5 分钟接入手机归属地查询：从注册到第一条返回
手机归属地查询API快速接入Python示例免费接口 # 5 分钟接入手机归属地查询：从注册到第一条返回
> **接口**：手机归属地查询 `6-1` ｜ **是否免费**：是（注册默认可免费调用，有使用档次限制）｜ **请求方式**：POST / GET ｜ **返回格式**：JSON ｜ **适用人群**：新注册用户、初级开发者 ｜ **阅读时间**：约 5 分钟
## TL;DR
- 这是一个**免费、单参数**接口：你只需要传一个手机号 `num`，就能拿回省、市、运营商、邮编、区号。
- 三步跑通：**注册拿 AppKey → 发请求 → 解析 `showapi_res_body`**。代码替换 `YOUR_APPKEY` 即可运行。
- **失败时（如号码格式错）不扣点数**——放心试，先在校验客户端格式再调用更省心。
## Why：这跟我有什么关系？
无论是做用户注册、来电弹屏、订单风控，还是单纯想给通讯录加个归属地标签，你都会遇到同一个需求：**拿到一个手机号，想知道它属于哪个省、哪个市、哪家运营商。**
自己维护号段库？三网号段每半年都在变，广电（192 段）等新运营商一出来就得跟着更新，维护成本高、还容易错。手机归属地查询接口把这件事变成了**一次 HTTP 调用**：你把号码发过去，它把结构化结果还给你，更新频率是半年一次官方维护，你不用管底层数据。
对初学者最友好的一点是——它**只要求一个必填参数 `num`**，没有复杂的鉴权头、没有多层嵌套的请求体。本文的目标就是让你在 5 分钟内拿到第一条真实返回。
## What：接口速览
| 项目 | 内容 |
|------|------|
| 接口名称 | 手机归属地查询 |
| 接入点 | `6-1`（本接口仅 1 个接入点，同步请求-响应） |
| 接口地址 | `https://route.showapi.com/6-1?appKey={your_appKey}` |
| 请求方式 | POST 或 GET |
| 鉴权方式 | Query 参数 `appKey` |
| 必填参数 | `num`（手机号，字符串） |
| 返回格式 | JSON，业务数据封装在 `showapi_res_body` 内 |
| 计费 | 免费服务（注册默认可免费调用，设使用档次限制）；**失败不扣点数** |
| 更新频率 | 半年更新一次新出现的号段归属地信息 |
| 集成能力 | MCP 服务、OpenAPI 3.0（YAML/JSON） |
| 注意 | **不支持携号转网查询** |
## How：从注册到第一条返回
### 步骤 1 · 注册并获取 AppKey
1. 打开 [易源官网](https://www.showapi.com) 注册账号（本接口为免费服务，注册后默认可调用）。
2. 进入 [AppKey 管理页](https://www.showapi.com/console#/myApp)，复制你的 AppKey。
3. 把下面代码里的 `YOUR_APPKEY` 替换成它。
### 步骤 2 · 发起第一次调用（以 `18908711111` 为例）
下面三种写法**替换占位符即可运行**，都带超时（10s）和 `ret_code` 错误判断。
**Python（requests）**
```python
import requests
API_URL = "https://route.showapi.com/6-1"
APP_KEY = "YOUR_APPKEY" # 替换为你的真实 AppKey
PHONE = "18908711111" # 要查询的手机号
resp = requests.get(
API_URL,
params={"appKey": APP_KEY, "num": PHONE},
timeout=10,
)
data = resp.json()
body = data.get("showapi_res_body", {})
if body.get("ret_code") == 0:
print("省：", body.get("prov"))
print("市：", body.get("city"))
print("运营商：", body.get("name"))
print("号段：", body.get("num"))
print("区号：", body.get("areaCode"))
print("邮编：", body.get("postCode"))
else:
# 失败时不会扣点数，可安心重试或提示用户
print("查询失败，错误码：", body.get("ret_code"), "（失败不扣点数）")
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/6-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "num=18908711111"
```
**Node.js（fetch，Node 18+ 原生支持）**
```javascript
const APP_KEY = "YOUR_APPKEY"; // 替换为你的真实 AppKey
const PHONE = "18908711111";
const resp = await fetch(
`https://route.showapi.com/6-1?appKey=${APP_KEY}`,
{
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ num: PHONE }),
signal: AbortSignal.timeout(10000), // 超时 10s
}
);
const data = await resp.json();
const body = data.showapi_res_body || {};
if (body.ret_code === 0) {
console.log("省：", body.prov, "市：", body.city, "运营商：", body.name);
} else {
console.log("查询失败，错误码：", body.ret_code, "（失败不扣点数）");
}
```
### 步骤 3 · 解析 `showapi_res_body`
返回最外层是系统级字段（`showapi_res_code` / `showapi_res_error` / `showapi_res_id`），**真正的业务数据全部在 `showapi_res_body` 对象里**。上面的代码都是先取 `showapi_res_body`，再读 `prov` / `city` / `name` 等字段——这是本接口固定的封装结构，务必记住"先剥一层"。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"num": 1890871,
"prov": "云南",
"ret_code": 0,
"areaCode": "0871",
"name": "电信",
"cityCode": "530100",
"postCode": "650000",
"provCode": "530000",
"type": 2,
"city": "昆明"
}
}
```
| 字段 | 含义 | 本例值 |
|------|------|--------|
| `prov` | 省 | 云南 |
| `city` | 市 | 昆明 |
| `name` | 运营商名称 | 电信 |
| `num` | 号段（前 7 位） | 1890871 |
| `type` | 运营商枚举（1移动/2电信/3联通/4广电/-1未知） | 2 |
| `areaCode` | 城市区号 | 0871 |
| `postCode` | 邮政编码 | 650000 |
| `provCode` | 省别编码（本省身份证前几位） | 530000 |
| `cityCode` | 城市编码（本城市身份证前几位） | 530100 |
| `ret_code` | 业务状态码，0 成功，其他失败 | 0 |
> 字段的完整含义、类型与示例见 [《手机归属地返回字段全解》](https://www.showapi.com/guides/phone-attribution-response-fields-6)。
## 进阶 / 边界
- **失败不扣点数**：`ret_code != 0`（如 `-2` 非 11 位、-4 格式错）时不消耗调用额度，可放心做格式校验后再发请求。
- **不支持携号转网**：号码携号转网后，返回结果仍按原号段归属，不会变。这是官方明确的能力边界，不是 bug。
- **免费档位限制**：免费调用有使用档次上限，批量场景请先做客户端校验、再考虑本地缓存（详见系列缓存篇）。
## FAQ
**Q1：一定要用 POST 吗？GET 行不行？**
两种都支持。示例里 Python 用 GET、cURL/Node 用 POST，效果一致，按你项目习惯选。
**Q2：返回的 `city` 是"市"还是"区/县"？**
文档定义为"市"。具体粒度以接口返回为准，不要假设它到区县级。
**Q3：`num` 字段返回的是完整手机号吗？**
不是。`num` 返回的是**号段（前 7 位）**，如 `1890871`，不是完整号码，注意别把它当成用户输入的原号。
**Q4：调用失败会扣我的点数吗？**
不会。文档明确"失败时不扣点数"，`ret_code` 非 0 即失败且不扣费。
**Q5：没有经纬度字段，能在地图上标点吗？**
本接口不返回经纬度。要做地图可视化，需用 `prov`/`city` 配合外部地理编码服务转换坐标，本接口只负责"归属地文字"。
**Q6：广电的号码能查到吗？**
能。`type=4` 即广电（192 号段）。查不到时 `type` 返回 `-1`（未知）。
## 相关能力 / 下一步阅读
- [《手机归属地返回字段全解：prov/city/type/postCode 一文读懂》](https://www.showapi.com/guides/phone-attribution-response-fields-6) —— 每个字段的类型、取值与坑位
- [《错误码排查：-2 非11位 / -3 非数字 / -4 格式 / -5-6 找不到》](https://www.showapi.com/guides/phone-attribution-error-codes-6) —— 4 类错误对照与排查路径
- **本系列共 12 篇**：查看[手机归属地查询 · 官方指南总目录](https://www.showapi.com/guides/phone-attribution-guides-6)
