全球IP归属地查询免费API详细指南

概述

接口盒子免费API提供的全球IP归属地查询服务是一个功能强大、完全免费的API接口，支持IPv4和IPv6地址查询，能够返回详细的IP地理位置和运营商信息。该服务结合大数据多通道查询，具有高稳定性和准确性。

核心功能特点

双协议支持：全面支持IPv4和IPv6地址查询
多通道查询：提供0-2三种查询通道，确保查询准确性
详细地理位置信息：返回大洲、国家、省、市、区级详细信息
附加数据：提供运营商信息、经纬度坐标及行政区划代码
免费使用：接口完全免费，无每日调用上限

接口基本信息

请求地址 ：https://cn.apihz.cn/api/ip/chaapi.php

请求方式：GET或POST

请求参数详解

参数名	类型	是否必填	说明
id	整数	是	用户中心的数字ID
key	字符串	是	用户中心通讯秘钥
ip	字符串	否	欲查询的IP地址(IPv4/IPv6)，不填则默认为请求接口IP
td	整数	否	查询通道(0-2)，0为综合通道(默认)

返回参数说明

成功查询将返回包含以下字段的JSON数据：

code: 状态码(200成功，400错误)
msg: 消息内容或位置描述
zhou: 大洲名称
guo: 国家名称
sheng: 省级名称
shi: 市级名称
qu: 区级名称
isp: 运营商名称
lat: 纬度坐标
lon: 经度坐标
guocode: 国家代码
ip: 被查询的IP地址
shengcode: 省级区划代码
shicode: 市级区划代码
qucode: 区级区划代码

调用示例

PHP调用示例

复制代码

php

复制

复制代码

<?php
/**
 * 全球IP归属地查询 - PHP示例
 * 需要确保服务器支持cURL扩展
 */

class IPQuery {
    private $apiUrl = 'https://cn.apihz.cn/api/ip/chaapi.php';
    private $userId = '你的用户ID'; // 替换为实际用户ID
    private $userKey = '你的用户KEY'; // 替换为实际用户KEY
    
    /**
     * 查询IP归属地信息
     * @param string $ip 要查询的IP地址，为空则查询本机IP
     * @param int $channel 查询通道(0-2)，默认0为综合通道
     * @return array 解析后的IP信息数组
     */
    public function query($ip = '', $channel = 0) {
        // 构建请求参数
        $params = array(
            'id' => $this->userId,
            'key' => $this->userKey,
            'td' => $channel
        );
        
        if (!empty($ip)) {
            $params['ip'] = $ip;
        }
        
        // 构建请求URL
        $url = $this->apiUrl . '?' . http_build_query($params);
        
        // 发起GET请求
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 10);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        
        if (curl_error($ch)) {
            return array('code' => 400, 'msg' => '请求失败: ' . curl_error($ch));
        }
        
        curl_close($ch);
        
        // 解析返回的JSON数据
        $result = json_decode($response, true);
        
        if (json_last_error() !== JSON_ERROR_NONE) {
            return array('code' => 400, 'msg' => 'JSON解析失败: ' . json_last_error_msg());
        }
        
        return $result;
    }
}

// 使用示例
$ipQuery = new IPQuery();

// 查询指定IP
$result = $ipQuery->query('112.192.49.243');

// 查询本机IP
// $result = $ipQuery->query();

if ($result['code'] == 200) {
    echo "查询成功:\n";
    echo "IP: " . $result['ip'] . "\n";
    echo "位置: " . $result['guo'] . "-" . $result['sheng'] . "-" . $result['shi'] . "\n";
    echo "运营商: " . $result['isp'] . "\n";
    echo "经纬度: " . $result['lat'] . ", " . $result['lon'] . "\n";
} else {
    echo "查询失败: " . $result['msg'] . "\n";
}
?>

Python调用示例

复制代码

python

下载

复制

复制代码

#!/usr/bin/env python3
"""
全球IP归属地查询 - Python示例
需要安装requests库: pip install requests
"""

import requests
import json

class IPQuery:
    def __init__(self, user_id, user_key):
        self.api_url = "https://cn.apihz.cn/api/ip/chaapi.php"
        self.user_id = user_id
        self.user_key = user_key
    
    def query(self, ip="", channel=0):
        """
        查询IP归属地信息
        :param ip: 要查询的IP地址，为空则查询本机IP
        :param channel: 查询通道(0-2)，默认0为综合通道
        :return: 解析后的IP信息字典
        """
        # 构建请求参数
        params = {
            'id': self.user_id,
            'key': self.user_key,
            'td': channel
        }
        
        if ip:
            params['ip'] = ip
        
        try:
            # 发起GET请求
            response = requests.get(
                self.api_url, 
                params=params, 
                timeout=10,
                verify=False  # 可根据需要设置为True以验证SSL证书
            )
            
            # 检查HTTP状态码
            if response.status_code != 200:
                return {
                    'code': 400, 
                    'msg': f'HTTP请求失败，状态码: {response.status_code}'
                }
            
            # 解析JSON响应
            result = response.json()
            return result
            
        except requests.exceptions.RequestException as e:
            return {'code': 400, 'msg': f'请求异常: {str(e)}'}
        except json.JSONDecodeError as e:
            return {'code': 400, 'msg': f'JSON解析失败: {str(e)}'}

# 使用示例
if __name__ == "__main__":
    # 替换为你的实际用户ID和KEY
    USER_ID = "你的用户ID"
    USER_KEY = "你的用户KEY"
    
    ip_query = IPQuery(USER_ID, USER_KEY)
    
    # 查询指定IP
    result = ip_query.query("112.192.49.243")
    
    # 查询本机IP
    # result = ip_query.query()
    
    if result.get('code') == 200:
        print("查询成功:")
        print(f"IP: {result.get('ip', '未知')}")
        print(f"位置: {result.get('guo', '未知')}-{result.get('sheng', '未知')}-{result.get('shi', '未知')}")
        print(f"运营商: {result.get('isp', '未知')}")
        print(f"经纬度: {result.get('lat', '未知')}, {result.get('lon', '未知')}")
        print(f"完整信息: {result.get('msg', '未知')}")
    else:
        print(f"查询失败: {result.get('msg', '未知错误')}")

注意事项

用户认证：必须使用自己的用户ID和KEY，避免使用示例中的公共测试凭证
频率限制：虽然接口免费且无每日上限，但存在每分钟调用频次限制
准确性说明：不同查询通道的结果可能略有差异，建议根据实际需要选择合适的通道
错误处理：在实际应用中应添加完善的错误处理机制
生产环境：在生产环境中使用时应考虑添加重试机制和缓存策略

应用场景

该API适用于多种应用场景：

网站分析：分析访问用户的地理分布
安全防护：识别异常登录地点
内容本地化：根据用户位置提供个性化内容
数据统计：生成用户地理分布热力图
网络管理：IP地址管理和定位

总结

接口盒子提供的全球IP归属地查询API是一个功能全面、稳定可靠的免费服务。通过简单的HTTP请求即可获取详细的IP地理位置信息，为开发者提供了极大的便利。无论是网站开发、数据分析还是网络安全应用，这个API都能提供有力的支持。

在使用过程中，建议开发者遵循API的使用规范，合理控制调用频率，并妥善处理可能出现的异常情况，以确保应用的稳定性和用户体验。