开发接口文档

0. 基础规范

统一响应结构

// 成功
{
  "code": 200,
  "success": true,
  "message": "success",
  "data": { /* 业务数据结构 */ },
  "timestamp": 1715000000
}

// 失败
{
  "code": 400, // 400参数 404未找到 500服务器错
  "success": false,
  "message": "错误描述",
  "data": null
}

API Key 鉴权

业务状态码说明

HTTP 响应状态码

1. 单 IP 查询

请求参数

调用示例

# GET（key 写在 URL，最快联调。key 需到后台「API 密钥管理」创建，此处为示例占位）
curl -X GET "https://ip.jwzcq.com/api/ip.php?action=query&ip=8.8.8.8&key=sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Header 传 key（生产推荐，不进日志）
curl -X GET "https://ip.jwzcq.com/api/ip.php?ip=8.8.8.8" \
  -H "X-API-Key: sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# POST
curl -X POST "https://ip.jwzcq.com/api/ip.php" \
  -d "action=query&ip=8.8.8.8&key=sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 浏览器 JS (fetch)
fetch("https://ip.jwzcq.com/api/ip.php?action=query&ip=8.8.8.8&key=sk_demo_xxxxxxxxxxxxxxxxxxxxxxxx")
  .then(r => r.json())
  .then(json => console.log(json.data.location, json.data.full_location));

① 响应字段总览（外层 ApiResponse 结构）

② data（业务查询结果）字段详解

③ data.location（归属地标准化字段）

④ data.raw（数据库原始行，字段依 SQL 导入结果而定）

⑤ data._api_key（鉴权开启时附加，密钥配额快照）

完整响应示例（实际抓包结果）

{
  "code": 200,
  "success": true,
  "message": "success",
  "data": {
    "success": true,
    "code": 200,
    "message": "查询成功",
    "ip": "8.8.8.8",
    "ip_int": 134744072,
    "found": true,
    "start_ip": "8.8.8.8",
    "end_ip": "8.8.8.8",
    "start_ip_int": "134744072",
    "end_ip_int": "134744072",
    "location": {
      "country": "美国",
      "region": "加利福尼亚州",
      "city": "圣克拉拉",
      "county": "山景城",
      "isp": "谷歌公司DNS服务器",
      "owner": "",
      "base_station": ""
    },
    "full_location": "美国 加利福尼亚州 圣克拉拉 山景城 谷歌公司DNS服务器",
    "raw": {
      "id": "2403478",
      "start_ip": "8.8.8.8",
      "end_ip": "8.8.8.8",
      "start_ip_int": "134744072",
      "end_ip_int": "134744072",
      "country_name": "美国",
      "region_name": "加利福尼亚州",
      "city_name": "圣克拉拉",
      "district_name": "山景城",
      "owner_domain": "",
      "isp_domain": "谷歌公司DNS服务器",
      "country_code": "US",
      "continent_code": "NA"
    },
    "query_time": "2026-08-10 14:23:42",
    "_api_key": {
      "name": "IP查询",
      "owner": "博优科技",
      "daily_quota": 0,
      "used_today": 28,
      "expires_at": "",
      "reset_day": "2026-08-10"
    }
  },
  "timestamp": 1786343022
}

2. 批量 IP 查询

请求参数

调用示例

curl -X POST "https://ip.jwzcq.com/api/ip.php?action=batch" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "ips[]=8.8.8.8&ips[]=114.114.114.114&ips[]=1.1.1.1"

# 或者 JSON 方式
curl -X POST "https://ip.jwzcq.com/api/ip.php?action=batch" \
  -H "Content-Type: application/json" \
  -d '{"ips":"8.8.8.8,114.114.114.114"}'

3. 获取当前访问者 IP + 归属地

curl "https://ip.jwzcq.com/api/ip.php?action=myip"

4. 健康检查

curl "https://ip.jwzcq.com/api/ip.php?action=ping"

// 返回示例
{ "code":200, "data": {
    "status":"ok",
    "db":"ok",
    "count":3500000,
    "version":"1.0.0",
    "time":"2026-05-06 12:00:00"
} }

5. 各种语言调用示例

PHP (file_get_contents)

'

Warning:  file_get_contents(<?php echo htmlspecialchars($baseUrl); ?>/api/ip.php?ip=8.8.8.8): failed to open stream: No such file or directory in /disk/webroot/ip.jwzcq.com/api_docs.php on line 409



Notice:  Trying to access array offset on value of type null in /disk/webroot/ip.jwzcq.com/api_docs.php on line 411

'

JavaScript (jQuery AJAX)

$.ajax({
  url: "https://ip.jwzcq.com/api/ip.php",
  type: "GET",
  dataType: "json",
  data: { action: "query", ip: "8.8.8.8" },
  success: function(res) {
    if (res.success && res.data.found) {
      console.log(res.data.full_location);
    }
  }
});

Python (requests)

import requests

url = "https://ip.jwzcq.com/api/ip.php"
resp = requests.get(url, params={"action": "query", "ip": "8.8.8.8"})
data = resp.json()
if data["success"] and data["data"]["found"]:
    print(data["data"]["full_location"])