HAM 池塘 · 开放接口

开放只读接口

把「现在谁在频率上」接进你的机器人、桌面小工具、HamClock 或者群里。全部免费、无需注册、不用 API Key。

先说清楚边界：这里只有读接口。打卡、修改、下线不对外开放（写接口要求同站来源，防止脚本刷假台）。 数据是用户自己上报的，不保证准确，请勿用于救援、航空、航海等任何安全相关用途。 频率请以当地法规和实际守听为准。

通用约定

接口清单

1. 在线打卡列表

GET/api/spots
参数说明
lat, lon你的位置。带上就会给每条记录补 distanceKm / bearing / bearingText。
maxKm只回这个半径内的点位（需同时带 lat/lon）。
band频段，如 2m / 70cm / 20m；all 或不传为全部。
mode模式：FM / SSB / CW / FT8 等。
statusCQ（在呼叫）/ QRV（可通联）/ QSO（通联中）。
callsign呼号前缀或片段，服务端做包含匹配。
limit条数，默认 200，上限 500。
since增量模式：传上次响应的 v，只回变化过的条目（含 {id, del:1} 删除标记）。
# 找 145.500 附近 50 公里内的 FM 台
curl "https://ham-spot.app.workbuddy.host/api/spots?lat=39.9042&lon=116.4074&maxKm=50&band=2m&mode=FM"

# 返回（节选）
{
  "ok": true,
  "data": {
    "v": 1793,
    "total": 1,
    "items": [{
      "id": "6f3a91c2",
      "callsign": "BG7XSS",
      "freq": 145.5, "band": "2m", "mode": "FM",
      "status": "CQ", "freqType": "simplex",
      "lat": 39.9, "lon": 116.41, "precision": 2,
      "antenna": "橡皮鸭", "power": "5W",
      "updatedAt": 1792240000000, "expiresAt": 1792247200000,
      "distanceKm": 1.2, "bearing": 87, "bearingText": "东"
    }]
  }
}

中继台：freqType 为 repeater 时，freq 等于下行， freqOut / freqIn / tone 分别是下行、上行、哑音。

2. 热门频率

GET/api/hot

当前守听人数最多的频率排行，适合做「今天大家都在哪」的小组件。

{ "ok": true, "data": { "alive": 42, "items": [
  { "freq": 145.5, "count": 9, "modes": { "FM": 9 } },
  { "freq": 438.5, "count": 5, "modes": { "FM": 5 } }
] } }

3. 站点配置

GET/api/config

频段表 bands、常用频率 callFreqs、模式/台型/功率/天线枚举、默认位置精度、打卡有效期上限等。做客户端时直接读这份，别在代码里抄一遍。

4. 实时统计

GET/api/stats

当前在线、今日峰值、今日打卡数、频段/模式分布。关于页用的就是它。

5. 传播指数

GET/api/solar

SFI / A / K / 黑子数 + 各波段白天夜间 Poor–Fair–Good（数据来源 HamQSL / N0NBH，服务端缓存 30 分钟）。 取不到时可能返回 503，或有 stale: true 的旧值。

6. 健康检查

GET/api/health

轻量、无副作用，给 UptimeRobot 之类的监控用：status / version / spots / online / mode。

7. App 下载信息

GET/api/app/info

当前安装包的版本号、大小、上传时间；/api/app/download 取文件本体。

最小可用示例

一个每 60 秒刷新、只显示 2 米波段在线台的小脚本：

// Node 18+ / 浏览器都行
const r = await fetch('https://ham-spot.app.workbuddy.host/api/spots?band=2m&limit=50')
const { data } = await r.json()
for (const s of data.items) {
  console.log(`${s.callsign} ${s.freq} MHz ${s.mode} ${s.status} · ${s.distanceKm ?? '?'} km`)
}

关于数据