本接口提供IP地址/域名的归属地查询服务，支持IPv4地址查询、域名自动解析后查询，返回包含国家、省份、城市、运营商等详细信息的JSON格式数据。
| 项目 | 说明 |
|---|---|
| 接口地址 | http://ping.4759.cn/api/ip.php |
| 请求方式 | GET |
| 返回格式 | JSON（UTF-8编码） |
| 跨域支持 | 支持（允许所有域名调用） |
| 调用限制 | 单授权码最多50次/分钟（防止恶意刷接口） |
| 授权要求 | 必须携带有效的key参数（授权码），在线测试已内置测试码，无需手动输入 |
| 字段特性 | 返回字段已标准化，空值/未知字段自动隐藏；电话区号仅展示接口原生返回值，无则自动过滤（无预设映射） |
| 参数名 | 是否必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|
| key | 是 | 字符串 | API授权码（联系管理员获取；在线测试已内置测试码，无需手动输入） | 内置测试授权码 |
| ip | 是 | 字符串 | 要查询的IPv4地址或域名（域名会自动解析为IP后查询） | 123.161.169.10 / www.baidu.com |
| format | 否 | 字符串 | 返回格式，仅支持json（默认值），预留扩展其他格式 |
json |
| 层级 | 参数名 | 类型 | 说明 |
|---|---|---|---|
| 顶级 | code | 整数 | 状态码（200=成功，400=参数错误，401=未授权，403=授权封禁，404=域名解析失败，429=调用超限，500=接口异常） |
| 顶级 | msg | 字符串 | 状态描述（成功/失败原因） |
| 顶级 | data | 对象 | 查询结果数据（仅code=200时有值，空值/未知字段会自动过滤） |
| data层 | input | 字符串 | 原始输入的IP/域名 |
| data层 | ip | 字符串 | 最终查询的IPv4地址（域名会解析为IP） |
| data层 | ip_type | 字符串 | IP类型（IPv4/IPv6） |
| data层 | domain_parse_msg | 字符串 | 域名解析提示（非域名查询时为空） |
| data层 | country | 字符串 | 国家/地区（标准化返回） |
| data层 | province | 字符串 | 省份/直辖市（已自动补全"省/市"后缀，如"河南省"/"北京市"） |
| data层 | city | 字符串 | 城市（已自动补全"市"后缀，如"驻马店市"） |
| data层 | district | 字符串 | 区县（已自动补全"区/县"后缀，如"驿城区"） |
| data层 | isp | 字符串 | 网络运营商（标准化返回，如"中国电信"/"中国移动"/"中国联通"） |
| data层 | big_area | 字符串 | 大区（如华北、华东、华南等） |
| data层 | continent | 字符串 | IP所属洲（如亚洲） |
| data层 | zipcode字符串 | 邮政编码 | |
| data层 | country_code | 字符串 | 国家代码（如CN） |
| data层 | lng | 字符串 | 经度 |
| data层 | lat | 字符串 | 纬度 |
| data层 | call_stats | 对象 | 调用统计信息（包含当前授权码剩余调用次数、频率限制等） |
| data.call_stats | used_count | 整数 | 当前分钟已调用次数 |
| data.call_stats | limit_count | 整数 | 每分钟调用限制次数（50次） |
| data.call_stats | reset_time | 字符串 | 调用次数重置时间（分钟级别） |
| 状态码 | 说明 | 解决方案 |
|---|---|---|
| 200 | 查询成功 | 正常解析data字段即可（空值字段会自动过滤） |
| 400 | 参数错误 | 检查是否传入ip参数，参数是否为空 |
| 401 | 未授权 | 在线测试已内置测试授权码，无需手动输入；自定义调用需添加有效的key参数 |
| 403 | 授权码已封禁 | 联系管理员解封或更换授权码 |
| 404 | 域名解析失败 | 确认域名是否正确，或该域名是否有IPv4解析记录 |
| 429 | 调用频率超限 | 等待1小时后再调用，或联系接口提供方调整限制 |
| 500 | 数据源接口异常 | 稍等片刻重试，若持续失败可联系接口提供方排查 |
示例1：带授权码的正常调用
请求地址：http://ping.4759.cn/api/ip.php?key=内置测试授权码&ip=123.161.169.10
返回结果：
{
"code": 200,
"msg": "查询成功",
"data": {
"input": "123.161.169.10",
"ip": "123.161.169.10",
"ip_type": "IPv4",
"country": "中国",
"province": "河南省",
"city": "驻马店市",
"district": "驿城区",
"isp": "中国电信",
"big_area": "华中",
"continent": "亚洲",
"zipcode": "463900",
"country_code": "CN",
"lng": "114.02597",
"lat": "32.98962",
"domain_parse_msg": "",
"call_stats": {
"used_count": 1,
"limit_count": 50,
"reset_time": "2026-03-28 18:00:00"
}
}
}
示例2：缺少授权码（返回401未授权）
请求地址：http://ping.4759.cn/api/ip.php?ip=123.161.169.10
返回结果：
{
"code": 401,
"msg": "未授权：缺少有效的API授权码（key参数），由 4759.cn 提供服务",
"data": null
}
<?php
$apiUrl = 'http://ping.4759.cn/api/ip.php';
$apiKey = '您的授权码';
$target = 'www.baidu.com';
$requestUrl = $apiUrl . '?key=' . urlencode($apiKey) . '&ip=' . urlencode($target);
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $requestUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>