📍 关于接口
本服务提供两个 IP 地理位置查询端点：/api/iplocation 返回常规位置信息（国家、城市、经纬度等）；/api/iplocationdebug 额外返回调试字段（原始数据、处理耗时、地理数据库版本等），便于开发诊断。
所有响应均为 application/json 格式，支持通过查询参数指定 IP，不传则自动获取请求来源 IP。
🌐 基础地址 (Base URL)：
* 所有端点均以此前缀拼接，例如
https://api.yourservice.com* 所有端点均以此前缀拼接，例如
https://api.yourservice.com/api/iplocation。开发环境请替换为实际域名/IP。
📡 API 端点
| 方法 | 端点路径 | 描述 | 主要特点 |
|---|---|---|---|
| GET | /api/iplocation | 获取IP地理位置（标准模式） | 返回国家、地区、城市、坐标、时区等核心字段 |
| GET | /api/iplocationdebug | 获取IP地理位置（调试模式） | 包含标准字段 + debug元数据（原始数据、处理耗时、精度半径等） |
🔎 请求参数
两个端点均支持以下 查询字符串参数 (Query String)：
| 参数名 | 类型 | 必需 | 说明 |
|---|---|---|---|
ip | string | 可选 | IPv4 或 IPv6 地址，例如 8.8.8.8。不提供时自动获取客户端公网IP。 |
lang | string | 可选 | 返回语言，支持 zh-CN (默认) 或 en，影响国家/城市名称。 |
✅ 示例：GET /api/iplocation?ip=1.1.1.1&lang=en
📘 端点 ① — 标准 IP 定位
📎 请求示例 (GET /api/iplocation)
curl -X GET "https://api.yourservice.com/api/iplocation?ip=8.8.8.8" \ -H "Accept: application/json"
{
"status": "success",
"query": {
"ip": "8.8.8.8",
"lang": "zh-CN"
},
"location": {
"country": "美国",
"country_code": "US",
"region": "加利福尼亚",
"city": "山景城",
"latitude": 37.4056,
"longitude": -122.0775,
"timezone": "America/Los_Angeles",
"zip": "94043",
"isp": "Google LLC"
},
"confidence": "high"
}
📌 响应字段说明：status — 请求状态；location 包含地理位置详情；confidence 表示定位可信度。若IP无效或私有地址会返回相应错误。
🐞 端点 ② — 调试模式 IP 定位
🔧 请求示例 (GET /api/iplocationdebug)
curl -X GET "https://api.yourservice.com/api/iplocationdebug?ip=8.8.8.8&lang=en" \ -H "Accept: application/json"
{
"status": "success",
"query": {
"ip": "8.8.8.8",
"lang": "en"
},
"location": {
"country": "United States",
"country_code": "US",
"region": "California",
"city": "Mountain View",
"latitude": 37.4056,
"longitude": -122.0775,
"timezone": "America/Los_Angeles",
"zip": "94043",
"isp": "Google LLC"
},
"debug": {
"raw_data_source": "geoip2_city_mmdb",
"processing_time_ms": 12.3,
"accuracy_radius_km": 5,
"geo_db_version": "20260501",
"original_ip_type": "public_ipv4",
"flags": {
"is_mobile": false,
"is_proxy": false
}
}
}
🧪 debug 额外字段说明：processing_time_ms 服务端处理耗时；accuracy_radius_km 定位半径(km)；raw_data_source 地理库类型；original_ip_type IP属性。适合排查定位差异或性能分析。
⚠️ 常见错误响应
- ▪
400— IP 格式无效 - ▪
404— 无法定位该 IP (保留地址或未知) - ▪
429— 请求频率超限 - ▪
500— 服务内部错误
📦 默认行为说明
- ▪ 未提供
ip参数 → 自动获取请求来源 IP - ▪ IPv6 地址完全支持
- ▪ 所有时间戳均为 UTC+0
🧪 调试端点使用场景
- ▪ 对比不同 IP 的定位精度
- ▪ 监控响应性能指标
- ▪ 检查地理库版本是否最新
⚡ 快速测试 (本地模拟)
# 获取当前本机公网 IP 的位置（标准） curl https://api.yourservice.com/api/iplocation # 查询指定 IP (Cloudflare DNS) 并获取调试信息 curl "https://api.yourservice.com/api/iplocationdebug?ip=1.1.1.1&lang=zh-CN"