mirror of
https://git.ianrenton.com/ian/spothole.git
synced 2026-09-24 08:14:32 +00:00
54 lines
3.8 KiB
HTML
54 lines
3.8 KiB
HTML
{% extends "../help_page.html" %}
|
|
{% block help_content %}
|
|
|
|
<h2 class="mt-4 mb-4">Writing your own Client</h2>
|
|
|
|
<div class="alert alert-primary" role="alert">
|
|
<i class="fa-solid fa-circle-info"></i> <strong>Writing a Spothole client using AI?</strong><br/>The price of
|
|
creating a service with a nice API in 2025 is that a lot of people are going to vibe-code themselves a personal
|
|
ham radio dashboard using this data. That's fine, I can't stop you doing that, and I do appreciate the freedom of
|
|
creativity it gives to people who otherwise wouldn't create software. <em>However</em>, if an AI wrote your code and
|
|
it doesn't work, please don't jump straight to emailing me. Either take the time to understand the code yourself
|
|
first, or else ask your AI to fix its own mess. Thanks!
|
|
</div>
|
|
|
|
<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.</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 %}
|