接口文档

查询接口

返回格式

响应均为 application/json。GET 返回单个对象；POST 批量返回{"results":[...]}，结果顺序与请求一致，每项结构相同， 共 20+ 个字段（见下表）。

# GET https://api.ip.denys.cn/v1/query?ip=223.5.5.5
{
  "ip": "223.5.5.5",
  "found": true,
  "country": "中国",
  "province": "浙江省",
  "city": "杭州市",
  "isp": "阿里",
  "country_code": "CN",
  "is_china_mainland": true,
  "region": "mainland",
  "continent_code": "AS",
  "phone_prefix": "+86",
  "china_province_code": "330000",
  "province_pinyin": "zhejiang",
  "province_short_code": "ZJ",
  "province_abbr": "浙",
  "china_region": "华东",
  "city_code": "hangzhou",
  "city_short_code": "HZ",
  "city_area_code": "0571",
  "china_city_code": "330100",
  "timezone": "Asia/Shanghai",
  "asn": 45102,
  "as_org": "ALIBABA-CN-NET Alibaba US Technology Co., Ltd."
}

# GET https://api.ip.denys.cn/v1/query?ip=2400:3200::1
{
  "ip": "2400:3200::1",
  "found": true,
  "country": "中国",
  "province": "浙江省",
  "city": "杭州市",
  "isp": "阿里",
  "country_code": "CN",
  "is_china_mainland": true,
  "region": "mainland",
  "continent_code": "AS",
  "phone_prefix": "+86",
  "china_province_code": "330000",
  "province_pinyin": "zhejiang",
  "province_short_code": "ZJ",
  "province_abbr": "浙",
  "china_region": "华东",
  "city_code": "hangzhou",
  "city_short_code": "HZ",
  "city_area_code": "0571",
  "china_city_code": "330100",
  "timezone": "Asia/Shanghai",
  "asn": 45102,
  "as_org": "ALIBABA-CN-NET Alibaba US Technology Co., Ltd."
}

港澳台说明：香港、澳门、台湾的 IP 统一返回 country=中国、country_code=CN，以 province 区分： 香港特别行政区、澳门特别行政区、台湾省（city 为空）。判断是否中国大陆请直接用 is_china_mainland 字段（或 region 字段：mainland/hk/mo/tw/overseas），无需自己维护省份名单； 国际电话区号也已按地区区分（大陆 +86 / 香港 +852 / 澳门 +853 / 台湾 +886）。

未命中示例：{"ip":"10.0.0.1","found":false}（不计费）。 每次成功（200）响应带 X-Quota-Remaining 头，为本次扣减后的剩余次数。

鉴权

所有请求需携带请求头 X-API-Key: ipk_your_key（key 在控制台创建）。也支持 ?key= 查询参数，但会进入访问日志，不建议使用。

计费规则

• 仅查询命中（found=true）的结果计费；未命中或 IP 格式非法不计费。
• GET 单次最多计 1 次；POST 批量按响应中 found=true 的个数计费，余量不足时扣至 0。
• 每次成功（200）响应均带 X-Quota-Remaining 响应头，表示本次扣减后的剩余次数。
• 次数长期有效，不设有效期。

错误码

调用示例

# 单个查询
curl 'https://api.ip.denys.cn/v1/query?ip=223.5.5.5' -H 'X-API-Key: ipk_your_key'

# IPv6 查询
curl 'https://api.ip.denys.cn/v1/query?ip=2400:3200::1' -H 'X-API-Key: ipk_your_key'

# 批量查询
curl -X POST 'https://api.ip.denys.cn/v1/query' \
  -H 'X-API-Key: ipk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"ips":["223.5.5.5","119.29.29.29"]}'

const res = await fetch('https://api.ip.denys.cn/v1/query?ip=223.5.5.5', {
  headers: { 'X-API-Key': 'ipk_your_key' },
})
const data = await res.json()
console.log('剩余次数:', res.headers.get('X-Quota-Remaining'))
console.log(data)

import requests

res = requests.get(
    "https://api.ip.denys.cn/v1/query",
    params={"ip": "223.5.5.5"},
    headers={"X-API-Key": "ipk_your_key"},
)
print(res.json())
print("剩余次数:", res.headers.get("X-Quota-Remaining"))

<?php
$ch = curl_init('https://api.ip.denys.cn/v1/query?ip=223.5.5.5');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['X-API-Key: ipk_your_key'],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $data['country'], ' ', $data['province'], ' ', $data['city'], PHP_EOL;

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest(http.MethodGet, "https://api.ip.denys.cn/v1/query?ip=223.5.5.5", nil)
	req.Header.Set("X-API-Key", "ipk_your_key")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]any
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data)
}

use reqwest::blocking::Client;

fn main() -> Result<(), Box<dyn std::error::Error>> {
	let text = Client::new()
		.get("https://api.ip.denys.cn/v1/query?ip=223.5.5.5")
		.header("X-API-Key", "ipk_your_key")
		.send()?
		.text()?;
	println!("{text}");
	Ok(())
}

AI 集成

本站提供 AI 友好的机器可读文档。把下面这段提示词发给你的 AI 编程助手（Claude Code / Cursor / ChatGPT 等），即可正确接入：

我在用 IP 查询 API：基础地址 https://api.ip.denys.cn，鉴权请求头 X-API-Key（密钥我稍后提供）。
写代码前先抓取 https://api.ip.denys.cn/llms-full.txt 阅读完整接口说明，严格按其中的端点、响应字段、计费规则与错误码实现。

MCP 远程端点（推荐）

本站提供无状态 MCP 服务（Streamable HTTP，端点 https://api.ip.denys.cn/mcp， 工具：ip_query / ip_batch /ip_quota），调用按次计费、规则与直调完全一致， 返回字段与 REST 接口相同（20+ 个，含归属地、区号、行政区划码、ASN 等）：

# Claude Code 等 CLI 工具（一行添加）
claude mcp add --transport http ip-geo https://api.ip.denys.cn/mcp --header "X-API-Key: ipk_your_key"

# Claude Desktop / Cursor 等（mcpServers JSON 配置）
{
  "mcpServers": {
    "ip-geo": {
      "url": "https://api.ip.denys.cn/mcp",
      "headers": { "X-API-Key": "ipk_your_key" }
    }
  }
}

机器可读入口：/llms.txt（站点索引）、/llms-full.txt（完整参考单文件版，推荐 AI 直接读取）。