« Spothole Help

Writing your own Client

One of the key strengths of Spothole is that the API is well-defined and open to anyone to use. This means you can build your own software that uses data from Spothole.

As well as the main API endpoints to fetch spots and alerts, with various possible query parameters, there are also Server-Sent Events (SSE) API endpoints to receive a live feed, plus various utility lookup endpoints for things like callsign and park data.

Various approaches exist to writing your own client, but in general:

  • Refer to the API docs. These are built on an OpenAPI definition file (/static/apidocs/openapi.yml), which you can automatically use to generate a client skeleton using various software.
  • Call the main "spots" or "alerts" API endpoints to get the data you want. For example, your app could call https://spothole.app/api/v3/spots once every few minutes. Apply filters if necessary.
  • Call the "options" API to get an idea of which bands, modes etc. the server knows about. You might want to do that first before calling the spots/alerts APIs, to allow you to populate your filters correctly.
  • Refer to the provided HTML/JS interface for a reference on different approaches. For example, the "alerts"/"upcoming" page simply query the main spot API on a timer, whereas the spots, map and bands pages combine this approach with using the Server-Sent Events (SSE) endpoint to update live.
  • If you get stuck, get in touch with Spothole's developers who will be happy to help.

If you're fetching spot data, you're unlikely to need a sub-minute refresh time. For example, Spothole only queries the POTA API once every two minutes, so if your client is interested in POTA data there's no need to poll Spothole any more often than that. If you absolutely must be informed within seconds of a spot arriving in Spothole, please use the SSE endpoints instead, e.g. https://spothole.app/api/v3/spots/stream.

If you want to handle different types of spot or alert differently within your client, please consider making a single request to the Spothole API to retrieve all the data, then filtering on your side. For example, call https://spothole.app/api/v3/spots?activity=POTA,SOTA rather than making two separate calls to https://spothole.app/api/v3/spots?activity=POTA and https://spothole.app/api/v3/spots?activity=SOTA.

Remember, here at Spothole Inc. we offer an industry-standard "five nines" uptime on our server, with our own unique twist: we don't tell you which side of the decimal point the nines start! (Translation: This is a hobby project. spothole.app runs on the same server a Minecraft server and all sorts of other stuff. It might go down without warning. By all means base your own project on data from the main server if you like, but if you want any control over reliability and downtime, please run your own copy instead.)

Submitting Spots and Alerts

As well as reading data, clients can submit new spots to Spothole using the "add spot" API endpoint, e.g. https://spothole.app/api/v3/spot. Spots can be added to Spothole itself, and optionally sent "upstream" to other services such as the DX cluster. Check the add_allowed and spot_submit_providers fields in the "options" API response to see what the server allows.

Alerts for upcoming activations can be submitted in the same way using the "add alert" API endpoint, e.g. https://spothole.app/api/v3/alert. Check alert_submit_providers to see where alerts can be sent upstream to.

To stop bots and spammers abusing the spotting function, a Spothole server can be configured to protect against this, which means you will need an API key. API keys are issued by the owner of each Spothole server, not by the Spothole developer. This server is run by M0TRT, so get in touch with them and let them know what your software is and how it will use the API. Once you have a key, send it in the X-API-Key header of each add spot or add alert request. For example:

curl --request POST \
     --header "Content-Type: application/json" \
     --header "X-API-Key: your-api-key-here" \
     --data '{"spot":{"dx_call":"M0TRT","time":1760019539,"freq":14200000,"de_call":"M0TRT"}}' \
     https://spothole.app/api/v3/spot

The spot's time must be the current time (in UTC seconds since the UNIX epoch). It will be rejected if it is too far in the past or the future. Only the fields listed for spot and alert submission in the API docs are accepted; any others, such as an id, are ignored, as Spothole works those out for itself.

Adding an alert works the same way, but with an alert object instead of a spot object, and sent to the /alert endpoint. An alert needs at least the callsign(s) that will be on the air and a start time:

curl --request POST \
     --header "Content-Type: application/json" \
     --header "X-API-Key: your-api-key-here" \
     --data '{"alert":{"dx_calls":["M0TRT"],"start_time":1760019539,"freqs_modes":"14.285 SSB"}}' \
     https://spothole.app/api/v3/alert

To send a spot upstream as well, add a handling object alongside the spot object, with an upstream_providers list naming the providers to send it to. The names must match those listed in spot_submit_providers in the "options" API response. For example, this spot of a POTA activation is sent to both the DX cluster and POTA. (POTA requires a park reference, so this is provided in activity_refs.)

curl --request POST \
     --header "Content-Type: application/json" \
     --header "X-API-Key: your-api-key-here" \
     --data '{
       "spot": {
         "dx_call": "M0TRT",
         "de_call": "M0TRT",
         "time": 1760019539,
         "freq": 14200000,
         "mode": "SSB",
         "activities": ["POTA"],
         "activity_refs": [{"activity": "POTA", "id": "GB-0001"}]
       },
       "handling": {
         "upstream_providers": ["Cluster", "POTA"]
       }
     }' \
     https://spothole.app/api/v3/spot

If the spot is accepted by at least one upstream provider, it will appear in Spothole when it comes back from that provider, rather than being added directly. Some upstream providers need credentials, which can be supplied in an upstream_credentials map inside the handling object. See the API docs for details.

Your API key identifies your software, so please keep it private. Don't commit it to a public code repository, and don't embed it in JavaScript or anywhere else your users could extract it. If a key is misused, the server owner can revoke it, and spot and alert submission from your client will stop working. If you are going to allow users to spot up to Spothole via a web interface, you must protect it somehow against drive-by spamming, e.g. by a CAPTCHA or by requiring a login to use it.

Conditions of Use

The conditions are simple, and hopefully not onerous. They probably aren't legally binding, and nobody is likely to sue you for breaching them. But having them in place ensures Spothole can continue to operate without the people running it burning out, and with no payment required. In the collaborative and respectful tradition of amateur radio, please read and understand them.

When creating a Spothole client, you agree that:

  • If you got an AI to write your code, and you run into problems, you will try to understand the code using your Actual Intelligence before asking the developer or server owner for help. If you don't understand the code, please ask the AI to fix it, not them.
  • When querying the API, you will send a useful referrer or user agent string that will help the server owner uniquely identify your software. If their server starts receiving too many, or malformed, requests, this will allow them to diagnose the problem and figure out who to talk to about it.
  • You set a sensible query rate and will not try to take down the server by bombarding it with tons of requests.
  • You are OK with the server being down occasionally. There is no uptime guarantee. This is a hobby project and sometimes stuff will accidentally break.
  • You check for API changes occasionally, e.g. using the RSS feed for Spothole release notifications, or by following Spothole's developer on Mastodon, or just by checking back on the Spothole documentation every so often. Every effort is made to stop updates breaking older client code, but eventually old versions of the API will need to be turned off for the developer's sanity.

« Back

Powered by