mirror of
https://git.ianrenton.com/ian/spothole.git
synced 2026-09-24 16:24:32 +00:00
43 lines
3.2 KiB
HTML
43 lines
3.2 KiB
HTML
{% extends "../help_page.html" %}
|
|
{% block help_content %}
|
|
|
|
<h2 class="mt-4 mb-4">Writing your own client</h2>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>Various approaches exist to writing your own client, but in general:</p>
|
|
<ul>
|
|
<li>Refer to the API docs. These are built on an OpenAPI definition file (<code>/static/apidocs/openapi.yml</code>), which you can
|
|
automatically use to generate a client skeleton using various software.</li>
|
|
<li>Call the main "spots" or "alerts" API endpoints to get the data you want. For example, your app could call
|
|
<code>https://spothole.app/api/v2/spots</code> once every few minutes. Apply filters if necessary.</li>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
<li>Let me know if you get stuck, I'm happy to help.
|
|
<ul>
|
|
<li>Caveat: If you have vibe-coded a client, do not contact me until you have read and understood the code using your actual Human Intelligence.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>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.</p>
|
|
<p>If you absolutely must be informed within seconds of a spot arriving in Spothole, please use the SSE endpoints instead,
|
|
e.g. <code>https://spothole.app/api/v2/spots/stream</code>.</p>
|
|
<p>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
|
|
<code>https://spothole.app/api/v2/spots?sig=POTA,SOTA</code> rather than making two separate calls to
|
|
<code>https://spothole.app/api/v2/spots?sig=POTA</code> and <code>https://spothole.app/api/v2/spots?sig=SOTA</code>.</p>
|
|
<p>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.
|
|
<code>spothole.app</code> 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.)</p>
|
|
|
|
{% end %}
|