IPDB｜猫猫说的对！

1. 接口说明

1.1 IP 地理位置查询

请求路径： /api/ip
请求方法： GET
功能描述： 根据提供的 IP 地址查询并返回详细的地理位置、ISP 及相关元数据。

请求参数

参数名	数据类型	必填	描述说明	示例值
ip	string	是	需查询的 IPv4 或 IPv6 地址	`121.35.100.100` 或 `240e:3b7...`
lang	string	否	指定响应结果的语言代码	`zh`, `en`, `ja`, `ko`, `fr`, `de`, `es`, `ru`, `ar`, `hi`

2. 响应数据字典

成功调用后，API 将返回 JSON 格式的数据对象。以下为各字段的详细说明：

字段名	数据类型	描述说明	示例值
ip	string	被查询的原始 IP 地址	`121.35.100.100`
ip_version	string	IP 协议版本	`IPv4`
continent	string	所属大洲	`亚洲`
country	string	所属国家	`中国`
province	string	所属省份	`广东`
city	string	所属城市	`深圳`
district	string	所属区县	`宝安`
isp	string	互联网服务提供商 (ISP)	`电信`
longitude	string	地理经度坐标	`113.88311`
latitude	string	地理纬度坐标	`22.55371`
admin_code	string	行政区划代码	`440306`
area_code	string	电话区号	`0755`
zip_code	string	邮政编码	`518100`
time_zone	string	所在时区	`Asia/Shanghai`
currency	string	法定货币代码	`CNY`
elevation	string	海拔高度	`11`
weather_station	string	气象站代码	`CHXX0120`
country_code	string	国家代码（注：仅 IPv6 查询返回）	`CN`
language	string	当前响应采用的语言代码	`zh`

3. 请求与响应示例

3.1 综合查询（IPv4 结合多语言参数）

通过附加 lang 参数获取指定语言（如英文）的定位信息。

请求指令：

curl "https://ip.huhu.cafe/api/ip?ip=84.245.9.227&lang=en"

响应报文：

{
  "ip": "84.245.9.227",
  "ip_version": "IPv4",
  "continent": "Europe",
  "country": "Netherlands",
  "province": "Flevoland",
  "city": "Almere Stad",
  "district": "",
  "isp": "Cambrium",
  "country_code": "",
  "longitude": "52.385800",
  "latitude": "5.221500",
  "admin_code": "",
  "area_code": "",
  "zip_code": "1316",
  "time_zone": "Europe/Amsterdam",
  "currency": "EUR",
  "elevation": "",
  "weather_station": "",
  "language": "en"
}

3.2 IPv6 协议查询

查询 IPv6 格式地址，返回结果将包含专属的 country_code 字段。

请求指令：

curl "https://ip.huhu.cafe/api/ip?ip=240e:3b7:3272:d8d0:db09:c067:8d59:539e"

响应报文：

{
  "ip": "240e:3b7:3272:d8d0:db09:c067:8d59:539e",
  "ip_version": "IPv6",
  "continent": "Asia",
  "country": "中国",
  "province": "广东省",
  "city": "深圳市",
  "district": "",
  "isp": "电信",
  "country_code": "CN",
  "longitude": "",
  "latitude": "",
  "admin_code": "",
  "area_code": "",
  "zip_code": "",
  "time_zone": "",
  "currency": "",
  "elevation": "",
  "weather_station": ""
}

4. 异常与错误处理

当 API 调用遭遇异常时，将返回相应的 HTTP 状态码及错误信息描述，以便快速定位问题。

HTTP 状态码	错误提示信息	触发原因描述
400	IP地址不能为空	客户端请求中缺失必需的 IP 地址参数
400	无效的IP地址	提供的 IP 地址格式不符合 IPv4 或 IPv6 标准规范
500	IPv4搜索器未初始化	服务端内部异常，IPv4 数据检索模块加载失败
500	IPv6搜索器未初始化	服务端内部异常，IPv6 数据检索模块加载失败
500	服务器内部错误	服务器处理请求时发生未知异常或崩溃