IP归属地查询接口接入指南｜输入IP地址，获取国家、省份、城市、运营商与经纬度

一、技术简介

IP 归属地查询接口（IP Geolocation API）是一项将 IP 地址解析为地理位置信息的基础数据服务。输入一个 IPv4 地址，接口返回该地址对应的国家、省份、城市、区县、运营商、经纬度坐标以及行政区划编码等多维度地理属性。该能力适用于需要根据网络来源 IP 做地域识别的技术场景，例如访问风控、内容分发、日志分析、流量统计等。接口基于标准 HTTP 协议提供，返回 JSON 结构数据，便于在服务端或脚本中直接解析使用。

二、能力概览

三、适用场景

• 访问风控与反欺诈：在登录、注册、下单等环节获取请求来源 IP 的地域与运营商信息，结合业务规则识别异常登录或可疑流量。
• 内容分发与本地化：根据用户地域返回对应的语言、币种、库存或运营活动，实现区域化内容投放。
• 日志与流量分析：将访问日志中的 IP 批量转换为地理位置，绘制地域分布热力图或统计来源构成。
• 网络质量诊断：结合运营商与地理位置信息，定位访问延迟较高的区域，辅助链路优化。

四、接入流程

4.1 请求参数

4.2 接入步骤

1. 在云市场开通对应 API 商品，获取 appcode。
2. 在控制台查看该商品的 API 网关接入地址与请求方式。
3. 构造请求：在 Header 携带 Authorization: APPCODE <appcode>，Body 或 Query 传入 ip 参数。
4. 发送 HTTP 请求，解析响应 JSON 中的 showapi_res_body 业务字段。
5. 对返回的错误码做分支处理，完善异常路径。

五、调用示例与返回结构

5.1 请求示例

以 POST 方式调用，接入地址以控制台调用信息为准，请求头携带 appcode：

POST /post/<apiCode> HTTP/1.1
Host: <云市场API网关接入地址>
Authorization: APPCODE <appcode>
Content-Type: application/x-www-form-urlencoded

ip=203.0.113.220

5.2 完整返回结构（JSON）

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
  "showapi_res_body": {
   
    "country": "中国",
    "region": "云南",
    "city": "昆明",
    "county": "五华",
    "isp": "电信",
    "continents": "亚洲",
    "en_name": "China",
    "en_name_short": "CN",
    "lat": "23.048884",
    "lnt": "113.760234",
    "city_code": "530100",
    "ret_code": 0
  }
}

5.3 字段含义说明

5.4 多语言调用示例

Python

import requests

host = "<云市场API网关接入地址>"
appcode = "<appcode>"
api_code = "<apiCode>"

resp = requests.post(
    f"https://{host}/post/{api_code}",
    headers={
   "Authorization": f"APPCODE {appcode}"},
    data={
   "ip": "203.0.113.220"},
)
body = resp.json()["showapi_res_body"]
print(body["country"], body["city"], body["isp"])

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URLEncoder;

public class IpGeoDemo {
   
    public static void main(String[] args) throws Exception {
   
        String host = "<云市场API网关接入地址>";
        String appcode = "<appcode>";
        String apiCode = "<apiCode>";
        String ip = URLEncoder.encode("203.0.113.220", "UTF-8");

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://" + host + "/post/" + apiCode))
            .header("Authorization", "APPCODE " + appcode)
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString("ip=" + ip))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php
$host = "<云市场API网关接入地址>";
$appcode = "<appcode>";
$apiCode = "<apiCode>";
$ip = "203.0.113.220";

$ch = curl_init("https://{$host}/post/{$apiCode}");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: APPCODE {$appcode}", "Content-Type: application/x-www-form-urlencoded"],
    CURLOPT_POSTFIELDS => http_build_query(["ip" => $ip]),
    CURLOPT_RETURNTRANSFER => true,
]);
$resp = curl_exec($ch);
curl_close($ch);
echo $resp;

Node.js

const https = require("https");

const host = "<云市场API网关接入地址>";
const appcode = "<appcode>";
const apiCode = "<apiCode>";
const postData = "ip=" + encodeURIComponent("203.0.113.220");

const req = https.request(
  {
   
    hostname: host,
    path: "/post/" + apiCode,
    method: "POST",
    headers: {
   
      "Authorization": "APPCODE " + appcode,
      "Content-Type": "application/x-www-form-urlencoded",
      "Content-Length": Buffer.byteLength(postData),
    },
  },
  (res) => {
   
    let data = "";
    res.on("data", (chunk) => (data += chunk));
    res.on("end", () => console.log(data));
  }
);
req.write(postData);
req.end();

六、在线调试实录

在控制台「API 调试」面板中填写参数即可发起在线调用，无需编写代码即可验证返回结构：

1. 选择该商品的 API 调试入口，确认请求方式为 POST。
2. 在 Header 中填入 Authorization: APPCODE <appcode>。
3. 在 Body 参数中填写 ip = 203.0.113.220。
4. 发起请求，观察返回 JSON。
5. 校验 showapi_res_code == 0 且 showapi_res_body.ret_code == 0，再读取 country / city / isp 等业务字段。

常见观察点：若 showapi_res_code 非 0，说明请求在网关层被拦截（多为鉴权或限流）；若 ret_code 非 0，说明请求到达业务层但查询未成功（多为 IP 格式或数据缺失）。

七、接口调用限制与规范

• 请求频率：单账户存在 QPS 上限与每日调用配额，具体数值以控制台实时配置为准，建议在客户端做限流与排队。
• 参数规范：ip 须为标准 IPv4 格式；非法格式会被网关或业务层拒绝。
• 编码规范：请求体建议使用 application/x-www-form-urlencoded 编码。
• 幂等说明：同一 IP 的多次查询互不影响，可安全重试；重试时建议结合退避策略，避免触发限流。
• 合规要求：仅可将接口用于自身业务的地域识别，不得用于用户画像定向、违规追踪或其他违反数据合规要求的行为。
• 封禁说明：高频异常请求、鉴权失败频发或超出配额可能触发临时限流，请关注配额余量。

八、能力边界与免责声明

支持范围

• 标准 IPv4 地址的归属地解析。
• 返回国家、省、市、区县、运营商、经纬度、行政区划编码等维度。

不支持 / 边界

• 不保证对每个 IP 都能解析到区县级（部分 IP 仅能定位到省级或市级）。
• 不提供 IPv6 解析（如需请选择对应专用接口）。
• 定位结果基于 IP 地址库推算，反映注册地或运营地，可能与实际物理位置存在偏差。
• 不提供历史 IP 归属地变更记录。

免责声明

• 返回数据来源于公开的 IP 地址库，仅供参考，不作为唯一判定依据。
• 接口不对基于返回数据做出的业务决策承担责任。
• 调用方须自行保障传输安全与密钥保管，避免 appcode 泄露。

九、错误码与排查指南

十、常见问题 FAQ

Q1：返回的国家和城市不一致怎么办？
A：定位结果基于 IP 地址库推算，部分 IP 的注册地与使用地不同属正常情况，建议业务侧仅将结果作为参考维度。

Q2：数据多久更新一次？
A：IP 地址库按周期更新维护，具体刷新频率以控制台说明为准；不宜将结果用于强实时性判定。

Q3：是否支持批量查询？
A：单次请求对应单个 IP。如需批量，建议在服务端以受控并发循环调用，并遵守频率限制，避免触发限流。

Q4：支持 IPv6 吗？
A：本接口面向 IPv4；IPv6 请选择对应的专用接口。

Q5：返回坐标是 WGS84 还是 GCJ02？
A：返回坐标的具体坐标系以接口文档为准；如需与地图叠加，注意坐标系转换。

Q6：调用异常时如何对账？
A：建议结合返回码与控制台配额监控记录请求结果，对失败请求做标记与统计，便于后续排查。

十一、内容小结

本文介绍了 IP 归属地查询接口的接入方式：在 Header 携带 Authorization: APPCODE <appcode> 鉴权，传入 ip 参数即可获得国家、省、市、区县、运营商、经纬度与行政区划编码等地理属性。接入时建议做好参数校验、频率控制与异常分支处理，并将结果作为参考维度参与业务判断。调用前请在控制台确认接入地址、配额与限制，确保符合使用规范。