<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# IP 地址查询（街道级）

> 提供 IP 地址的街道级归属查询，精度可达乡镇街道一级。

相比普通国家/城市级 IP 库，本接口返回 25+ 个字段：省市区街道四级行政 + 多备选街道、经纬度、海拔、邮编、区号、行政区划代码、ISP 运营商、气象站编码、IANA 时区，以及完整的代理/风险评分（是否代理、代理概率、代理类型、真实用户率、移动流量率、风险等级、风险评分、风险标签）。

典型场景：反欺诈与风控、精准营销与广告投放、门店 LBS 分布分析、物流与配送区域匹配、区域合规访问控制、日志 BI 地理回填。

支持 IPv4 与 IPv6。边缘缓存 12 小时，命中时延迟 <10ms；未命中时约 200–500ms。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `ip-pro` |
| 接口名称 | IP 地址查询（街道级） |
| 接口地址 | `https://v1.apizero.cn/api/ip-pro` |
| 请求方法 | `GET` |
| 分类 | geo |
| 提供方 | 极数本源 |
| 计费模式 | 按次付费 · 点数包 · 月套餐 |
| 单次消耗 | 5 积分 |
| 起步价 | ¥0.00 / 1000 次 |
| QPS 限制 | 3 req/s |
| 每日免费额度 | 30 次（已认证用户） |
| 匿名每日额度 | 5 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

本接口默认开放匿名调用（受每日免费额度限制）。需要更高配额或商业使用时，请携带 Authorization 头。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `ip` | `string` | 否 | 要查询的 IP 地址（IPv4 或 IPv6）。不传时自动使用调用方自身 IP，适用于"查我自己" | `110.87.41.14` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | Bearer Token。匿名调用时可省略（受每日免费额度限制）；付费方案或超过免费额度时必需 | `Bearer sk_live_xxxxxxxxxxxxxxxx` |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/ip-pro?ip=110.87.41.14&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `code` | `integer` | 业务状态码，0 表示成功 | `0` |
| `msg` | `string` | 人类可读的中文消息 | `成功` |
| `data` | `object` | 业务数据 | — |
| `request_id` | `string` | 本次请求的唯一 ID（调试时请提供给客服） | `moq2ifz512694137` |
| `data.ip` | `string` | IP 地址（原样返回） | `110.87.41.14` |
| `data.ip_int` | `integer` | IPv4 的整数形式；IPv6 为 null | `1851205902` |
| `data.continent` | `string` | 大洲名（中文） | `亚洲` |
| `data.country` | `string` | 国家/地区名（中文） | `中国` |
| `data.country_code` | `string` | ISO 3166-1 二字国家码 | `CN` |
| `data.province` | `string` | 省 / 直辖市 / 自治区 | `福建` |
| `data.city` | `string` | 地级市 | `福州` |
| `data.district` | `string` | 区 / 县 | `永泰` |
| `data.street` | `string` | 乡镇 / 街道（最佳匹配） | `城峰镇` |
| `data.street_alternatives` | `string[]` | 备选街道（同 IP 段跨多街道时有用） | `["福建福州永泰城峰镇", ...]` |
| `data.area_code` | `string` | 6 位行政区划代码（GB/T 2260） | `350125` |
| `data.zip_code` | `string` | 邮政编码 | `350000` |
| `data.city_code` | `string` | 电话区号 | `0591` |
| `data.location` | `string` | 人类友好位置串 | `中国福建福州永泰电信` |
| `data.latitude` | `float` | 纬度（WGS-84）；无数据为 null | `25.855039` |
| `data.longitude` | `float` | 经度（WGS-84）；无数据为 null | `118.94202` |
| `data.elevation` | `integer` | 海拔（米）；无数据为 null | `29` |
| `data.time_zone` | `string` | IANA 时区 | `Asia/Shanghai` |
| `data.weather_station` | `string` | 最近气象站编码（WMO） | `CHXX0031` |
| `data.isp` | `string` | 运营商 | `电信` |
| `data.risk` | `object` | 风险评分子对象 | — |
| `data.risk.level` | `string` | 风险等级：无风险/低风险/中风险/高风险 | `无风险` |
| `data.risk.score` | `integer` | 风险评分 0 ~ 100，越高越危险 | `0` |
| `data.risk.is_proxy` | `boolean` | 是否为代理 / VPN | `false` |
| `data.risk.proxy_probability` | `float` | 代理概率 0 ~ 100（%） | `0` |
| `data.risk.proxy_type` | `string` | 代理类型（HTTP/SOCKS5/VPN/Tor，无则空） | — |
| `data.risk.real_rate` | `float` | 真实用户流量占比（%） | `6` |
| `data.risk.mobile_rate` | `float` | 移动流量占比（%） | `4.69` |
| `data.risk.tag` | `string` | 风险标签（机房/数据中心/爬虫等，无则空） | — |
| `data.risk.detected_at` | `string` | 最后检出时间，无记录为 null | `null` |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "ip": "110.87.41.14",
        "ip_int": 1851205902,
        "continent": "亚洲",
        "country": "中国",
        "country_code": "CN",
        "province": "福建",
        "city": "福州",
        "district": "永泰",
        "street": "城峰镇",
        "street_alternatives": [
            "福建福州永泰城峰镇",
            "福建福州永泰大洋镇",
            "福建福州永泰S211",
            "福建福州永泰X182"
        ],
        "area_code": "350125",
        "zip_code": "350000",
        "city_code": "0591",
        "location": "中国福建福州永泰电信",
        "latitude": 25.855039,
        "longitude": 118.94202,
        "elevation": 29,
        "time_zone": "Asia/Shanghai",
        "weather_station": "CHXX0031",
        "isp": "电信",
        "risk": {
            "level": "无风险",
            "score": 0,
            "is_proxy": false,
            "proxy_probability": 0,
            "proxy_type": "",
            "real_rate": 6,
            "mobile_rate": 4.69,
            "tag": "",
            "detected_at": null
        }
    },
    "request_id": "moq2ifz512694137"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `0` | `OK` | 成功 |
| `4000` | `Bad Request` | IP 地址格式错误：ip 参数不是合法 IPv4 / IPv6 |
| `4011` | `Unauthorized` | API Key 无效：Bearer Token 格式错误或不存在 |
| `4013` | `Forbidden` | API Key 已暂停 |
| `4014` | `Forbidden` | 当前 IP 不在 API Key 白名单内 |
| `4015` | `Unauthorized` | 本接口需要 API Key 才能调用（管理员关闭了匿名调用时） |
| `4022` | `Payment Required` | 余额不足，请充值后再试 |
| `4029` | `Too Many Requests` | 调用过快，请稍后再试（超过 QPS 限制） |
| `4030` | `Too Many Requests` | 今日免费额度已用完 |
| `5020` | `Bad Gateway` | 上游服务暂不可用（上游超时或宕机） |

## 9. 变更日志

- **1.0.0** (2026-05-04)
  - 首次发布
  - 支持 IPv4 / IPv6 街道级归属查询
  - 返回 25+ 标准化字段（含完整风险评分）
  - 12 小时边缘缓存

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/ip-pro`

Source: `https://apizero.cn/aidocs/ip-pro/raw.md`
Last updated: 2026-05-13T16:42:07+08:00