w1cdn/spothole
1
0
Fork 0
mirror of https://git.ianrenton.com/ian/spothole.git synced 2026-09-28 18:22:05 +00:00
Code Issues 13 Packages Projects Releases Wiki Activity

Document use of the web interface, plus some other changes. Closes #152

Browse Source
This commit is contained in:
Ian Renton
2026-09-25 14:52:16 +01:00
parent 760c2412d3
commit 4df00c321c
18 changed files with 338 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files
templates/help/usage/clients.html
+37 -11
View File
@@ -4,12 +4,10 @@
<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!
<i class="fa-solid fa-circle-info"></i> <strong>Conditions of Use</strong><br/>At the end of this page is a
section on conditions for using the Spothole API. These are not onerous, but some simple points you should agree to
to ensure Spothole remains free and available to everyone. Please ensure you read it before writing a client to the
Spothole API. This still applies even if you are getting an AI to write your client for you!
</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
@@ -34,11 +32,10 @@
</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/v3/spots/stream</code>.</p>
<p>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. <code>https://spothole.app/api/v3/spots/stream</code>, or the Telnet server.</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/v3/spots?activity=POTA,SOTA</code> rather than making two separate calls to
@@ -50,4 +47,33 @@
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>
<h3 class="mt-4" id="terms">Conditions of Use</h3>
<p>There are some simple, hopefully not onerous terms and conditions that you should agree to before writing a client
for the Spothole API. These probably aren't legally binding, and I'm just a random guy on the internet, I'm not
going to sue you for breaching them. But having these conditions in place ensures Spothole can continue to operate
without me burning out and with no payment required. In the collaborative and respectful tradition of amateur radio,
please read and understand them.</p>
<p>When creating a Spothole client, you agree that:</p>
<ul>
<li>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 me for help. If you don't understand the code, please ask the AI to fix it,
not me.
</li>
<li>When querying the API, you will send a useful referrer or user agent string that will help me uniquely identify
your software. This will allow me to diagnose the problem and figure out who to talk to if Spothole starts
receiving too many, or malformed, requests.
</li>
<li>You set a sensible query rate and will not try to take down the server by bombarding it with tons of requests.
</li>
<li>You are OK with the server being down occasionally. There is no uptime guarantee. This is a hobby project and
sometimes I will accidentally break stuff.
</li>
<li>You check for API changes occasionally, e.g. using <a
href="https://git.ianrenton.com/ian/spothole/releases.rss">the RSS feed for Spothole release
notifications</a>, or by <a href="https://mastodon.radio/@ian">following me on Mastodon</a>, or just by checking
back on the Spothole documentation every so often. I will do my best to stop updates breaking older client code,
but eventually I will need to turn off old versions of the API for my own sanity.
</li>
</ul>
{% end %}