mirror of
https://git.ianrenton.com/ian/spothole.git
synced 2026-09-29 02:32:05 +00:00
Document use of the web interface, plus some other changes. Closes #152
This commit is contained in:
Ian Renton
+39
-24
@@ -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 %}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 %}
|
||||
|
||||
@@ -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 %}
|
||||
Reference in New Issue
Block a user