国际 IP 地址定位

定位结果是 IP 所属网络的地域参考，不代表设备实时位置。城市、省份可能为空；经纬度为可用定位记录中的数值，缺失或冲突记录明确失败。数据公布与更新频率以实际来源为准。
查询 IPv4 地址所属网络的地域资料。
查询 IPv6 地址所属网络的地域资料。
支持合法的 IPv6 压缩写法。
支持 IPv4 映射 IPv6 地址的兼容查询。
返回国家代码，便于地域分组。
返回可用的省份资料，便于区域展示。
返回可用的城市资料，便于城市级参考。
返回纬度与经度，便于展示地域参考点。
可用于网络访问记录的地域整理。
可用于地域统计报表中的资料补充。
一次查询一个 IP，便于按请求核对定位结果。
提供 IPv6 公开样例，便于验证接入格式。

当前接口契约

接口详情：https://www.gugudata.com/api/details/internationaliplocation

请求参数

参数	类型	必填	默认值	说明
appkey	string	是	无	开发者凭据；支持现有 Query、Header 和 Bearer，多处值须一致。
ip	string	是	无	IPv4 或 IPv6 字面量；不接受域名、端口或 CIDR。

正常响应字段

字段	类型	说明
dataStatus.requestParameter	string	真实、可读的业务请求参数；无业务参数时为空，不包含凭据。
dataStatus.statusCode	integer	接口返回状态码
dataStatus.status	string	接口返回状态，例如 SUCCESS 或 ERROR。
dataStatus.statusDescription	string	接口返回状态说明
dataStatus.responseDateTime	string	接口数据返回时间
dataStatus.dataTotalCount	integer	单个定位对象为 1。
data	object	定位结果是 IP 所属网络的地域参考，不代表设备实时位置。城市、省份可能为空；经纬度为可用定位记录中的数值，缺失或冲突记录明确失败。数据公布与更新频率以实际来源为准。
data.countryCode	string	IP 地址定位国家代码
data.state	string/null	IP 地址定位省份/州
data.city	string/null	IP 地址定位城市
data.latitude	number	IP 地址定位纬度
data.longitude	number	IP 地址定位经度

业务状态说明

业务状态码	业务状态码解释	备注
200	成功	HTTP 200
400	参数错误	HTTP 400
500	定位数据不可用	HTTP 500
429	频率受限	HTTP 429
403	无权限或过期	HTTP 403
402	凭据错误	HTTP 402

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

成功（业务码 200）。

Bodyapplication/json

示例

{"dataStatus":{"requestParameter":"ip=2001:4878:b554:aaaa:aaaa:aaaa:aaaa:aaaa","statusCode":200,"status":"SUCCESS","statusDescription":"successfully / 成功","responseDateTime":"2026-10-26 21:01:02","dataTotalCount":1},"data":{"countryCode":"US","state":"Massachusetts","city":"Cambridge (East Cambridge)","latitude":42.3649,"longitude":-71.0889}}

🟠400参数错误（业务码 400）。

🔴500定位数据不可用（业务码 500）。

🟠429频率受限（业务码 429）。

🟠403无权限或过期（业务码 403）。

🟠402凭据错误（业务码 402）。

当前接口契约#

请求参数#

正常响应字段#

业务状态说明#

请求参数

请求示例代码

返回响应

当前接口契约

请求参数

正常响应字段

业务状态说明