{% 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 %}