IP 归属地查询接口技术解析：请求参数、返回结构与错误排查

本文以「IP 归属地查询接口」为对象，面向开发者梳理其能力边界、接入方式与调试要点，全文为中立技术说明。

一、技术简介

IP 归属地查询接口（又称 IP 地理定位接口）是一类将 IP 地址解析为地理位置信息的网络服务。它接收单个 IPv4 地址作为输入，返回该地址所属的国家、省、市、区县、运营商、经纬度坐标以及行政区划编码等多维度数据。该接口适用于需要在服务端识别访问来源地理分布的场景，例如访问日志的地域统计、异常流量的初步定位、按地域做内容或节点调度的前置判断等。其定位精度可达县区级，覆盖国内与海外多数 IP 段。下文将围绕接口的请求构造、返回字段、调试方法与错误排查展开说明。

二、能力概览

下表列出接口对外提供的主要数据维度，便于在接入前评估是否满足业务的数据需求。

三、适用场景

该接口以「IP → 地理位置」的映射为核心，下列为常见的技术接入情境：

• 访问日志地域统计：在 Web 服务或网关层对每条请求的来源 IP 做归属地解析，按省/市维度聚合访问分布，支撑运营看板。
• 异常流量初判：当某来源 IP 在短时间内出现大量请求时，结合归属地信息辅助判断是否来自异常区域，作为风控规则的输入之一。
• 内容或节点调度：根据来源 IP 的地域归属，将用户引导至就近的接入节点或返回本地化内容。
• 合规与数据驻留：在涉及数据地域合规要求的系统中，用归属地信息做区域判断与留痕。

以上场景均只把接口输出作为技术判断的输入，不应作为唯一决策依据。

四、接入流程

接口采用标准 HTTP GET 方式调用，鉴权使用阿里云市场 API 网关的 APPCODE 方式。

请求要素

请求参数（Query）

标准接入步骤

1. 在阿里云市场完成该接口的订购，获取 APPCODE。
2. 在请求头中设置 Authorization: APPCODE <appcode>。
3. 以 GET 方式携带 ip 参数请求上述地址。
4. 解析返回的 JSON，读取 showapi_res_body 中的地理字段。

五、调用示例与返回结构

以下展示四种语言的调用示例与一份完整的返回样例。

返回结构

接口统一以如下结构返回：

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "country": "中国",
    "en_name": "China",
    "en_name_short": "CN",
    "continents": "亚洲",
    "region": "云南",
    "city": "昆明",
    "county": "五华",
    "city_code": "530102",
    "isp": "电信",
    "ip": "106.61.28.243",
    "lnt": "102.70786",
    "lat": "25.03521",
    "ret_code": 0
  }
}

Python 示例

import urllib.request
import json

host = "https://ali-ip.showapi.com/ip"
appcode = "YOUR_APPCODE"
ip = "223.5.5.5"

req = urllib.request.Request(f"{host}?ip={ip}")
req.add_header("Authorization", f"APPCODE {appcode}")

with urllib.request.urlopen(req, timeout=10) as resp:
    data = json.loads(resp.read().decode("utf-8"))

body = data.get("showapi_res_body", {
   })
print(body.get("country"), body.get("region"), body.get("city"), body.get("isp"))

Java 示例

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

public class IpLookup {
   
    public static void main(String[] args) throws Exception {
   
        String host = "https://ali-ip.showapi.com/ip";
        String appcode = "YOUR_APPCODE";
        String ip = "223.5.5.5";

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(host + "?ip=" + ip))
                .header("Authorization", "APPCODE " + appcode)
                .GET()
                .build();

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

PHP 示例

<?php
$host = "https://ali-ip.showapi.com/ip";
$appcode = "YOUR_APPCODE";
$ip = "223.5.5.5";

$url = $host . "?ip=" . $ip;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: APPCODE " . $appcode));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
$body = json_decode($result, true);
print_r($body["showapi_res_body"]);
?>

Node.js 示例

const https = require("https");

const host = "https://ali-ip.showapi.com/ip";
const appcode = "YOUR_APPCODE";
const ip = "223.5.5.5";

const options = {
   
  headers: {
    Authorization: `APPCODE ${
     appcode}` }
};

https.get(`${
     host}?ip=${
     ip}`, options, (res) => {
   
  let raw = "";
  res.on("data", (chunk) => (raw += chunk));
  res.on("end", () => {
   
    const data = JSON.parse(raw);
    console.log(data.showapi_res_body);
  });
});

六、在线调试实录

下面以一次真实调用走查接口行为。查询目标 ip=106.61.28.243，请求头携带 APPCODE。

请求

GET /ip?ip=106.61.28.243 HTTP/1.1
Host: ali-ip.showapi.com
Authorization: APPCODE <appcode>

响应（HTTP 200）

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "country": "中国",
    "en_name": "China",
    "en_name_short": "CN",
    "continents": "亚洲",
    "region": "云南",
    "city": "昆明",
    "county": "五华",
    "city_code": "530102",
    "isp": "电信",
    "ip": "106.61.28.243",
    "lnt": "102.70786",
    "lat": "25.03521",
    "ret_code": 0
  }
}

结果解读

• showapi_res_code 为 0 表示接口层处理成功；ret_code 为 0 表示归属地查询成功。
• 当 ip 查不到对应归属地时，接口仍返回 HTTP 200，但 showapi_res_body.ret_code 可能为 -1，需读取 showapi_res_body 中的错误信息字段做处理。
• 经纬度为字符串类型，下游若用于计算应先转为数值。

七、接口调用限制与规范

以下为接入时需关注的规范，具体配额为账号维度配置，以控制台实时配置为准。

• 调用频率：单账户存在 QPS 上限，高并发场景需做客户端限流与排队，避免集中突发。
• 配额：每次成功响应（HTTP 200）扣减一次调用额度，非 200 响应通常不计入扣减，以控制台说明为准。
• 批量规则：该接口为单 IP 查询，若需批量解析应在客户端循环调用并做好频控。
• 参数规范：ip 须为标准 IPv4 格式；传入非法或查无结果的地址会触发对应的错误分支（见第九章）。
• 合规要求：归属地数据仅用于技术判断，调用方应在隐私政策中说明数据用途，避免将结果用于违规的地域歧视或用户画像。

八、能力边界与免责声明

支持

• 国内与海外 IPv4 地址的归属地解析。
• 返回国家、省、市、区县、运营商、经纬度、行政区划编码等维度。
• 单次单 IP 查询。

不支持 / 边界

• 不支持 IPv6 地址解析（请确认输入为 IPv4）。
• 不保证 100% 覆盖所有 IP 段，部分地址可能查无结果。
• 数据库按周期更新，实时性以数据源更新频率为准，不保证与当前网络拓扑完全一致。
• 经纬度为大致定位，不能用于需要精确物理定位的场景。

免责声明

归属地数据仅供参考，接口不对数据准确性、完整性及基于该数据做出的业务决策承担责任。生产环境应结合多源信息校验关键判断。

九、错误码与排查指南

接口的错误来自两层：HTTP 层（由网关返回）与业务层（由响应体 ret_code 返回）。

十、常见问题 FAQ

Q1：接口支持 IPv6 吗？
当前接口面向 IPv4 地址，传入 IPv6 会触发 555 / ret_code=-1 错误分支，建议调用前做地址族校验。

Q2：返回的国家英文名与缩写字段有什么用？
en_name（如 China）与 en_name_short（如 CN）便于与国际化的地理库、ISO 3166 标准做关联，适合多语言系统。

Q3：查不到归属地时接口会报错吗？
不一定。常见情况下接口仍返回 HTTP 200，但 showapi_res_body.ret_code 为 -1，需在业务代码中显式处理该分支，而不是仅判断 HTTP 状态。

Q4：经纬度是字符串还是数值？
示例返回中为字符串（如 "102.70786"），用于距离计算或地图标点时需先转为浮点数。

Q5：高并发调用要注意什么？
应遵守账户 QPS 上限，在客户端实现限流、重试与退避；避免短时突发导致 403 限流。

Q6：城市代码（city_code）如何解读？
为行政区划代码（如 530102 对应昆明市五华区），可与国家统计局行政区划代码标准对齐，用于区县级聚合。

十一、内容小结

IP 归属地查询接口以 GET 方式、APPCODE 鉴权，将单个 IPv4 地址解析为国家、省、市、区县、运营商、经纬度与行政区划编码等维度，定位精度可达县区级。接入时需注意：请求仅含 ip 一个必填参数；返回结构统一以 showapi_res_code/showapi_res_body 承载；查无结果时仍可能返回 HTTP 200 但 ret_code=-1，必须在代码中处理；调用受账户 QPS 与配额约束，高并发需做好限流与重试。归属地数据仅作技术参考，生产环境应结合多源校验。