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

Ham Radio Spotting API

Spot yourself, or the stations you hear, from your logging app, a Discord bot, a script, a Stream Deck button, or a Raspberry Pi in the shack, using one HTTP request. Spots show up on SpottedHam, trigger email alerts, appear on club boards, and go out on the SpottedHam DX cluster.

Quick start on Spotting

  1. Sign in (Google or email magic link, at the top of this page), then open API Keys from your callsign menu and create a key. Tick Allow this key to spot other stations if you want it to spot more than just you.
  2. Send a POST to https://www.spottedham.com/api/v1/spot with your key, a frequency and a mode.
  3. Check the board. A self-spot is pinned to the top.

Pick the example for where you type it. Command Prompt, PowerShell and Mac/Linux all quote things differently, so copying the wrong one is the most common reason a first try fails.

Windows, Command Prompt
curl -X POST https://www.spottedham.com/api/v1/spot -H "Authorization: Bearer sh_your_key_here" -H "Content-Type: application/json" -d "{\"frequency\": 14.244, \"mode\": \"SSB\", \"ref\": \"US-1234\", \"comment\": \"POTA, QRP 5w\"}"
Windows, PowerShell
Invoke-RestMethod -Method Post -Uri https://www.spottedham.com/api/v1/spot -Headers @{ Authorization = "Bearer sh_your_key_here" } -ContentType "application/json" -Body '{"frequency": 14.244, "mode": "SSB", "ref": "US-1234", "comment": "POTA, QRP 5w"}'

In Windows PowerShell, curl is a different command, so use Invoke-RestMethod (or type curl.exe with the Command Prompt example).

Mac, Linux, Raspberry Pi
curl -X POST https://www.spottedham.com/api/v1/spot \
  -H "Authorization: Bearer sh_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"frequency": 14.244, "mode": "SSB", "ref": "US-1234", "comment": "POTA, QRP 5w"}'

Endpoint

POST https://www.spottedham.com/api/v1/spot

Send JSON (Content-Type: application/json) or a normal form post (application/x-www-form-urlencoded). Pass your key in one of these ways, in order of preference:

  • Authorization: Bearer sh_...
  • X-API-Key: sh_...
  • An api_key field in the body, for tools that can't set headers.

Fields

FieldNotes
frequencyrequiredMHz (14.074) or kHz (14074). Values over 1000 are read as kHz. Use frequency_khz or frequency_mhz to be explicit. Optional for EchoLink, AllStar and other VoIP self-spots.
moderequiredSSB, CW, FT8, FT4, FM, VARAC, ECHOLINK… USB, LSB and PHONE are stored as SSB.
callsignoptionalWho you are spotting. Defaults to your callsign. Portable forms count as you: N0CALL/P, W6/N0CALL. Any other callsign is a spot of another station.
refoptionalPark, summit, or grid: US-1234, W6/CT-001, CM97. park, summit and grid are accepted as aliases.
commentoptionalUp to 120 characters.
qthoptionalLocation text, up to 60 characters.
net_nameoptionalMarks the spot as a net, and it shows the NET badge.
bandoptionalWorked out from the frequency if you leave it out. Ignored for spots of other stations (always taken from the frequency).
clientoptionalName of your app or script, e.g. "my-pi-script". It helps us see which integrations people use.

The spotter is always the owner of the key. It can't be set in the request. If the same callsign is spotted again within an hour, the existing spot is updated rather than duplicated, the same as spotting on the website.

Sample JSON body
{
  "callsign": "N0CALL/P",
  "frequency": 14.062,
  "mode": "CW",
  "ref": "US-1234",
  "comment": "CQ POTA, QRP 5W",
  "qth": "Mt. Diablo SP",
  "client": "My logger 1.0"
}

Spotting other stations

A key can spot other stations once you turn on Allow this key to spot other stations for it on your API Keys page (when you create it, or later with the Allow others button). Without it, spotting another callsign is refused with a 422 that tells you where to turn it on.

Spots of other stations work a little differently from self-spots:

  • You are the spotter. Your callsign is shown as the spotter, marked via API.
  • Not pinned. They're shown like DX cluster spots, not pinned to the top of the board like member self-spots. (If you update a spot that was already pinned, it stays pinned.)
  • Real frequency required. The frequency must be inside an amateur band, from 160m to 23cm. Frequency 0 isn't allowed, so VoIP modes need the RF frequency of the node or repeater.
  • Real callsign required. Callsigns need letters and a digit, like K1ABC or VP2E/K1ABC.
  • Duplicates are ignored. Spotting the same station within 1 kHz of the same frequency again within 10 minutes returns 200 with "action": "duplicate" and posts nothing. Treat that as success, so a bot never loops on retries.
  • They go out on the SpottedHam DX cluster and trigger matching email alerts, like any other spot.

Good spotting etiquette: only spot stations you (or your club's operators) actually heard, on the frequency you heard them. Don't respot the same station over and over, and don't let a decoder script spot everything it hears. Keys that are abused get disabled.

curl -X POST https://www.spottedham.com/api/v1/spot \
  -H "Authorization: Bearer sh_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"callsign": "K1ABC", "frequency": 7.030, "mode": "CW", "comment": "599 into CA"}'

Limits

Per keySelf-spotsOther stations
Time between spots30 seconds10 seconds
Per hourno separate limit60
Per 24 hours200300

The two are counted separately. New keys (under 7 days old or under 20 accepted spots) get half the limits for other stations. Over a limit you get 429 with a Retry-After header saying how many seconds to wait. A GET with your key shows your current limits and usage.

Responses

HTTP 201
{
  "ok": true,
  "action": "created",
  "id": 7961402,
  "spot": { "callsign": "N0CALL", "frequency_mhz": 14.244, "band": "20m", "mode": "SSB",
            "ref": "US-1234", "comment": "POTA, QRP 5w", "spotter": "N0CALL",
            "source": "manual", "spotted_utc": "2026-11-21T17:02:11Z" },
  "view_url": "https://www.spottedham.com/?q=N0CALL"
}

"action" is "created" (201), "updated" (200, the callsign was already on the board in the last hour) or "duplicate" (200, nothing posted). "source" is "manual" for self-spots and "api" for spots of other stations.

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

  • 401: the key is missing, wrong, or revoked.
  • 403: the key has been disabled. error says why.
  • 422: a field needs fixing. fields says which one.
  • 429: slow down. Wait the number of seconds in the Retry-After header.
  • 500 / 503: our problem. Try again in a minute.

To check a key without spotting, send a GET to the same URL with the key. You get back your callsign, whether the key can spot other stations, and your current usage for both kinds of spots.

More examples

Python

import requests

r = requests.post(
    "https://www.spottedham.com/api/v1/spot",
    headers={"Authorization": "Bearer sh_your_key_here"},
    json={"frequency": 7.030, "mode": "CW", "ref": "W6/CT-001",
          "comment": "SOTA, QRV for 30 min", "client": "my-pi-script"},
    timeout=10,
)
data = r.json()
if r.status_code == 429:
    print("Rate limited, wait", r.headers.get("Retry-After"), "seconds")
elif data.get("ok"):
    print(data["action"], data.get("view_url"))   # created / updated / duplicate
else:
    print(r.status_code, data["error"], data.get("fields"))

PowerShell (multi-line, for scripts)

$body = @{ frequency = 146.520; mode = "FM"; comment = "Simplex, monitoring" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "https://www.spottedham.com/api/v1/spot" `
  -Headers @{ Authorization = "Bearer sh_your_key_here" } `
  -ContentType "application/json" -Body $body

JavaScript

const res = await fetch("https://www.spottedham.com/api/v1/spot", {
  method: "POST",
  headers: { "Authorization": "Bearer sh_your_key_here", "Content-Type": "application/json" },
  body: JSON.stringify({ frequency: 14074, mode: "FT8", comment: "CQ from the backyard" })
});
console.log(res.status, await res.json());

Don't put your key in JavaScript on a public web page. Anyone can read it there. Call the API from a server, script or app instead.

Ideas

  • Raspberry Pi / shack computer: read your rig's frequency from flrig, rigctld or Hamlib, and spot yourself when you start calling CQ.
  • Stream Deck or a phone shortcut: one button that spots you on your usual park frequency.
  • Home Assistant: spot yourself when the rig powers on.
  • Discord or club bots: a /spot command that lets club members post the stations they work, using a key that can spot other stations.
  • Logging app developers: add SpottedHam next to your POTA and SOTA spot options, for self-spots and hunter spots. Email us and we'll list your app here.

Reading spots

This API posts spots. To read them, use the Ham Radio Spots API: GET https://www.spottedham.com/api/v1/spots returns the live feed (DX cluster, POTA, SOTA, member and API spots) as JSON, filtered by band, mode, callsign, park or summit. No key is needed. Bots typically use both: read the feed to post new spots into a chat, and this API to spot from a chat command.

FAQ

Is it free?

Yes. Sign in, create a key, and start spotting.

Can I spot other stations?

Yes, with a key that has Allow this key to spot other stations turned on. See Spotting other stations for the rules and limits. You can also spot anyone on the SpottedHam website.

Where do my spots go?

To the SpottedHam board, to anyone with a matching email alert, to club boards and embedded widgets, and to the SpottedHam DX cluster. Self-spots are pinned to the top of the board with the member spots.

I got "duplicate". Did it fail?

No. You already spotted that station on that frequency in the last 10 minutes, so the spot is already on the board. Nothing else to do.

I leaked my key. What now?

Revoke it on your API keys page. It stops working right away. Then create a new one.

Get your API key · Read spots with the Spots API · More about ham radio spots and DX cluster commands.

NOTE