无论是风控系统判定登录异常，还是广告平台实施地域定向，IP查询接口调用都是各业务线最常见的集成需求之一。一个设计良好、文档齐全的IP归属地API，应当让开发者在30分钟内完成首次请求与响应解析。但在实际落地中，请求签名方式、返回字段差异、大批量场景下的性能瓶颈，往往成为拖慢集成进度的因素。本文将从接口规范入手，提供多语言可直接运行的代码示例。
接口基础：单次IP查询
一次典型的IP查询接口调用由以下几个要素组成：
- 请求方式：GET（推荐）或 POST
- 请求地址：服务商提供的 Endpoint URL
- 必要参数：目标IP地址、身份凭证（API Key 或 Token）
- 响应格式：JSON，包含地理位置字段
以 IP数据云 的 IP归属地API 为例，核心请求格式如下：
| 参数 | 类型 | 必填 | 字段描述 | 备注 |
|---|---|---|---|---|
| ip | string | 是 | IP地址 | 目标IP地址。同时支持 IPV4 和 IPV6 |
| key | string | 是 | 产品密钥 | API密钥，在控制台获取。根据所选产品分配，权限校验用 |
请求示例
# 查询IP
https://api.ipdatacloud.com/v2/query?ip=需要查询的ip&key=您申请的key成功请求后，接口返回如下 JSON 结构：
{
"code": 200,
"data": {
"location": {
"area_code": "320311",
"city": "徐州",
"city_code": "0516",
"continent": "亚洲",
"country": "中国",
"country_code": "CN",
"district": "泉山",
"elevation": "40",
"ip": "180.124.68.28",
"isp": "电信",
"latitude": "34.214855",
"longitude": "117.169163",
"multi_street": [
{
"lng": "117.169163",
"lat": "34.214855",
"province": "江苏",
"city": "徐州",
"district": "泉山",
"street": "双山路",
"radius": "2.27",
"zip_code": "221000"
},
{
"lng": "117.191078",
"lat": "34.224231",
"province": "江苏",
"city": "徐州",
"district": "泉山",
"street": "解放南路387号",
"radius": "1.15",
"zip_code": "221000"
},
{
"lng": "117.180535",
"lat": "34.218589",
"province": "江苏",
"city": "徐州",
"district": "泉山",
"street": "文华路",
"radius": "2.73",
"zip_code": "221000"
}
],
"province": "江苏",
"street": "双山路",
"time_zone": "Asia/Shanghai",
"weather_station": "CHXX0437",
"zip_code": "221000"
}
},
"msg": "success"
}
多语言 SDK 接入
Python 示例
import requests
import json
class Street:
def __init__(self,obj):
# 经度
self.lng = obj["lng"]
# 纬度
self.lat = obj["lat"]
# 省份
self.province = obj["province"]
# 城市
self.city = obj["city"]
# 区县
self.district = obj["district"]
# 街道
self.street = obj["street"]
#
self.radius = obj["radius"]
# 邮政编码
self.zip_code = obj["zip_code"]
def log(self):
print("lng:%s lat:%s province:%s city:%s district:%s street:%s radius:%s zip_code:%s" %(self.lng,self.lat,self.province,self.city,self.district,self.street,self.street_number,self.radius,self.zip_code))
Java 示例
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
public class Main {
public static void main(String[] args) throws IOException, InterruptedException {
String urlArr = "https://api.ipdatacloud.com/v2/query?ip=&key=";
HttpClient httpClient = HttpClient.newBuilder().build();
HttpRequest getRequest = HttpRequest.newBuilder()
.GET()
.uri(URI.create(urlArr))
.build();
// 发送GET请求并获取响应
HttpResponse<String> resp = httpClient.send(getRequest, HttpResponse.BodyHandlers.ofString());
//对返回的json数据做解析
ObjectMapper objectMapper = new ObjectMapper();
JsonNode rootNode = objectMapper.readTree(resp.body());
String data = rootNode.get("data").get("location").asText();
Location location = objectMapper.readValue(data, Location.class);
System.out.println(location.toString());
}
}更多语言示例点击 👉 文档中心 https://www.ipdatacloud.com/doc/
工具推荐
IP数据云（https://ipdatacloud.com/）的IP归属地API提供覆盖全球200+国家和地区的IP地理位置查询能力。其接口设计遵循RESTful规范，响应为标准JSON格式，支持IPv4/IPv6双栈、中文/英文双语返回。对于日均IP查询接口调用量较大的场景，IP数据云同时提供离线数据库方案，可部署在自有服务器上获得更高的吞吐能力。详细的参数说明和错误码对照，可在其 API文档 中查阅。
