Logo, can of SpottedHam, Spotted ham makes it easy to share your location on the bands in real-time.

Ham Radio Spots API

Get the live SpottedHam spot feed as JSON: DX cluster, POTA, SOTA and member spots, filtered the way you want. Use it for a Discord bot, a club web page, a dashboard in the shack, or a Google Sheet. No key needed.

Quick start

Send a GET to https://www.spottedham.com/api/v1/spots. That's it, no sign-up. This gets the 10 newest 20m FT8 spots:

curl "https://www.spottedham.com/api/v1/spots?band=20m&mode=FT8&limit=10"

Works as-is in Command Prompt, PowerShell (type curl.exe), Mac, Linux and Raspberry Pi. Keep the double quotes, or the & breaks the command. You can also open the URL in a browser to look at the data.

Endpoint

GET https://www.spottedham.com/api/v1/spots

You get the latest version of each spot from the last 12 hours, newest first. A station that was spotted several times shows up once, with its latest frequency and comment.

Query parameters

All optional. Combine as many as you like; a spot must match all of them. Lists are comma-separated, and a list matches any value in it. Case doesn't matter.

ParameterExampleNotes
bandband=20m,40mBands like 160m … 23cm, plus VOIP.
modemode=CW,FT8SSB also matches spots reported as USB or LSB, and they come back as SSB.
callsigncallsign=3Y0J,KM6HBH/PExact callsigns of the stations spotted. Portable forms are separate callsigns, so list each one you want.
spotterspotter=W6ABCExact callsign of who made the spot.
refref=US-
ref=W6/CT
Starts-with match on the park, summit or grid. US- = every US park, US-1234 = one park, W6/CT = one SOTA region. DX cluster spots have no ref, so they never match.
sourcesource=pota,sotaWhere the spot came from: member (spotted on SpottedHam, including self-spots), pota, sota, cluster (DX cluster), api (posted with the spotting API).
sincesince=2026-11-21T17:00:00Z
since=1763744400
Only spots newer than this. ISO 8601 in UTC, or unix seconds. See polling.
since_idsince_id=13976440Only spots with a higher id than this. Optional extra for polling, see below.
limitlimit=100How many spots to return. Default 50, maximum 200.

More examples:

Response

A real response for ?source=pota&limit=2:

{
  "ok": true,
  "count": 2,
  "generated_utc": "2026-11-22T02:53:53Z",
  "spots": [
    {
      "id": 13976440,
      "callsign": "KC4/KL5SE",
      "frequency_mhz": 14.243,
      "band": "20m",
      "mode": "SSB",
      "ref": "AQ-0077",
      "comment": "SSB",
      "qth": "AQ-AQ",
      "net_name": null,
      "spotter": "KL5SE",
      "source": "pota",
      "spotted_utc": "2026-11-22T02:46:59Z",
      "url": "https://www.spottedham.com/?q=KC4%2FKL5SE"
    },
    {
      "id": 13976441,
      "callsign": "DS2MGT",
      "frequency_mhz": 7.013,
      "band": "40m",
      "mode": "CW",
      "ref": "KR-0375",
      "comment": "STARTING POTA ACTIVATION",
      "qth": "KR-KG",
      "net_name": null,
      "spotter": "DS2MGT",
      "source": "pota",
      "spotted_utc": "2026-11-22T02:46:27Z",
      "url": "https://www.spottedham.com/?q=DS2MGT"
    }
  ]
}
FieldNotes
idSpot id. A respot of the same station gets a new id.
frequency_mhzAlways MHz. 0 for EchoLink/AllStar/VoIP spots.
refPark (POTA), summit (SOTA) or grid. Empty if none.
comment, qthPlain text. If you put them in a web page, escape them like any other user text.
net_nameName of the net for net spots, otherwise null.
sourcemember, pota, sota, cluster or api, same names as the filter.
spotted_utcWhen the spot was made or last updated, ISO 8601 UTC.
urlThe station on the SpottedHam board. Please link each callsign to it (see Using the feed on your site).

Errors come back as {"ok": false, "error": "...", "fields": {...}}:

  • 400: a parameter isn't valid. fields says which one.
  • 401 / 403: the API key you sent is wrong, revoked or disabled. Leave the key out and the feed still works.
  • 429: too many requests. Wait the number of seconds in the Retry-After header.
  • 500 / 503: our problem. Try again in a minute.

Rate limits and caching

Requests per minuteCounted per
No key5IP address
With a free API key30key

Every response has X-RateLimit-Limit and X-RateLimit-Remaining headers. Over the limit you get 429 with Retry-After. To use a key, send it the same way as for spotting: Authorization: Bearer sh_... or X-API-Key: sh_.... A key that is only used to read never needs the "spot other stations" option.

Successful responses are cached for 15 seconds, on our server and in your browser or proxy (Cache-Control: public, max-age=15). Asking the same question more often than that gets you the same data, and still counts toward your rate limit. The X-Cache header says HIT for a cached answer and MISS for a fresh one. Errors are never cached. CORS is open (Access-Control-Allow-Origin: *), so web pages on any site can call the API directly.

Using the feed on your site

If you show SpottedHam spots publicly (a website, a Discord or Slack channel, an app, a dashboard on a club screen), please:

  • Credit SpottedHam with a link to https://www.spottedham.com/, near where the spots are shown.
  • Link each callsign to its url, so people can see the station on the live board.

It's a request, not a legal requirement. It keeps the feed free, and it helps other hams find the board. Copy one of these:

Website (HTML)
Spots from <a href="https://www.spottedham.com/">SpottedHam</a>
Discord, Slack, GitHub (Markdown)
Spots from [SpottedHam](https://www.spottedham.com/)
Plain text (apps, printouts)
Spots from SpottedHam.com

Polling for new spots

For a bot or a live display, ask every 30 to 60 seconds and pass since so you only get what's new. Two tips:

  • Spots are sorted by spotted_utc, and some feeds (POTA) report a spot a little after it was made. Ask for a minute or two of overlap, and skip ids you've already seen. The Python example below does exactly that.
  • since_id is an alternative that never misses a newly added spot, but a few spot updates keep their id, so since with overlap is the safer default.

Examples

curl

curl "https://www.spottedham.com/api/v1/spots?source=pota&ref=US-&mode=CW&limit=20"

# with a key (higher limit)
curl -H "Authorization: Bearer sh_your_key_here" "https://www.spottedham.com/api/v1/spots?limit=200"

Python: polling loop

import time
from datetime import datetime, timedelta, timezone
import requests

URL = "https://www.spottedham.com/api/v1/spots"
FILTERS = {"source": "pota,sota", "band": "20m,40m"}   # change to taste
seen = {}                                   # spot id -> spotted time
last = datetime.now(timezone.utc) - timedelta(minutes=10)

while True:
    since_dt = last - timedelta(minutes=2)  # 2 min overlap for late-arriving spots
    r = requests.get(URL, params={**FILTERS, "since": since_dt.strftime("%Y-%m-%dT%H:%M:%SZ"),
                                  "limit": 200}, timeout=10)
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", 60)))
        continue
    r.raise_for_status()
    for s in reversed(r.json()["spots"]):  # oldest first
        if s["id"] in seen:
            continue
        t = datetime.fromisoformat(s["spotted_utc"].replace("Z", "+00:00"))
        seen[s["id"]] = t
        last = max(last, t)
        print(f'{s["spotted_utc"]}  {s["callsign"]:<10} {s["frequency_mhz"]:>9}  {s["mode"]:<4} {s["ref"]}  {s["comment"]}')
    seen = {i: t for i, t in seen.items() if t >= since_dt}   # forget ids outside the overlap
    time.sleep(60)

JavaScript: live spots on a club website

Paste this into any page. It shows your members' spots and refreshes every minute. Text is added with textContent, so comments can't inject HTML into your page.

<div id="sh-spots">Loading spots…</div>
<p style="font-size:small">Spots from <a href="https://www.spottedham.com/">SpottedHam</a></p>
<script>
const SH_CALLS = "W6ABC,K6XYZ,N6QRP";   // your members
async function loadSpots() {
  const box = document.getElementById("sh-spots");
  try {
    const res = await fetch("https://www.spottedham.com/api/v1/spots?limit=20&callsign=" + encodeURIComponent(SH_CALLS));
    const data = await res.json();
    box.textContent = "";
    if (!data.ok || data.count === 0) { box.textContent = "No member spots right now."; return; }
    for (const s of data.spots) {
      const row = document.createElement("div");
      const a = document.createElement("a");
      a.href = s.url; a.textContent = s.callsign;
      row.append(a, ` ${s.frequency_mhz} MHz ${s.mode} ${s.ref} ${s.comment} (${new Date(s.spotted_utc).toLocaleTimeString()})`);
      box.append(row);
    }
  } catch (e) { box.textContent = "Spots unavailable right now."; }
}
loadSpots();
setInterval(loadSpots, 60000);
</script>

Don't put an API key in a public web page; anyone can read it there. The 5-per-minute limit is per visitor's IP, so a public page doesn't need a key. Want a styled board with no code? Use the free club widget.

Google Sheets

The feed is JSON, and IMPORTDATA only reads CSV, so use a small Apps Script. In your sheet: Extensions → Apps Script, paste this, save, and run loadSpots (allow access the first time). To refresh it automatically, add a time-driven trigger (the clock icon) that runs it every 5 or 10 minutes.

function loadSpots() {
  const url = "https://www.spottedham.com/api/v1/spots?source=pota&ref=US-&limit=100";
  const data = JSON.parse(UrlFetchApp.fetch(url).getContentText());
  const rows = [["Spotted (UTC)", "Callsign", "MHz", "Band", "Mode", "Ref", "Comment", "Spotter", "Link"]];
  data.spots.forEach(s => rows.push([s.spotted_utc, s.callsign, s.frequency_mhz, s.band,
                                     s.mode, s.ref, s.comment, s.spotter, s.url]));
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
  sheet.clearContents();
  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
}

FAQ

Is it free?

Yes, for personal projects, club websites, bots and apps.

Do I need an API key?

No. Without a key you get 5 requests per minute per IP address, which is plenty for polling. A free API key raises it to 30 per minute, for servers that make many different queries.

How often should I poll?

Every 30 to 60 seconds. Responses are cached for 15 seconds, so faster polling just returns the same data. Use since to only fetch what's new (see polling).

Can I show these spots on my website?

Yes. CORS is open, so the JavaScript example above works on any site. Please credit SpottedHam with a link and link each callsign to its url; there's a copy-paste credit line under Using the feed on your site. For a ready-made board, use the club widget.

How far back does it go?

The last 12 hours, latest version of each spot. For older history, use the board's history view.

Can I post spots too?

Yes, with the spotting API: spot yourself, or other stations with a key that allows it.

Related: Spotting API · Ham radio spots · Club widget · DX cluster commands

NOTE