spothole/templates/about.html

{% extends "base.html" %}
{% block content %}

<div id="info-container" class="mt-4">
    <h2 class="mt-4 mb-4">About Spothole</h2>
    <p>Spothole is a utility to aggregate "spots" from amateur radio DX clusters and xOTA spotting sites, and provide an
        open JSON API as well as a website to browse the data.</p>
    <p>While there are several other web-based interfaces to DX clusters, and sites that aggregate spots from various
        outdoor activity programmes for amateur radio, Spothole differentiates itself by supporting a larger number of
        data sources, and by being "API first" rather than just providing a web front-end. This allows other software to
        be built on top of it.</p>
    <p>The API is deliberately well-defined with an <a href="/apidocs/openapi.yml">OpenAPI specification</a> and <a
            href="/apidocs">API documentation</a>. The API delivers spots in a consistent format regardless of the data
        source, freeing developers from needing to know how each individual data source presents its data.</p>
    <p>Spothole itself is also open source, Public Domain licenced code that anyone can take and modify. <a
            href="https://git.ianrenton.com/ian/spothole/">The source code is here</a>.</p>
    <p>The software was written by <a href="https://ianrenton.com">Ian Renton, MØTRT</a> and other contributors. Full
        details are available in the <a href="https://git.ianrenton.com/ian/spothole/src/branch/main/README.md">README
            file</a>.</p>
    <p>This server is running Spothole version {{software_version}}.</p>
    <h2 class="mt-4 mb-4">Using Spothole</h2>
    <p>There are a number of different ways to use Spothole, depending on what you want to do with it and your level of
        technical skill:</p>
    <ol>
        <li>You can <b>use it on the web</b>, like you are (probably) doing right now. This is how most people use it,
            to look up spots and alerts, and make interesting QSOs.
        </li>
        <li>If you are using an Android or iOS device, you can <b>"install" it on your device</b>. Spothole is a
            Progressive Web App, meaning it's not delivered through app stores, but if you open the page on Chrome
            (Android) or Safari (iOS) there will be an option in the menu to install it. It will then appear in your
            main app menu.
        </li>
        <li>You can <b>embed the web interface in another website</b> to show its spots in a custom dashboard or the
            like. The usage is explained in more detail in the <a
                    href="https://git.ianrenton.com/ian/spothole/src/branch/main/README.md">README file</a>.
        </li>
        <li>You can <b>write your own client using the Spothole API</b>, using the main Spothole instance to provide
            data, and do whatever you like with it. The README contains guidance on how to do this, and the full API
            docs are linked above. You can also find reference implementations in the form of Spothole's own web-based
            front end, plus my other two tools built on Spothole: <a href="https://fieldspotter.radio">Field Spotter</a>
            and the <a href="https://qsomap.m0trt.radio">QSO Map Tool</a>.
        </li>
        <li>If you want to <b>run your own version of Spothole</b> so you can customise the configuration, such as
            enabling sources that I disable on the main instance, you can do that too. The README contains not only
            advice on how to set up Spothole but how to get it auto-starting with systemd, using an nginx reverse proxy,
            and setting up HTTPS support with certbot.
        </li>
        <li>Finally, you can of course download the source code and <b>develop Spothole to meet your needs</b>. Whether
            you contribute your changes back to the main repository is up to you. As usual, the README file contains
            some advice on the structure of the repository, and how to get started writing your own spot provider.
        </li>
    </ol>
    <h2 id="faq" class="mt-4">FAQ</h2>
    <h4 class="mt-4">"Spots"? "DX Clusters"? What does any of this mean?</h4>
    <p>This is a tool for amateur ("ham") radio users. Many amateur radio operators like to make contacts with others
        who are doing something more interesting than sitting in their home "shack", such as people in rarely-seen
        countries, remote islands, or on mountaintops. Such operators are often "spotted", i.e. when someone speaks to
        them, they will put the details such as their operating frequency into an online system, to let others know
        where to find them. A DX Cluster is one type of those systems. Most outdoor radio awards programmes, such as
        "Parks on the Air" (POTA) have their own websites for posting spots.</p>
    <p>Spothole is an "aggregator" for those spots, so it checks lots of different services for data, and brings it all
        together in one place. So no matter what kinds of interesting spots you are looking for, you can find them
        here.</p>
    <p>As well as spots, it also provides a similar feed of "alerts". This is where amateur radio users who are going to
        interesting places soon will announce their intentions.</p>
    <h4 class="mt-4">What are "DX", "DE" and modes?</h4>
    <p>In amateur radio terminology, the "DX" contact is the "interesting" one that is using the frequency shown and
        looking for callers. They might be on a remote island or just in a local park, but either way it's interesting
        enough that someone has "spotted" them. The callsign listed under "DE" is the person who entered the spot of the
        "DX" operator. "Modes" are the type of communication they are using. For example you might see "CW" which is
        Morse Code, or voice "modes" like SSB or FM, or more exotic "data" modes which are used for computer-to-computer
        communication.</p>
    <h4 class="mt-4">What data sources are supported?</h4>
    <p>Spothole can retrieve spots from: <a href="https://www.dxcluster.info/telnet/">Telnet-based DX clusters</a>, the
        <a href="https://www.reversebeacon.net/">Reverse Beacon Network (RBN)</a>, the <a
                href="https://www.aprs-is.net/">APRS Internet Service (APRS-IS)</a>, <a href="https://pota.app">POTA</a>,
        <a href="https://www.sota.org.uk/">SOTA</a>, <a href="https://wwff.co/">WWFF</a>, <a
                href="https://www.cqgma.org/">GMA</a>, <a href="https://wwbota.net/">WWBOTA</a>, <a
                href="http://www.hema.org.uk/">HEMA</a>, <a href="https://www.parksnpeaks.org/">Parks 'n' Peaks</a>, <a
                href="https://ontheair.nz">ZLOTA</a>, <a href="https://www.wota.org.uk/">WOTA</a>, <a
                href="https://llota.app">LLOTA</a>, <a href="https://wwtota.com">WWTOTA</a>, <a
                href="https://tilesontheair.com/">Tiles on the Air</a>, the <a href="https://ukpacketradio.network/">UK
            Packet Repeater Network</a>, and any site based on the <a href="https://github.com/nischu/xOTA">xOTA
            software by nischu</a>.</p>
    <p>Spothole can retrieve alerts from: <a href="https://www.ng3k.com/">NG3K</a>, <a href="https://pota.app">POTA</a>,
        <a href="https://www.sota.org.uk/">SOTA</a>, <a href="https://wwff.co/">WWFF</a>, <a
                href="https://www.parksnpeaks.org/">Parks 'n' Peaks</a>, <a href="https://www.wota.org.uk/">WOTA</a> and
        <a href="https://www.beachesontheair.com/">BOTA</a>.</p>
    <p>Spothole can retrieve solar and propagation condition data from <a href="https://www.hamqsl.com">HamQSL</a>, the
        <a href="https://www.swpc.noaa.gov/">NOAA Space Weather Prediction Center</a>, the <a
                href="https://giro.uml.edu/">Lowell GIRO Data Center</a> and <a href="https://prop.kc2g.com/">prop.kc2g.com</a>
        by KC2G.</p>
    <p>Spothole can also perform lookups for callsign data on behalf of the user from <a
            href="https://qrz.com">QRZ.com</a> and <a href="https://hamqth.com">HamQTH</a>.</p>
    <p>Note that the server owner has not necessarily enabled all these data sources. In particular it is common to
        disable RBN, to avoid the server being swamped with FT8 traffic, and to disable APRS-IS and UK Packet Net so
        that the server only displays stations where there is likely to be an operator physically present for a QSO.</p>
    <p>Between the various data sources, the following Special Interest Groups (SIGs) are supported: Parks on the Air
        (POTA), Summits on the Air (SOTA), Worldwide Flora & Fauna (WWFF), Global Mountain Activity (GMA), Worldwide
        Bunkers on the Air (WWBOTA), HuMPs Excluding Marilyns Award (HEMA), Islands on the Air (IOTA), Mills on the Air
        (MOTA), the Amateur Radio Lighthouse Socirty (ARLHS), International Lighthouse Lightship Weekend (ILLW), Silos
        on the Air (SIOTA), World Castles Award (WCA), New Zealand on the Air (ZLOTA), Keith Roget Memorial National
        Parks Award (KRMNPA), Wainwrights on the Air (WOTA), Beaches on the Air (BOTA), Lagos y Lagunas On the Air
        (LLOTA), Towers on the Air (WWTOTA), Tiles on the Air, Worked All Britain (WAB), Worked All Ireland (WAI), el
        Diploma Municipios de España (DME) and Toilets on the Air (TOTA).</p>
    <p>As of the time of writing in June 2026, I think Spothole captures essentially all outdoor radio programmes
        that have a defined reference list, and almost certainly those that have a spotting/alerting API. If you know of
        one I've missed, please let me know!</p>
    <h4 class="mt-4">Why can I filter spots by both SIG and Source? Isn't that basically the same thing?</h4>
    <p>Mostly, but not quite. While POTA spots generally come from the POTA source and so on, there are a few
        exceptions:</p>
    <ol>
        <li>Sources like GMA and Parks 'n' Peaks provide spots for multiple different programmes (SIGs).</li>
        <li>Cluster spots may name SIGs in their comment, in which case the source remains the Cluster, but a SIG is
            assigned.
        </li>
        <li>Some SIGs, such as Worked all Britain (WAB), don't have their own spotting site and can <em>only</em> be
            identified through comments on spots retrieved from other sources.
        </li>
        <li>SIGs have well-defined names, whereas the server owner may name the sources as they see fit.</li>
    </ol>
    <p>Spothole's web interface exists not just for the end user, but also as a reference implementation for the API, so
        I have chosen to demonstrate both methods of filtering.</p>
    <h4 class="mt-4">How is this better than DXheat, DXsummit, POTA's own website, etc?</h4>
    <p>It's probably not? But it's nice to have choice.</p>
    <p>I think it's got three key advantages over those sites:</p>
    <ol>
        <li>It provides a public, <a href="/apidocs">well-documented API</a> with an <a href="/apidocs/openapi.yml">OpenAPI
            specification</a>. Other sites don't have official APIs or don't bother documenting them publicly, because
            they want people to use their web page. I like Spothole's web page, but you don't have to use it&mdash;if
            you're a programmer, you can build your own software on Spothole's API. Spothole does the hard work of
            taking all the various data sources and providing a consistent, well-documented data set. You can then do
            the fun bit of writing your own application.
        </li>
        <li>It grabs data from a lot more sources. I've seen other sites that pull in DX Cluster and POTA spots
            together, but nothing on the scale of what Spothole supports.
        </li>
        <li>Spothole is open source, so anyone can contribute the code to support a new data source or add new features,
            and share them with the community.
        </li>
    </ol>
    <h4 class="mt-4">Why does this website ask me if I want to install it?</h4>
    <p>Spothole is a Progressive Web App, which means you can install it on an Android or iOS device by opening the site
        in Chrome or Safari respectively, and clicking "Install" on the pop-up panel. It'll only prompt you once, so if
        you dismiss the prompt and change your mind, you'll find an Install / Add to Home Screen option on your
        browser's menu.</p>
    <p>Installing Spothole on your phone is completely optional, the website works exactly the same way as the "app"
        does.</p>
    <h4 class="mt-4">Why hasn't my spot/alert shown up yet?</h4>
    <p>To avoid putting too much load on the various servers that Spothole connects to, the Spothole server only polls
        them once every two minutes for spots, and once every 30 minutes for alerts. (Some sources, such as DX clusters,
        RBN, APRS-IS and WWBOTA use a non-polling mechanism, and their updates will therefore arrive more quickly.) Then
        if you are using the web interface, that has its own rate at which it fetches the data from Spothole. This is
        instant for the main spots list, with new spots appearing immediately at the top of the list, while the map and
        bands displays update once a minute, and the alerts display updates once every 5 minutes. So you could be
        waiting around three minutes to see a newly added spot, or 40 minutes to see a newly added alert.</p>
    <h4 class="mt-4">What licence does Spothole use?</h4>
    <p>Spothole's source code is licenced under the Public Domain. You can write a Spothole client, run your own server,
        modify it however you like, you can claim you wrote it and charge people £1000 for a copy, I don't really mind.
        (Please don't do the last one. But if you're using my code for something cool, it would be nice to hear from
        you!)</p>
    <h2 class="mt-4">Data Accuracy</h2>
    <p>Please note that the data coming out of Spothole is only as good as the data going in. People mis-hear and make
        typos when spotting callsigns all the time. There are also plenty of cases where Spothole's data, particularly
        location data, may be inaccurate. For example, there are POTA parks that span multiple US states, countries that
        span multiple CQ zones, portable operators with no requirement to sign /P, etc. If you are doing something where
        accuracy is important, such as contesting, you should not rely on Spothole's data to fill in any gaps in your
        log.</p>
    <h2 id="privacy" class="mt-4">Privacy</h2>
    <p>Spothole collects no data about you on a permanent basis. All spots and alerts are "timed out" and deleted from
        the system after a set interval, which by default is one hour for spots and one week for alerts.</p>
    <p>Settings you select from Spothole's menus are sent to the server, in order to provide the data with the requested
        filters. They are also stored in your browser's local storage, so that your preferences are remembered between
        sessions.</p>
    <p>The data you provide can optionally include your login credentials for QRZ.com and HamQTH. You can provide these
        in the "Data" menu of most pages. If you do, Spothole will augment the data it produces with lookups from these
        services, which can for example provide more accurate markers on the map tab, and operator names when you mouse
        over a DX callsign. Spothole will still work fine if you don't provide these. The values you enter are sent to
        Spothole via HTTPS so are protected in transit, though of course you do have to trust Spothole with this
        sensitive data in order to use this feature.</p>
    <p>Spothole uses no trackers, no ads, and no cookies.</p>
    {% if len(web_ui_options["support-button-html"]) > 0 %}
    <p><strong>Caveat: </strong> The owner of this server has chosen to inject their own content into the "spots" page.
        This is designed for a "donate" or "support this server" button. The functionality of this injected content is
        the responsibility of the server owner, rather than the Spothole software.</p>
    {% end %}
    <p>Spothole is open source, so you can audit <a href="https://git.ianrenton.com/ian/spothole">the code</a> if you
        like.</p>
    <h2 class="mt-4">Thanks</h2>
    <p>This project would not have been possible without those volunteers who have taken it upon themselves to run DX
        clusters, xOTA programmes, DXpedition lists, callsign lookup databases, solar conditions and propagation
        modelling software, and other online tools on which Spothole's data is based. The vast majority of these are not
        profit-seeking and are made purely for the love of the hobby and to help others in the community. Spothole is
        standing on the shoulders of giants, who deserve a huge amount of thanks for all the work they put in.</p>
    <p>Spothole is also dependent on a number of Python libraries, in particular pyhamtools, and many JavaScript
        libraries, as well as the Font Awesome icon set and flag icons from the Noto Color Emoji set, and MIT-licenced
        GeoJSON files for CQ and ITU zones from HA8TKS.</p>
    <p>This software is dedicated to the memory of Tom G1PJB, SK, a friend and colleague who sadly passed away around
        the time I started writing it in Autumn 2025. I was looking forward to showing it to you when it was done.</p>
</div>

<script>$(document).ready(function () {
    $("#nav-link-about").addClass("active");
}); <!-- highlight active page in nav --></script>

{% end %}