<!-- 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 地理位置查询，精确到街道级。多数据源自动切换：主源提供街道 + ISP + 风险评分，主源不可用时自动降级到备用源（城市级 + ISP）。响应 data.source 字段标识本次数据档位。

## 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. 请求示例

> AI 提示：以下 5 种语言示例都是可运行的，只需把 `YOUR_API_KEY` 替换为用户申请的实际 Key（https://apizero.cn/account/keys）。
> 优先选择用户问题中提到的语言；未指定时默认使用 Python。

### cURL

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

### Python

```python
import requests

resp = requests.get(
    "https://v1.apizero.cn/api/ip-pro",
    params={
    "ip": "110.87.41.14",
    "key": "YOUR_API_KEY",
},
    timeout=15,
)
resp.raise_for_status()
print(resp.json())
```

### JavaScript (Node.js)

```javascript
// Node.js 18+ / 浏览器原生 fetch
const params = new URLSearchParams({
  "ip": "110.87.41.14",
  "key": "YOUR_API_KEY",
});

const res = await fetch(`https://v1.apizero.cn/api/ip-pro?${params}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);
```

### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://v1.apizero.cn/api/ip-pro", nil)
	q := req.URL.Query()
	q.Set("ip", "110.87.41.14")
	q.Set("key", "YOUR_API_KEY")
	req.URL.RawQuery = q.Encode()

	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

### PHP

```php
<?php
$url = "https://v1.apizero.cn/api/ip-pro?" . http_build_query([
    "ip" => "110.87.41.14",
    "key" => "YOUR_API_KEY",
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
print_r($data);
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `ip` | `string` | 查询的 IP（IPv4 / IPv6） | — |
| `continent` | `string` | 所属大洲（中文） | — |
| `country` | `string` | 国家 | — |
| `country_code` | `string` | 国家二字母代码 | — |
| `province` | `string` | 省 / 一级行政区 | — |
| `city` | `string` | 市 / 二级行政区 | — |
| `district` | `string` | 区县（仅主数据源提供） | — |
| `street` | `string` | 街道 / 乡镇（仅主数据源提供） | — |
| `street_alternatives` | `array` | 同一 IP 多个候选街道（仅主数据源提供） | — |
| `area_code` | `string` | 行政区划代码 | — |
| `zip_code` | `string` | 邮编 | — |
| `city_code` | `string` | 城市电话区号 | — |
| `latitude` | `number` | 纬度 | — |
| `longitude` | `number` | 经度 | — |
| `elevation` | `number` | 海拔（米，备用数据源时为 null） | — |
| `time_zone` | `string` | 时区，如 Asia/Shanghai | — |
| `isp` | `string` | ISP / 运营商 | — |
| `risk` | `object` | 风险评分对象，含 level/score/is_proxy/proxy_probability 等 | — |
| `source` | `string` | 数据档位：primary（街道级 + 风险评分）或 backup（城市级基础信息） | — |

## 7. 响应示例

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

## 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.1.0** (2026-05-28)
  - 重构上游链路，大幅提升查询成功率和稳定性
  - 引入备用数据源，主数据源不可用时自动降级到城市级信息
  - 响应新增 data.source 字段：primary = 街道级 + 风险评分；backup = 城市级基础信息
  - 缓存策略：主数据源命中缓存 12h、备用数据源命中缓存 1h（更快尝试主源恢复）
- **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-07-18T10:38:08+08:00