IP 归属查询 API：IPv4、IPv6、地域字段与未命中处理-优快云博客

GuGuData IP 归属查询 API 使用 GET 接收 IPv4 或 IPv6 字面量，返回 Country、Address 和 LocationCode 三个资料字段。结果是 IP 所属网络的地域参考，不是设备的实时位置或精确坐标；没有命中资料时仍保留 Data 对象，并以 DataTotalCount=0 标识。

原始 API 封面

接口与输入

项目	说明
请求方法	GET
接口地址	`https://api.gugudata.com/websitetools/iplocation`
返回格式	JSON，UTF-8
鉴权	对应产品有效 AppKey；示例通过 Header 提供

参数名	参数类型	是否必须	默认值	备注
appkey	string	是	无	已开通本商品的 APPKEY；也可使用既有 Header 或 Bearer 鉴权，不同时要求多个载体。
ip	string	是	无	要查询的 IPv4 或 IPv6 字面量；不是域名、URL、端口或 CIDR。

参数名与大小写按当前契约传递，鉴权凭据只需使用一种受支持的方式。公开文章不放真实 AppKey。

请求示例

以下是集成示例，YOUR_APPKEY 为占位符，未使用真实凭据执行。正式调用需要对应产品权益。查询参数由 --data-urlencode 分别编码，避免中文或特殊字符破坏 URL。

curl --get 'https://api.gugudata.com/websitetools/iplocation' \
  --header 'X-GUGUDATA-APPKEY: YOUR_APPKEY' \
  --data-urlencode 'ip=110.96.0.0'

返回字段

参数名	参数类型	备注
DataStatus.RequestParameter	string	本次真实、可读的业务请求参数，不含凭据；Demo 与实际示例输入对应。
DataStatus.StatusCode	integer	100 成功；501 参数错误对应 HTTP 400；901 处理或依赖失败对应 HTTP 503，公共鉴权和限流规则保持。
DataStatus.StatusDescription	string	业务处理结果说明。
DataStatus.ResponseDateTime	string	接口响应生成时间，不代表来源资料更新时间。
DataStatus.DataTotalCount	integer	本次返回的记录数量；无命中时为 0。
Data	object	定位结果对象；未命中时保留对象并返回 DataTotalCount=0。
Data.Country	string / null	历史地域描述字段；不改为国家代码，未命中可为 null。
Data.Address	string / null	IP 地址具体定位地址
Data.LocationCode	string / null	可关联的六位行政区划码；无法关联时为空字符串，未命中可为 null。

公开样例与结果核对

2026 年 11 月 7 日回读了当前公开样例。公开 Demo 查询 110.96.0.0，与上方请求输入一致，以下保留实际业务字段及计数。

{
  "DataStatus": {
    "StatusCode": 100,
    "RequestParameter": "ip=110.96.0.0",
    "DataTotalCount": 1
  },
  "Data": {
    "Address": "中移铁通",
    "Country": "北京市",
    "LocationCode": "110000"
  }
}

公开样例证明采样时的返回结构，不代表带占位符的生产请求已经执行，也不用于推断全部数据覆盖或固定响应性能。响应时间和样例日期各有含义，应与 RequestParameter 一起核对。

字段口径与适用边界

ip 应是地址字面量，不传域名、URL、端口或 CIDR。Country 是历史地域描述字段，例如“北京市”，不能按名称误读为国家代码。Address 是来源网络或地域说明，不应直接当作用户家庭地址。LocationCode 为可关联的六位行政区划码，没有可靠关联时为空字符串，未命中时部分字段也可能为 null；缺失不能写成“未知用户位置已确认”。保留编码为字符串，不能将空码转换成数字 0。IPv4 和 IPv6 资料表达可能不同，不承诺固定精度或每周更新；共享网络、代理等情况下也不能据结果推断个人实际所在地。