{% 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>Let me know if you get stuck, I'm 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 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>

<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 operator of each Spothole server,
    so get in touch with the server owner 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 operator
    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>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 %}