开发接口文档

T0. 接口概览

T1. 单手机号查询

根据手机号或号段前缀查询归属地信息。

请求参数

调用示例

# GET + URL 参数
curl -X GET "https://ip.jwzcq.com/api/tel.php?action=query&tel=13800138000&key=sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# POST + form body
curl -X POST "https://ip.jwzcq.com/api/tel.php" \
  -H "X-API-Key: sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d "action=query&tel=13000001234"

# 前端 fetch
fetch("https://ip.jwzcq.com/api/tel.php?action=query&tel=13800138000&key=sk_demo_xxxxxxxxxxxxxxxxxxxxxxxx")
  .then(r => r.json())
  .then(data => console.log(data))

成功响应示例

{
  "code": 200,
  "success": true,
  "message": "success",
  "data": {
    "success": true,
    "code": 200,
    "message": "查询成功",
    "tel": "13000001234",
    "tel_length": 11,
    "segment": "1300000",
    "segment_int": 1300000,
    "found": true,
    "segment_range_start": "1300000",
    "segment_range_end":   "1300099",
    "segment_count":       100,
    "location": {
      "country": "中国",
      "region":  "山东",
      "city":    "济南",
      "county":  "",
      "isp":     "中国联通"
    },
    "extra": {
      "area_code":     "0531",
      "zip_code":      "250000",
      "district_code": "370100",
      "code":          "130"
    },
    "full_location": "中国 山东 济南 中国联通",
    "query_time": "2026-08-11 14:23:42"
  },
  "timestamp": 1786419822
}

返回字段说明

T2. 批量查询

单次最多处理 100 个手机号，支持数组形式或逗号分隔形式提交。

请求参数

调用示例

# 数组形式（推荐）
curl -X POST "https://ip.jwzcq.com/api/tel.php?action=batch" \
  -H "X-API-Key: sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d "tels[]=13800138000&tels[]=13000001234&tels[]=18912345678"

# 逗号分隔形式
curl -X POST "https://ip.jwzcq.com/api/tel.php?action=batch" \
  -d "tels=13800138000,13000001234,15500000000"

T3. 健康检查（免 Key）

用于监控 / Nginx 健康检测 / 开机自检，无需 Key。

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

// 返回
{
  "code": 200,
  "success": true,
  "data": {
    "status": "ok",
    "db":     "ok",
    "table":  "tel_location",
    "count":  522410,
    "time":   "2026-08-11 14:30:00"
  }
}

G0 接口概览

G1 地理编码（地址 → 经纬度）

将结构化地址（省市区+门址）解析为经纬度坐标，坐标系为天地图 CGCS2000。

请求参数

调用示例

# GET（URL 参数）
curl -X GET "https://ip.jwzcq.com/api/geo.php?action=geocode&address=%E5%B9%BF%E5%B7%9E%E5%B8%82%E5%A4%A9%E6%B2%B3%E5%8C%BA%E7%8F%A0%E6%B1%9F%E6%96%B0%E5%9F%8E%E8%8A%B1%E5%9F%8E%E5%B9%BF%E5%9C%BA&key=sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# POST + form body + Header 传 key（推荐）
curl -X POST "https://ip.jwzcq.com/api/geo.php" \
  -H "X-API-Key: sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d "action=geocode&address=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%B5%B7%E6%B7%80%E5%8C%BA%E8%8E%B2%E8%8A%B1%E6%B1%A0%E8%A5%BF%E8%B7%AF28%E5%8F%B7"

# 前端 fetch
fetch("https://ip.jwzcq.com/api/geo.php?action=geocode&address=%E4%B8%8A%E6%B5%B7%E5%B8%82%E6%B5%A6%E4%B8%9C%E6%96%B0%E5%8C%BA%E9%99%86%E5%AE%B6%E5%98%B4%E7%8E%AF%E8%B7%AF1000%E5%8F%B7&key=sk_demo_xxx")
  .then(r => r.json())
  .then(json => console.log(json.data.lon, json.data.lat))

成功响应示例

{
  "code": 200,
  "success": true,
  "message": "success",
  "type": "geocode",
  "data": {
    "address": "广州市天河区珠江新城花城广场",
    "lon": 113.318470,
    "lat": 23.123650,
    "level": "兴趣点",
    "score": 100
  },
  "query_time": "2026-08-20 15:30:54",
  "timestamp": 1787209854
}

返回字段说明

G2 逆地理编码（经纬度 → 地址）

根据经纬度坐标反查结构化地址、POI、道路、城市、区县及最近 POI 方位距离等信息。

请求参数

调用示例

# GET（天安门坐标）
curl -X GET "https://ip.jwzcq.com/api/geo.php?action=reverse&lon=116.397428&lat=39.90923&key=sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# POST（别名 revgeocode）
curl -X POST "https://ip.jwzcq.com/api/geo.php" \
  -H "X-API-Key: sk_demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d "action=revgeocode&lon=113.318470&lat=23.123650"

成功响应示例

{
  "code": 200,
  "success": true,
  "message": "success",
  "type": "reversegeocode",
  "data": {
    "lon": 116.397428,
    "lat": 39.909230,
    "formatted_address": "北京市东城区东华门街道天安门",
    "city": "北京市",
    "address": "天安门",
    "road": "东长安街",
    "poi": "天安门广场",
    "poi_distance": 120,
    "poi_position": "东北"
  },
  "query_time": "2026-08-20 15:32:00",
  "timestamp": 1787209920
}

返回字段说明

G3 健康检查（免 Key）

用于监控 / 开机自检，检查天地图 Key 配置状态、Redis 缓存连接情况及版本信息，无需 API Key。

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

// 返回
{
  "code": 200,
  "success": true,
  "message": "pong",
  "data": {
    "status":        "ok",
    "version":       "1.0.0",
    "tk_configured":true,
    "redis":        true,
    "redis_stats":  { /* 命中/未命中统计 */ },
    "time":          "2026-08-20 15:35:00",
    "timestamp":     1787210100
  }
}

G4 🗺️ 地图标注嵌入页（iframe）免 Key

返回一个可直接嵌入 iframe 的完整 HTML 地图页面。支持传入地址自动地理编码定位，也支持传入经纬度直接标注。 地图标注点可点击拖动调整位置，内置坐标复制、信息窗展示、postMessage 双向通信等功能，适合后台管理面板、表单详情页、位置展示等场景，无需自行对接天地图 JS API。

请求参数

📌 在线调用实例（点击即可体验）

嵌入示例

<!-- ① 地址模式：只需传 address，自动地理编码（推荐）-->
<iframe
  src="https://ip.jwzcq.com/api/geo.php?action=map&address=%E9%87%8D%E5%BA%86%E5%B8%82%E4%B8%A4%E6%B1%9F%E6%96%B0%E5%8C%BA%E6%B4%8B%E6%B2%B3%E8%B7%AF9%E5%8F%B7&title=公司地址"
  width="100%" height="450"
  frameborder="0" allowfullscreen
  style="border-radius:12px; box-shadow:0 2px 12px rgba(0,0,0,.08);">
</iframe>

<!-- ② 坐标模式：直接指定经纬度 -->
<iframe id="mapFrame" width="600" height="400" frameborder="0"></iframe>

// JS 动态加载（地址模式）
function showAddressMap(address, title) {
  var url = "https://ip.jwzcq.com/api/geo.php?action=map"
          + "&address=" + encodeURIComponent(address)
          + "&title=" + encodeURIComponent(title || "标注位置");
  document.getElementById("mapFrame").src = url;
}
// 调用：showAddressMap("重庆市两江新区洋河路9号", "公司地址");

postMessage 双向通信

嵌入页面后，父窗口可通过 postMessage 与地图交互：

① 子页面 → 父页面（坐标变化通知）

地图加载完成和用户点击移动标注后，iframe 会向父窗口发送消息：

// 父页面监听坐标变化
window.addEventListener("message", function(e) {
  if (e.data && e.data.type === "geo_mark") {
    console.log("标注坐标：", e.data.lon, e.data.lat);
    // e.data.lon     = 经度（Number）
    // e.data.lat     = 纬度（Number）
    // e.data.coord   = "lon,lat" 字符串
    // e.data.address = 原始地址（地址模式下有值）
  }
});

② 父页面 → 子页面（远程设置标注点）

父页面可发送消息远程更新标注点位置（无需刷新 iframe）：

var frame = document.getElementById("mapFrame");
// 动态更新标注点到上海东方明珠
frame.contentWindow.postMessage({
  type: "geo_set_marker",
  lon: 121.499809,
  lat: 31.239666,
  zoom: 16   // 可选
}, "*");

页面功能特性

• 🆕 地址自动定位：传入 address 或 content 参数，服务端自动调用天地图地理编码，无需前端转换
• 🆕 点击移动标注：默认开启（pickable=true），点击地图任意位置即可移动标注点，实时更新信息窗和坐标
• 天地图矢量底图 + 中文注记，全屏铺满 iframe，支持滚轮缩放 / 拖拽 / 双击放大
• 信息窗内置"📋 复制坐标"和"🎯 居中"按钮，一键复制当前标注坐标到剪贴板
• 右上角半透明毛玻璃坐标栏，实时显示当前标注点经纬度
• 地址解析失败时显示友好错误页面（不会白屏）
• postMessage 双向通信：子页面通知坐标变化，父页面可远程设置标注点
• 左上角蓝色提示条（点击移动标注时自动消失），顶部 Toast 通知交互反馈
• 响应式自适应 iframe 尺寸，移动端可正常使用
• 传 pickable=0 可禁用点击移动，变为纯展示模式

G5 📍 坐标拾取嵌入页（iframe）免 Key

返回一个可嵌入 iframe 的交互式地图页面，用户可以在地图上点击任意位置拾取坐标。支持 postMessage 实时回传坐标、callback URL 跳转回传、一键复制坐标等功能，非常适合表单中的"地图选点"场景。

请求参数

📌 在线调用实例（点击即可体验）

坐标回传方式

拾取页支持两种方式将坐标传回父页面，可同时使用：

① postMessage（推荐，适合 iframe 嵌入场景）

用户在地图上点击拾取坐标或点击"✅ 确认坐标"按钮后，iframe 会向父窗口发送 postMessage：

// 父页面监听坐标回传
window.addEventListener("message", function(e) {
  if (e.data && e.data.type === "geo_pick") {
    console.log("拾取坐标：", e.data.lon, e.data.lat, e.data.coord);
    // e.data.lon   = 经度（Number）
    // e.data.lat   = 纬度（Number）
    // e.data.coord = "lon,lat" 字符串（6位小数）
    document.getElementById("lonInput").value = e.data.lon.toFixed(6);
    document.getElementById("latInput").value = e.data.lat.toFixed(6);
  }
});

② Callback URL 跳转（适合弹窗 / 新窗口场景）

传入 callback 参数后，用户点击"确认"会跳转到该 URL 并将坐标作为 query 参数附加：

<!-- 传入 callback，确认后跳回表单页 -->
<iframe src="https://ip.jwzcq.com/api/geo.php?action=picker&lon=113.318&lat=23.123&callback=https%3A%2F%2Fip.jwzcq.com/geo_form.php&lon_field=lng&lat_field=lat"
        width="800" height="500" frameborder="0">
</iframe>

// 确认后跳转至：https://ip.jwzcq.com/geo_form.php?lng=113.318470&lat=23.123650

页面交互说明

• 鼠标在地图上移动时，底部坐标栏实时显示当前位置经纬度
• 点击地图任意位置：放置红色标记，弹出信息窗显示坐标，"确认坐标"按钮出现
• 信息窗内"📋 复制"按钮：一键复制坐标（格式 lon,lat）到剪贴板
• 信息窗内"✅ 确认"按钮：触发 postMessage + callback 跳转
• 底部"✅ 确认坐标"按钮：与信息窗确认按钮功能相同
• 支持滚轮缩放、拖拽平移、双击放大
• X-Frame-Options: SAMEORIGIN，仅允许同源嵌入；如需跨域嵌入可通过反向代理

完整集成示例

<!-- HTML：表单中嵌入坐标拾取 -->
<div class="form-row">
  <label>经度：<input type="text" id="formLon" readonly></label>
  <label>纬度：<input type="text" id="formLat" readonly></label>
  <button type="button" onclick="openPicker()">📍 地图选点</button>
</div>
<iframe id="pickerFrame" style="display:none;width:100%;height:450px;border:1px solid #ddd;border-radius:8px;"></iframe>

<script>
function openPicker() {
  var lon = document.getElementById("formLon").value || 116.397;
  var lat = document.getElementById("formLat").value || 39.909;
  var f = document.getElementById("pickerFrame");
  f.src = "https://ip.jwzcq.com/api/geo.php?action=picker&zoom=14&lon="+lon+"&lat="+lat;
  f.style.display = "block";
}
window.addEventListener("message", function(e) {
  if (e.data && e.data.type === "geo_pick") {
    document.getElementById("formLon").value  = e.data.lon.toFixed(6);
    document.getElementById("formLat").value  = e.data.lat.toFixed(6);
    document.getElementById("pickerFrame").style.display = "none";
  }
});
</script>