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.
https://www.spottedham.com/api/v1/spot with your key, a frequency and a mode.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.
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\"}"
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).
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"}'
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_...api_key field in the body, for tools that can't set headers.| Field | Notes | |
|---|---|---|
frequency | required | MHz (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. |
mode | required | SSB, CW, FT8, FT4, FM, VARAC, ECHOLINK… USB, LSB and PHONE are stored as SSB. |
callsign | optional | Who 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. |
ref | optional | Park, summit, or grid: US-1234, W6/CT-001, CM97. park, summit and grid are accepted as aliases. |
comment | optional | Up to 120 characters. |
qth | optional | Location text, up to 60 characters. |
net_name | optional | Marks the spot as a net, and it shows the NET badge. |
band | optional | Worked out from the frequency if you leave it out. Ignored for spots of other stations (always taken from the frequency). |
client | optional | Name 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.
{
"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"
}
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:
0 isn't allowed, so VoIP modes need the RF frequency of the node or repeater.K1ABC or VP2E/K1ABC.200 with "action": "duplicate" and posts nothing. Treat that as success, so a bot never loops on retries.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"}'
| Per key | Self-spots | Other stations |
|---|---|---|
| Time between spots | 30 seconds | 10 seconds |
| Per hour | no separate limit | 60 |
| Per 24 hours | 200 | 300 |
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.
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.
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"))
$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
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.
/spot command that lets club members post the stations they work, using a key that can spot other stations.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.
Yes. Sign in, create a key, and start spotting.
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.
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.
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.
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.