mirror of
https://git.ianrenton.com/ian/spothole.git
synced 2026-08-08 19:41:41 +00:00
39 lines
2.7 KiB
Markdown
39 lines
2.7 KiB
Markdown
## 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/v1/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.
|
|
* Let me know if you get stuck, I'm happy to help.
|
|
|
|
Please don't hammer the API with an unnecessarily high request rate. 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/v1/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/v1/spots?sig=POTA,SOTA` rather than making two separate calls to
|
|
`https://spothole.app/api/v1/spots?sig=POTA` and `https://spothole.app/api/v1/spots?sig=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 as my blog and 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.) |