Build on Shacks On The Air

Everything you can see on this site is available through the official API: live spots, the shack list, activations, leaderboards, events, and your own log and awards. Loggers can post QSOs and spots directly.

Please don't scrape the website. The API is faster, stable, documented and fair to everyone. If something you need is missing, tell us and we'll add it.

Two ways in

Pick the one that fits what you're building.

🔑

API keys

Your own scripts & loggers

✔ Read public feeds: spots, shacks, activations, leaderboards, events
✔ Read and write your own log, post spots
✔ Instant: create a key in your account, no review
✘ Can't act for other operators

Get an API key Key API reference

🧩

OAuth apps

Third-party services, reviewed

✔ Other operators connect their SHOTA account to your service
✔ "Sign in with SHOTA": callsign, profile, shack and (optionally) email
✔ Logbook read/write/delete, spotting, awards, profile updates
✔ Show your own card on users' SHOTA dashboard and logs pages
✔ Each app is reviewed and scoped; each user approves what it can do

OAuth guide My apps Cards guide Developer Terms

🔑

Authentication

Create a key under Account → API keys and send it as Authorization: Bearer <key> or X-API-Key. Keys have read and/or write scopes.

⏱️

Rate limits

120 requests per minute per key. Responses include X-RateLimit-Remaining. On 429, wait for Retry-After. Polling spots once a minute is plenty.

♿

Every shack is equal

G0ABC, G0ABC/P, G0ABC/M and EA8/G0ABC all belong to the same operator and shack. Where someone operated from is recorded, but it never changes their score.

Quick start

Fetch live spots

curl -H "Authorization: Bearer $SHOTA_KEY" \
  "https://shacksontheair.com/api/v1/spots?mode=CW"

Post a spot

curl -X POST -H "Authorization: Bearer $SHOTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activator":"G0ABC/P","frequency":14062.5,"mode":"CW","comment":"CQ SHOTA"}' \
  https://shacksontheair.com/api/v1/spots

Log QSOs as ADIF

curl -X POST -H "Authorization: Bearer $SHOTA_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @today.adi \
  https://shacksontheair.com/api/v1/qsos

…or as JSON

curl -X POST -H "Authorization: Bearer $SHOTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"qsos":[{"station_callsign":"G0ABC/M","call":"M0XYZ",
       "qso_date":"20261101","time_on":"1830","freq":"7.030",
       "band":"40m","mode":"CW","rst_sent":"599","rst_rcvd":"579"}]}' \
  https://shacksontheair.com/api/v1/qsos

ADIF notes

STATION_CALLSIGN must resolve to one of your registered callsigns. Portable (/P), mobile (/M, /MM, /AM) and prefixed forms (EA8/G0ABC) are all accepted.
If it is missing, your primary callsign is used.
Shack-to-shack: set SIG to SHOTA and SIG_INFO to the other station's shack reference, e.g. GB-0042.
Optional SHOTA_FROM: one of home, shed, club, mobile, portable or remote. Without it, we infer from /P or /M, otherwise home. It's just for the record and never scored.
Re-sending a QSO updates it rather than duplicating it. Duplicates are matched on base call, minute, band and mode.
An activation is one shack on one UTC day. It is valid at 10 QSOs, the same for everyone.
Hunters get credit automatically when an activator's log contains their callsign.
Maximum 256 KB or 5000 QSOs per request. Upload bigger logs on the website.

Endpoints at a glance

GET /spots, POST /spots
GET /shacks, /shacks/{ref}, /shacks/{ref}/activations
GET /activations, /events, /operators/{callsign}
GET /leaderboards/activators, /leaderboards/hunters
GET /me, /me/callsigns, /me/activations, /me/qsos, /me/hunted, /me/awards
POST /qsos, DELETE /qsos/{id}

API reference

Click Authorize and paste your key to try requests live.