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/add-spot.html
+1 -1
View File
@@ -77,7 +77,7 @@
</div>
<script src="/static/js/add-spot.js?v=1790324213"></script>
<script src="/static/js/add-spot.js?v=1790344336"></script>
<script>$(document).ready(function () {
$("#nav-link-add-spot").addClass("active");
}); <!-- highlight active page in nav --></script>
templates/alerts.html
+1 -1
View File
@@ -85,7 +85,7 @@
</div>
<script src="/static/js/alerts.js?v=1790324213"></script>
<script src="/static/js/alerts.js?v=1790344337"></script>
<script>$(document).ready(function () {
$("#nav-link-alerts").addClass("active");
}); <!-- highlight active page in nav --></script>
templates/bands.html
+2 -2
View File
@@ -76,8 +76,8 @@
</div>
<script src="/static/js/spotsbandsandmap.js?v=1790324213"></script>
<script src="/static/js/bands.js?v=1790324213"></script>
<script src="/static/js/spotsbandsandmap.js?v=1790344336"></script>
<script src="/static/js/bands.js?v=1790344336"></script>
<script>$(document).ready(function () {
$("#nav-link-bands").addClass("active");
}); <!-- highlight active page in nav --></script>
templates/base.html
+7 -10
View File
@@ -1,6 +1,6 @@
{% extends "skeleton.html" %}
{% block head_extra %}
<link rel="stylesheet" href="/static/css/style.css?v=1790324213" type="text/css">
<link rel="stylesheet" href="/static/css/style.css?v=1790344336" type="text/css">
<link href="/static/vendor/css/bootstrap-5.3.8.min.css" rel="stylesheet">
<link href="/static/vendor/css/fontawesome-6.7.2.min.css" rel="stylesheet">
<link href="/static/vendor/css/solid-6.7.2.min.css" rel="stylesheet">
@@ -16,10 +16,10 @@
window.fetchEventSource = fetchEventSource;
</script>
<script src="/static/js/utils.js?v=1790324213"></script>
<script src="/static/js/ui-ham.js?v=1790324213"></script>
<script src="/static/js/geo.js?v=1790324213"></script>
<script src="/static/js/common.js?v=1790324213"></script>
<script src="/static/js/utils.js?v=1790344336"></script>
<script src="/static/js/ui-ham.js?v=1790344336"></script>
<script src="/static/js/geo.js?v=1790344336"></script>
<script src="/static/js/common.js?v=1790344336"></script>
{% end %}
{% block body %}
<div class="container">
@@ -70,15 +70,12 @@
<footer class="d-flex flex-wrap justify-content-between align-items-center py-3 my-4 border-top">
<p class="col-md-4 mb-0 text-body-secondary">Made with love by <a href="https://ianrenton.com"
class="text-body-secondary">Ian, MØTRT</a>
and other contributors.</p>
and <a href="/help/thanks" class="text-body-secondary">other contributors.</a></p>
<p class="col-md-4 mb-0 justify-content-center text-body-secondary text-center">Spothole
v{{software_version}}</p>
<ul class="nav col-md-4 justify-content-end">
<li class="nav-item">
<a href="/help/faq" class="nav-link px-3 text-body-secondary">FAQ</a>
</li>
<li class="nav-item">
<a href="/help/privacy" class="nav-link px-3 text-body-secondary">Privacy</a>
<a href="/help/privacy" class="nav-link px-3 text-body-secondary">Privacy / Legal</a>
</li>
<li class="nav-item">
<a href="https://git.ianrenton.com/ian/spothole" class="nav-link px-3 text-body-secondary">Source
templates/conditions.html
+1 -1
View File
@@ -284,7 +284,7 @@
</div>
<script src="/static/vendor/js/chart-4.4.9.umd.min.js"></script>
<script src="/static/js/conditions.js?v=1790324213"></script>
<script src="/static/js/conditions.js?v=1790344336"></script>
<script>$(document).ready(function () {
$("#nav-link-conditions").addClass("active");
}); <!-- highlight active page in nav --></script>
templates/help.html
+2 -1
View File
@@ -12,6 +12,7 @@
<li><a href="/help/about">About Spothole</a></li>
<li><a href="/help/usage">How to use Spothole</a>
<ul>
<li><a href="/help/usage/web">Using the Web Interface</a></li>
{% if telnet_server_enabled %}
<li><a href="/help/usage/telnet">Connecting via Telnet</a></li>
{% end %}
@@ -31,7 +32,7 @@
<li><a href="/help/faq">Frequently Asked Questions (FAQ)</a></li>
<li><a href="/apidocs">API Documentation</a></li>
<li><a href="/help/accuracy">Data Accuracy</a></li>
<li><a href="/help/privacy">Privacy</a></li>
<li><a href="/help/privacy">Privacy and Legal Information</a></li>
<li><a href="/help/thanks">Thanks</a></li>
</ul>
</div>
templates/help/privacy.html
+39 -24
View File
@@ -1,29 +1,44 @@
{% extends "help_page.html" %}
{% block help_content %}
<h2 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 "Your 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>Any data you send as part of a query, such as your QRZ or HamQTH credentials, is used only for the lifetime of
that
query and is not saved anywhere apart from your own device.</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">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 "Your 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>Any data you send as part of a query, such as your QRZ or HamQTH credentials, is used only for the lifetime of
that
query and is not saved anywhere apart from your own device.</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">Legal</h2>
<p>This server is run by an amateur radio operator with callsign {{ server_owner_callsign }}. You should contact them if
you have any issues with the website.</p>
<p>Spothole exists as an aggregator of data from many other sources. To the best of my knowledge, all these sources
either:</p>
<ul>
<li>State licence terms that make their data acceptable for use on a non-profit website like this one, or,</li>
<li>Require you to ask permission before using their data, which I have done, or,</li>
<li>Have an open API and are happy with third-party use.</li>
</ul>
<p>If you represent one of these data sources and would like it removed from Spothole, please let me know.</p>
<p>Spothole does not produce any real data of its own. Information such as spots and alerts that Spothole displays are
entered by users, often of other websites. The data may be the property of the user or the other website, depending
on their terms and conditions.</p>
{% end %}
templates/help/usage.html
+2 -1
View File
@@ -6,7 +6,8 @@
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.
to look up spots and alerts, and make interesting QSOs. See <a href="/help/usage/web">Using the Web
Interface</a> for more information.
</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
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 %}
templates/help/usage/web.html
+133
View File
@@ -0,0 +1,133 @@
{% extends "../help_page.html" %}
{% block help_content %}
<h2 class="mt-4 mb-4">Using the Web Interface</h2>
<p>Although Spothole is designed "API first" and designed so that more technical users to write their own clients, the
majority of Spothole users use it via its web interface. This page describes that interface and how to use it.</p>
<h3>Menu Bar</h3>
<p>Across the top of the page, or hidden behind the <strong><i class="fa-solid fa-bars"></i> hamburger menu
button</strong> on
mobile, is the main menu which
provides access to all of Spothole's features. These are:</p>
<ul>
<li><strong><i class="fa-solid fa-tower-cell"></i> Spots</strong>, the main DX cluster type display showing live
spots in a table
</li>
<li><strong><i class="fa-solid fa-map"></i> Map</strong>, which displays spots with a known location on a map</li>
<li><strong><i class="fa-solid fa-ruler-vertical"></i> Bands</strong>, which displays spots with a known frequency
on radio band displays
</li>
<li><strong><i class="fa-solid fa-clock"></i> Upcoming</strong>, the list of upcoming activations, DXpeditions and
contests
</li>
{% if allow_spotting %}
<li><strong><i class="fa-solid fa-comment"></i> Add Spot</strong>, which allows users to add new spots to the system
</li>
{% end %}
<li><strong><i class="fa-solid fa-sun"></i> Conditions</strong>, displaying solar and geomagnetic conditions and DX
performance predictions
</li>
<li><strong><i class="fa-solid fa-chart-simple"></i> Status</strong>, which shows the status of the server itself
</li>
<li><strong><i class="fa-solid fa-circle-question"></i> Help</strong>, which opens up the help pages (like this one)
</li>
<li><strong><i class="fa-solid fa-gear"></i> API</strong>, which shows the OpenAPI specification by which clients
can use Spothole's data.
</li>
</ul>
<p><strong><i class="fa-solid fa-sun"></i> Conditions</strong>, <strong><i class="fa-solid fa-chart-simple"></i> Status</strong>,
<strong><i class="fa-solid fa-circle-question"></i> Help</strong> and <strong><i class="fa-solid fa-gear"></i>
API</strong> are stanalone pages, while the others have many more options as discussed below.</p>
<h3><i class="fa-solid fa-tower-cell"></i> Spots</h3>
<p>The spots page displays the traditional web-based "DX cluster" view, with a table of spots. The latest will appear at
the top of the table, and old ones will fall off the bottom. The list keeps itself up to date automatically, but if
you need to temporarily pause it, you can use the <strong><i class="fa-solid fa-play"></i> Run</strong> and
<strong><i class="fa-solid fa-stop"></i> Stop</strong> buttons.</p>
<p>On small screens such as mobile phones, the table will reflow into multiple lines per spot, keeping the alternating
background shading so you can tell spots apart.</p>
<p>A Search box is provided; this filters the spots so that only DX callsigns or comments that match your entry will be
shown. You can use this to look for specific callsign prefixes, or activities that aren't covered in the main
filters.</p>
<p>Three buttons at the top of the table provide the means for you to customise what you see and what data is used.
They are common to all the spot/alert pages, and are labelled <strong><i class="fa-solid fa-filter"></i>
Filters</strong>, <strong><i class="fa-solid fa-desktop"></i> Display</strong> and <strong><i
class="fa-solid fa-database"></i> Your data</strong>. Clicking each one will expand a menu of further
options.</p>
<h5><i class="fa-solid fa-filter"></i> Filters</h5>
<p>The Filters panel allows to to adjust what spots and alerts you will see. You can filter by band, mode, DX continent,
DE (spotter) continent, activity, and/or data source.</p>
<p>Activities include traditional amateur radio activities like DXpeditions and Contests, "adventure" activities like
POTA and SOTA, regional activities specific to a certain country, and event-based activities that only happen at
certain times of year.</p>
<p>Any of these filter options can be turned on and off as you like.</p>
<h5><i class="fa-solid fa-desktop"></i> Display</h5>
<p>The Display panel allows to to adjust other aspects of the spots you see. You can configure how many spots you get
on the page, whether UTC or local time is used, what colour scheme is used for pages and frequency bands, which
columns are shown in the table, and whether an audio sound effect is played when new spots pop up.</p>
<p>In the list of columns, three are disabled by default: Distance, Bearing, and "Worked?". Distance and bearing can
be enabled if you enter your grid locator under <strong><i class="fa-solid fa-database"></i> Your data</strong>.
"Worked?" adds a checkbox next to each row so you can tick off stations you've worked. There's currently no logger
integration; this is just for a quick check when you're using Spothole standalone.</p>
<h5><i class="fa-solid fa-database"></i> Your data</h5>
<p>The Your Data panel allows you to enter information specific to you. You can enter your QRZ.com and/or HamQTH
credentials, which will allow Spothole to fetch better data for the spots. You can set your grid locator, and clear
the list of calls you've worked, supporting the features discussed under "Display". You can also enter a list of
"Wanted Calls" (including partial calls), which will cause matching spots to have a gold highlight to catch your
eye.</p>
<h3><i class="fa-solid fa-map"></i> Map</h3>
<p>The map display shows spots visually on a map of the world. The location chosen can be based on various sources,
such as POTA park locations, QRZ.com lookup of an operator's home location, grids in the spot comments, and so on.
They are not guaranteed to be accurate, but should give a rough guide to where in the world each operator is.
You can click on the markers for more information about each spot.</p>
<p>The <strong><i class="fa-solid fa-desktop"></i> Display</strong> menu on the <strong><i class="fa-solid fa-map"></i>
Map</strong> page has a few differences to the one on the <strong><i class="fa-solid fa-tower-cell"></i>
Spots</strong> page:</p>
<ul>
<li>"Number of spots" is replaced by "Spot age"</li>
<li>"Time Zone", "Columns" and "Audio" are replaced by "Map Features" and "Map Style", allowing you to change the
look and feel of the map, display various grids and zones, and display a geodesic line between the DX spot and
the spotter, to give a better indication of where contacts are being made.
</li>
</ul>
<h3><i class="fa-solid fa-ruler-vertical"></i> Bands</h3>
<p>The bands display shows each amateur radio band that has active spots as a column, from lowest frequency at the top
to highest frequency at the bottom. Within it, markers indcate the callsign of the operator spotted on that
frequency.
</p>
<p>By hovering your mouse over the callsign, you can see the mode and the exact frequency.</p>
<h3><i class="fa-solid fa-clock"></i> Upcoming</h3>
<p>The upcoming page shows future park and summit activations, satellite operations, DXpeditions and contests from
various sources, in a table.</p>
<p>The table differs slightly from the table on the <strong><i class="fa-solid fa-tower-cell"></i> Spots</strong> page.
Here, the entries are in the opposite order, with "now" at the top, going further into the future as you scroll
down. The table is also split into three sections: "On Now", "Starting in the next 24 hours", and "Starting later".
Because upcoming alerts don't pop up as often as spots, there is no automatic refresh on this page.</p>
<p>This page has a unique card in the <strong><i class="fa-solid fa-filter"></i> Filters</strong> settings, "Duration
Limit". This allows you to hide long-running activations that hang around in the list for a long time, allowing you
to see the more time-limited ones. Because this is usually only a problem with POTA (where some people add an alert
several weeks long to say they'll be activating at some point during their holiday), you can choose to exclude
DXpeditions and Contests from this filter, because there will almost always be someone on the air during the whole
time the event is live.</p>
<p>Some upcoming alerts, such as DXpeditions and Contests, have links where you can learn more about them.</p>
<h3><i class="fa-solid fa-comment"></i> Add Spot</h3>
<p>The Add Spot page allows you to add a new spot into the Spothole system directly. Currently, this stays within
Spothole and is not sent "upstream" to DX clusters, POTA, SOTA etc. regardless of any activity you select.</p>
{% end %}
templates/map.html
+2 -2
View File
@@ -113,8 +113,8 @@
const CARTODB_API_KEY = "{{ web_ui_options.get('cartodb_api_key', '') }}";
</script>
<script src="/static/js/spotsbandsandmap.js?v=1790324213"></script>
<script src="/static/js/map.js?v=1790324213"></script>
<script src="/static/js/spotsbandsandmap.js?v=1790344337"></script>
<script src="/static/js/map.js?v=1790344337"></script>
<script>$(document).ready(function () {
$("#nav-link-map").addClass("active");
}); <!-- highlight active page in nav --></script>
templates/spots.html
+2 -2
View File
@@ -125,8 +125,8 @@
</div>
<script src="/static/js/spotsbandsandmap.js?v=1790324213"></script>
<script src="/static/js/spots.js?v=1790324213"></script>
<script src="/static/js/spotsbandsandmap.js?v=1790344336"></script>
<script src="/static/js/spots.js?v=1790344336"></script>
<script>$(document).ready(function () {
$("#nav-link-spots").addClass("active");
}); <!-- highlight active page in nav --></script>
templates/status.html
+1 -1
View File
@@ -96,7 +96,7 @@
</div>
</div>
<script src="/static/js/status.js?v=1790324213"></script>
<script src="/static/js/status.js?v=1790344336"></script>
<script>
$(document).ready(function () {
$("#nav-link-status").addClass("active");