在当今的软件开发中，集成第三方API来快速实现功能已成为一种高效的方式。本文详细介绍一个由"接口盒子"提供的免费手机号归属地查询API。该接口数据准确，调用简单，适合集成到各类网站、小程序或后台管理系统中。
一、接口简介
这个API的主要功能是查询指定手机号码的详细信息，包括归属省份、城市、运营商、区号、邮编等。对于需要验证手机号有效性、进行地域化营销或用户信息补全的应用场景来说，是一个非常实用的工具。
-
接口地址 ：
https://cn.apihz.cn/api/ip/shouji.php -
请求方式 ：支持 GET 和 POST 两种方式。
二、接口申请与认证
在使用此接口前，您需要拥有一个"接口盒子"平台的账号。
-
注册账号：访问 https://www.apihz.cn并完成注册登录。
-
获取ID和KEY ：登录用户中心后，您可以找到属于您自己的唯一 用户ID（id） 和 通讯秘钥（key）。
重要提示 ：官方文档中提供的示例ID和KEY（如
id=88888888&key=88888888）为公共测试凭证，所有用户共享调用频次限制，可能会因频繁调用而失败。为保证服务稳定性，强烈建议使用您个人账号的独有ID和KEY。
三、请求参数说明
调用接口时，必须传递以下三个参数：
| 参数名称 | 参数 | 是否必填 | 说明 |
|---|---|---|---|
| 用户ID | id |
是 | 您在用户中心的数字ID。 |
| 用户KEY | key |
是 | 用户中心的通讯秘钥，用于身份验证。 |
| 手机号 | phone |
是 | 需要查询的11位手机号码。 |
四、返回参数说明
接口返回标准JSON格式的数据。
-
成功响应（查询成功）:
json
json
复制
{ "code": 200, "haoduan": "1321993", "shengfen": "四川", "chengshi": "绵阳", "fuwushang": "中国联通", "quhao": "0816", "qhdm": "510700", "youbian": "621000" } -
错误响应（如秘钥错误）:
json
json
复制
{ "code": 400, "msg": "通讯秘钥错误。" }
各返回字段含义如下：
| 字段名（中文） | 字段（英文） | 说明 |
|---|---|---|
| 状态码 | code |
200代表成功，400代表失败。 |
| 信息提示 | msg |
当code为400时，此处返回错误原因。 |
| 号段 | haoduan |
手机号码的前7位号段。 |
| 省份 | shengfen |
手机号归属的省份。 |
| 城市 | chengshi |
手机号归属的城市。 |
| 运营商 | fuwushang |
手机号所属运营商，如中国移动、联通、电信。 |
| 区号 | quhao |
归属地的长途电话区号。 |
| 区划代码 | qhdm |
归属地的行政区划代码。 |
| 邮编 | youbian |
归属地的邮政编码。 |
五、调用示例
以下是使用不同编程语言调用该API的详细示例。
GET请求示例URL：
https://cn.apihz.cn/api/ip/shouji.php?id=您的用户ID&key=您的通讯秘钥&phone=13219931963
1. PHP调用示例
PHP可以使用file_get_contents或cURL库。这里展示更灵活的cURL方法。
php
php
复制
<?php
// 配置您的API凭证和要查询的手机号
$id = "您的用户ID"; // 替换为您的真实ID
$key = "您的通讯秘钥"; // 替换为您的真实KEY
$phone = "13219931963"; // 要查询的手机号
// 拼接请求URL
$api_url = "https://cn.apihz.cn/api/ip/shouji.php?id=" . $id . "&key=" . $key . "&phone=" . $phone;
// 初始化cURL会话
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 将响应结果返回，而不是直接输出
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 跳过SSL证书验证（仅测试环境建议，生产环境应设为true）
// 执行请求并获取返回的JSON数据
$response = curl_exec($ch);
// 检查请求是否成功
if (curl_error($ch)) {
die('cURL请求发生错误: ' . curl_error($ch));
}
// 关闭cURL资源
curl_close($ch);
// 将JSON字符串解析为PHP数组或对象
$data = json_decode($response, true); // 设置为true解析为关联数组
// 处理返回数据
if ($data['code'] == 200) {
// 查询成功，打印结果
echo "手机号: " . $phone . "<br>";
echo "归属地: " . $data['shengfen'] . "省 " . $data['chengshi'] . "市<br>";
echo "运营商: " . $data['fuwushang'] . "<br>";
echo "区号: " . $data['quhao'] . "<br>";
echo "邮编: " . $data['youbian'];
} else {
// 查询失败，打印错误信息
echo "查询失败，错误信息: " . $data['msg'];
}
?>2. Python调用示例
Python可以使用内置的urllib库或更流行的第三方requests库。这里使用requests库，需要先安装：pip install requests。
python
python
下载
复制
import requests
import json
# 配置您的API凭证和要查询的手机号
id = "您的用户ID" # 替换为您的真实ID
key = "您的通讯秘钥" # 替换为您的真实KEY
phone = "13219931963" # 要查询的手机号
# 接口地址
api_url = "https://cn.apihz.cn/api/ip/shouji.php"
# 构建请求参数
params = {
"id": id,
"key": key,
"phone": phone
}
try:
# 发送GET请求
response = requests.get(api_url, params=params)
# 确保请求成功（状态码为200）
response.raise_for_status()
# 解析返回的JSON数据
data = response.json()
# 处理返回数据
if data['code'] == 200:
# 查询成功，打印结果
print(f"手机号: {phone}")
print(f"归属地: {data['shengfen']}省 {data['chengshi']}市")
print(f"运营商: {data['fuwushang']}")
print(f"区号: {data['quhao']}")
print(f"邮编: {data['youbian']}")
else:
# 查询失败，打印错误信息
print(f"查询失败，错误信息: {data['msg']}")
except requests.exceptions.RequestException as e:
# 处理网络请求异常
print(f"网络请求出错: {e}")
except json.JSONDecodeError as e:
# 处理JSON解析异常
print(f"解析返回数据出错: {e}")六、重要注意事项
-
频率限制 ：使用个人ID和KEY享有独立的每分钟调用频次限制。公共KEY的频次限制很低，极易触发。每日调用总次数无上限。
-
安全性 ：请妥善保管您的
key（通讯秘钥），不要将其泄露或直接硬编码在客户端代码（如网页前端、小程序）中，以防被他人盗用。最佳实践是在您的服务器端进行API调用。 -
错误排查 ：如果调用失败，首先检查
code和msg字段。常见错误是id或key填写错误、手机号格式不正确等。 -
数据更新：手机号段和归属地信息会随时间变化，该接口的数据源会定期更新，但可能存在微小延迟。
总结
"接口盒子"提供的这个免费手机号归属地查询API，凭借其清晰的文档、稳定的服务和免费的特性，是开发者一个非常不错的选择。通过本文提供的详细说明和代码示例，您可以快速地将此功能集成到您的项目中。