mirror of
https://git.ianrenton.com/ian/spothole.git
synced 2026-09-28 18:22:05 +00:00
101 lines
7.4 KiB
HTML
101 lines
7.4 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>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
|
|
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/v3/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>If you get stuck, get in touch with Spothole's developers who will be happy to help.
|
|
</li>
|
|
</ul>
|
|
<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
|
|
<code>https://spothole.app/api/v3/spots?activity=POTA</code> and <code>https://spothole.app/api/v3/spots?activity=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 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.)</p>
|
|
|
|
<h3 class="mt-4" id="submitting-spots">Submitting Spots</h3>
|
|
<p>As well as reading data, clients can submit new spots to Spothole using the "add spot" API endpoint, e.g.
|
|
<code>https://spothole.app/api/v3/spot</code>. Spots can be added to Spothole itself, and optionally sent "upstream"
|
|
to other services such as the DX cluster. Check the <code>spot_allowed</code> and
|
|
<code>spot_submit_providers</code> fields in the "options" API response to see what the server allows.</p>
|
|
<p>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 <strong>API key</strong>. API keys are issued by the owner of each Spothole server,
|
|
not by the Spothole developer. This server is run by <strong>{{ server_owner_callsign }}</strong>, 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
|
|
<code>X-API-Key</code> header of each add spot request. For example:</p>
|
|
<pre><code>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</code></pre>
|
|
<p>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 submission from your client will stop working. Servers that don't protect spot submission
|
|
don't need an API key, and will accept spots with or without one.</p>
|
|
|
|
<h3 class="mt-4" id="terms">Conditions of Use</h3>
|
|
<p>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.</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 the developer or server owner for help. If you don't understand the code,
|
|
please ask the AI to fix it, not them.
|
|
</li>
|
|
<li>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.
|
|
</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 stuff will accidentally break.
|
|
</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 Spothole's developer on
|
|
Mastodon</a>, 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.
|
|
</li>
|
|
</ul>
|
|
|
|
{% end %}
|