Tidy up use of first person in docs. Since I don't run the only server, referring to "me" in the docs was ambiguous and probably reads oddly to the other server owners.

This commit is contained in:
Ian Renton
2026-09-27 16:47:30 +01:00
parent 5d8cd38351
commit 71557db37c
21 changed files with 112 additions and 90 deletions
+2 -2
View File
@@ -49,9 +49,9 @@ WEB_UI_OPTIONS["recaptcha_site_key"] = RECAPTCHA_SITE_KEY if PROTECT_SPOT_SUBMIS
WEB_UI_OPTIONS["allow_upstream_spotting"] = ALLOW_SPOTTING and ALLOW_UPSTREAM_SPOTTING WEB_UI_OPTIONS["allow_upstream_spotting"] = ALLOW_SPOTTING and ALLOW_UPSTREAM_SPOTTING
if ALLOW_SPOTTING and PROTECT_SPOT_SUBMISSION and not (RECAPTCHA_SITE_KEY and RECAPTCHA_SECRET_KEY): if ALLOW_SPOTTING and PROTECT_SPOT_SUBMISSION and (not API_KEYS or not (RECAPTCHA_SITE_KEY and RECAPTCHA_SECRET_KEY)):
logger.warning( logger.warning(
"Spot submission is protected but reCAPTCHA keys are not set, so only clients with an API key will be able to submit spots. Users of the web interface will not be able to add spots." "Spot submission is enabled and protected but reCAPTCHA keys are not set and there are no API keys registered for third-party clients, so it will be impossible to add spots. This is a configuration problem you should fix."
) )
+13 -9
View File
@@ -7,9 +7,9 @@ info:
You can find out more information about Spothole at https://spothole.app/help, and specifically about creating a client to this API at https://spothole.app/help/usage/clients. You can find out more information about Spothole at https://spothole.app/help, and specifically about creating a client to this API at https://spothole.app/help/usage/clients.
While I provide this API for free, there are some conditions of use that you must adhere to. These are not onerous, but ensure the API can remain available to everyone. These apply even if you are getting an AI to write your client software for you. See https://spothole.app/help/usage/clients#terms for details. The main Spothole server at `spothole.app` provides this API for free, subject to some conditions of use that you must adhere to. These are not onerous, but ensure the API can remain available to everyone. These apply even if you are getting an AI to write your client software for you. See https://spothole.app/help/usage/clients#terms for details. Owners of other Spothole servers may adopt the same conditions or set their own, so if you are using a different server, check with its owner.
If you want to submit spots from your client, an API key is required. Please contact the server owner for a key if you want to use this functionality. If you want to submit spots from your client, some Spothole servers require an API key. API keys are issued by the owner of each Spothole server, not by the Spothole developer, so contact the owner of the server you want to use.
## Changelog ## Changelog
@@ -34,14 +34,14 @@ info:
If your client submits spots via POST `/spot` and uses upstream submission, replace `submit_upstream` and `upstream_provider` in the `handling` object with an `upstream_providers` list, and turn `upstream_credentials` into a map where the key is the provider name, and the value is another map of credential name to value. If your client submits spots via POST `/spot` and uses upstream submission, replace `submit_upstream` and `upstream_provider` in the `handling` object with an `upstream_providers` list, and turn `upstream_credentials` into a map where the key is the provider name, and the value is another map of credential name to value.
Some Spothole servers, including `spothole.app`, require a CAPTCHA to submit spots via the web interface, which third-party clients can't solve. If you want your client to submit spots to such a server, ask the server operator for an API key, and send it in the `X-API-Key` request header with each add spot request. Some Spothole servers, including `spothole.app`, require a CAPTCHA to submit spots via the web interface, which third-party clients can't solve. If you want your client to submit spots to such a server, ask the server owner for an API key, and send it in the `X-API-Key` request header with each add spot request.
You are encouraged to move to the `v3` API endpoints as soon as possible. To upgrade, replace `v2` with `v3` in the URLs your code calls, then rename any use of the fields, query parameters and values listed above, and handle `activities` being a list rather than a single `sig` value. If you use the activity reference lookup, call `/lookup/activityref?activity=...&id=...` instead of `/lookup/sigref?sig=...&id=...`. You are encouraged to move to the `v3` API endpoints as soon as possible. To upgrade, replace `v2` with `v3` in the URLs your code calls, then rename any use of the fields, query parameters and values listed above, and handle `activities` being a list rather than a single `sig` value. If you use the activity reference lookup, call `/lookup/activityref?activity=...&id=...` instead of `/lookup/sigref?sig=...&id=...`.
### 2.2 ### 2.2
* Renamed AMSAT SIG to "Satellite" as AMSAT is a specific organisation not just a general term for satellite QSOs * Renamed AMSAT SIG to "Satellite" as AMSAT is a specific organisation not just a general term for satellite QSOs
* Removed `alert_type` from alert data. Contest, DXpedition and Satellite alerts now give those values in `sig` instead, alongside the existing outdoor activity programmes. Teeeeechnically a breaking change but AlertType is so new I doubt anyone is using it yet, so slipped this one in anyway. Sorry :) * Removed `alert_type` from alert data. Contest, DXpedition and Satellite alerts now give those values in `sig` instead, alongside the existing outdoor activity programmes. Teeeeechnically a breaking change but AlertType is so new that it's unlikely anyone is using it yet, so this one slipped in anyway. Sorry :)
* Added QRP, RaDAR Rally, /AM and /MM activities * Added QRP, RaDAR Rally, /AM and /MM activities
* Added `has_refs` and `alerts_possible` to Activity data * Added `has_refs` and `alerts_possible` to Activity data
* Added `dx_grid`, `dx_latitude` and `dx_longitude` to alert data * Added `dx_grid`, `dx_latitude` and `dx_longitude` to alert data
@@ -74,7 +74,7 @@ info:
#### Upgrading a client from v1 to v2 API endpoints #### Upgrading a client from v1 to v2 API endpoints
In v2.0 of Spothole, the `v1` API endpoints will be maintained for backwards compatibility, so I don't break everyone's In v2.0 of Spothole, the `v1` API endpoints will be maintained for backwards compatibility, so as not to break everyone's
clients on day one. So if you have written a client against the `v1` API, you shouldn't notice anything breaking. clients on day one. So if you have written a client against the `v1` API, you shouldn't notice anything breaking.
However, you are strongly encouraged to move to `v2` API endpoints as soon as possible. However, you are strongly encouraged to move to `v2` API endpoints as soon as possible.
@@ -88,9 +88,9 @@ info:
top-level `handling` object which in later versions will allow you to control sending spots upstream to cluster and top-level `handling` object which in later versions will allow you to control sending spots upstream to cluster and
xOTA sites. xOTA sites.
I don't think anyone was sending me QRZ/HamQTH credentials from their clients, or querying the `/options` call, so It's unlikely that any third-party clients were sending QRZ/HamQTH credentials to Spothole, or querying the
updating clients for changes there should be confined to Spothole's own web interface. If you were doing that and `/options` call, so updating clients for changes there should be confined to Spothole's own web interface. If you
I haven't noticed, please carefully note the breaking changes listed above. were doing that, please carefully note the breaking changes listed above.
### 1.5 ### 1.5
@@ -121,6 +121,7 @@ info:
* Removed band colour and icon information from spots. * Removed band colour and icon information from spots.
* Moved activation_score from top-level in Spot and Alert to be part of the SIGRef * Moved activation_score from top-level in Spot and Alert to be part of the SIGRef
contact: contact:
name: Ian Renton, M0TRT (Spothole developer)
email: ian@ianrenton.com email: ian@ianrenton.com
license: license:
name: The Unlicense name: The Unlicense
@@ -128,7 +129,10 @@ info:
version: 3.0 version: 3.0
servers: servers:
- url: /api/v3
description: This Spothole server
- url: https://spothole.app/api/v3 - url: https://spothole.app/api/v3
description: The main Spothole server
tags: tags:
- name: Spots - name: Spots
@@ -547,7 +551,7 @@ components:
name: X-API-Key name: X-API-Key
in: header in: header
description: > description: >
An API key issued by the server operator. On servers that protect spot submission, a valid API key allows An API key issued by the server owner. On servers that protect spot submission, a valid API key allows
the spot to be submitted without a CAPTCHA token. Not required on servers that don't protect spot submission. the spot to be submitted without a CAPTCHA token. Not required on servers that don't protect spot submission.
schema: schema:
type: string type: string
+1 -1
View File
@@ -130,7 +130,7 @@
const ALLOW_UPSTREAM_SPOTTING = {% raw safe_json_dumps(web_ui_options["allow_upstream_spotting"]) %}; const ALLOW_UPSTREAM_SPOTTING = {% raw safe_json_dumps(web_ui_options["allow_upstream_spotting"]) %};
</script> </script>
<script src="/static/js/add-spot.js?v=1790521969"></script> <script src="/static/js/add-spot.js?v=1790524051"></script>
<script>$(document).ready(function () { <script>$(document).ready(function () {
$("#nav-link-add-spot").addClass("active"); $("#nav-link-add-spot").addClass("active");
}); <!-- highlight active page in nav --></script> }); <!-- highlight active page in nav --></script>
+1 -1
View File
@@ -87,7 +87,7 @@
</div> </div>
<script src="/static/js/alerts.js?v=1790521969"></script> <script src="/static/js/alerts.js?v=1790524051"></script>
<script>$(document).ready(function () { <script>$(document).ready(function () {
$("#nav-link-alerts").addClass("active"); $("#nav-link-alerts").addClass("active");
}); <!-- highlight active page in nav --></script> }); <!-- highlight active page in nav --></script>
+2 -2
View File
@@ -82,8 +82,8 @@
const BANDS = {% raw safe_json_dumps(options["bands"]) %}; const BANDS = {% raw safe_json_dumps(options["bands"]) %};
</script> </script>
<script src="/static/js/spotsbandsandmap.js?v=1790521969"></script> <script src="/static/js/spotsbandsandmap.js?v=1790524051"></script>
<script src="/static/js/bands.js?v=1790521969"></script> <script src="/static/js/bands.js?v=1790524051"></script>
<script>$(document).ready(function () { <script>$(document).ready(function () {
$("#nav-link-bands").addClass("active"); $("#nav-link-bands").addClass("active");
}); <!-- highlight active page in nav --></script> }); <!-- highlight active page in nav --></script>
+6 -6
View File
@@ -1,6 +1,6 @@
{% extends "skeleton.html" %} {% extends "skeleton.html" %}
{% block head_extra %} {% block head_extra %}
<link rel="stylesheet" href="/static/css/style.css?v=1790521969" type="text/css"> <link rel="stylesheet" href="/static/css/style.css?v=1790524050" type="text/css">
<link href="/static/vendor/css/bootstrap-5.3.8.min.css" rel="stylesheet"> <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/fontawesome-6.7.2.min.css" rel="stylesheet">
<link href="/static/vendor/css/solid-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; window.fetchEventSource = fetchEventSource;
</script> </script>
<script src="/static/js/utils.js?v=1790521969"></script> <script src="/static/js/utils.js?v=1790524050"></script>
<script src="/static/js/ui-ham.js?v=1790521969"></script> <script src="/static/js/ui-ham.js?v=1790524050"></script>
<script src="/static/js/geo.js?v=1790521969"></script> <script src="/static/js/geo.js?v=1790524050"></script>
<script src="/static/js/common.js?v=1790521969"></script> <script src="/static/js/common.js?v=1790524050"></script>
{% end %} {% end %}
{% block body %} {% block body %}
<div class="container"> <div class="container">
@@ -69,7 +69,7 @@
<div id="footer" class="hideonmobile hideonmap"> <div id="footer" class="hideonmobile hideonmap">
<footer class="d-flex flex-wrap justify-content-between align-items-center py-3 my-4 border-top"> <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" <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> class="text-body-secondary">Ian, M0TRT</a>
and <a href="/help/thanks" class="text-body-secondary">other contributors.</a></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 <p class="col-md-4 mb-0 justify-content-center text-body-secondary text-center">Spothole
v{{software_version}}</p> v{{software_version}}</p>
+1 -1
View File
@@ -284,7 +284,7 @@
</div> </div>
<script src="/static/vendor/js/chart-4.4.9.umd.min.js"></script> <script src="/static/vendor/js/chart-4.4.9.umd.min.js"></script>
<script src="/static/js/conditions.js?v=1790521969"></script> <script src="/static/js/conditions.js?v=1790524051"></script>
<script>$(document).ready(function () { <script>$(document).ready(function () {
$("#nav-link-conditions").addClass("active"); $("#nav-link-conditions").addClass("active");
}); <!-- highlight active page in nav --></script> }); <!-- highlight active page in nav --></script>
+13 -2
View File
@@ -5,8 +5,19 @@
<h2>Help and Information</h2> <h2>Help and Information</h2>
<p>Welcome to Spothole's help pages.</p> <p>Welcome to Spothole's help pages.</p>
<p>Spothole is a utility to aggregate spots from amateur radio DX clusters and xOTA spotting sites, and provide an <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. (If that sounds like nonsense to you, I recommend open JSON API as well as a website to browse the data. (If that sounds like nonsense to you, start with
starting with the <a href="/help/faq">FAQ</a>!)</p> the <a href="/help/faq">FAQ</a>!)</p>
{% if server_owner_callsign == "M0TRT" %}
<p>You're using the "main" Spothole server at <a href="https://spothole.app">spothole.app</a>, which is run by
the software's main developer, <a href="https://ianrenton.com">Ian Renton, M0TRT</a>. You can contact Ian
directly for any queries about it.</p>
{% else %}
<p>Spothole is open-source software that anyone can run. The particular server you are using right now is run by
an amateur radio operator with callsign <strong>{{ server_owner_callsign }}</strong>, and not by the
oritinal developer of the software. This means that if you have any problems or questions about this server,
you should in the first instance contact them before contacting the Spothole developers. See
<a href="/help/privacy">Privacy and Legal Information</a> for details.</p>
{% end %}
<p>In the sections below, you can find more information about what Spothole is, and how to use it.</p> <p>In the sections below, you can find more information about what Spothole is, and how to use it.</p>
<ul> <ul>
<li><a href="/help/about">About Spothole</a></li> <li><a href="/help/about">About Spothole</a></li>
+7 -7
View File
@@ -34,20 +34,20 @@
</li> </li>
</ol> </ol>
<p>Spothole's web interface exists not just for the end user, but also as a reference implementation for the API, so <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> it demonstrates both methods of filtering.</p>
<h4 class="mt-4">How is this better than DXheat, DXsummit, POTA's own website, etc?</h4> <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>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> <p>I think it's got three key advantages over those sites:</p>
<ol> <ol>
<li>It provides a public, <a href="/apidocs">well-documented API</a> with an <a href="/apidocs/openapi.yml">OpenAPI <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 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 they want people to use their web page. Spothole has a nice web page too, 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 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 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. the fun bit of writing your own application.
</li> </li>
<li>It grabs data from a lot more sources. I've seen other sites that pull in DX Cluster and POTA spots <li>It grabs data from a lot more sources. Other sites pull in DX Cluster and spots from a few "on the air"
together, but nothing on the scale of what Spothole supports. activities together, but nothing on the scale of what Spothole supports.
</li> </li>
<li>Spothole is open source, so anyone can contribute the code to support a new data source or add new features, <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. and share them with the community.
@@ -70,9 +70,9 @@
waiting around three minutes to see a newly added spot, or 40 minutes to see a newly added alert.</p> 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> <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, <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. modify it however you like, you can claim you wrote it and charge people £1000 for a copy, it really doesn't
(Please don't do the last one. But if you're using my code for something cool, it would be nice to hear from matter. (Please don't do the last one. But if you're using Spothole's code for something cool, its developer,
you!)</p> <a href="https://ianrenton.com">Ian, M0TRT</a>, would love to hear from you!)</p>
<h4 class="mt-4">What commands are supported in the telnet server?</h4> <h4 class="mt-4">What commands are supported in the telnet server?</h4>
<p>Currently, <code>exit</code>, and nothing else. Support for some DXSpider-like commands may be added to Spothole <p>Currently, <code>exit</code>, and nothing else. Support for some DXSpider-like commands may be added to Spothole
in due course, but at the moment if you want to add Spothole as a telnet cluster data source to your desktop in due course, but at the moment if you want to add Spothole as a telnet cluster data source to your desktop
+10 -6
View File
@@ -27,16 +27,20 @@
like.</p> like.</p>
<h2 class="mt-4">Legal</h2> <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 <p>This server is run by an amateur radio operator with callsign {{ server_owner_callsign }}. You should contact them
you have any issues with the website.</p> with any questions about privacy or legal matters relating to this server, or if you have any issues with the
<p>Spothole exists as an aggregator of data from many other sources. To the best of my knowledge, all these sources website.</p>
either:</p> <p>Spothole exists as an aggregator of data from many other sources. To the best of the Spothole developers' knowledge,
all these sources either:</p>
<ul> <ul>
<li>State licence terms that make their data acceptable for use on a non-profit website like this one, or,</li> <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>Require you to ask permission before using their data, which has been done, or,</li>
<li>Have an open API and are happy with third-party use.</li> <li>Have an open API and are happy with third-party use.</li>
</ul> </ul>
<p>If you represent one of these data sources and would like it removed from Spothole, please let me know.</p> <p>If you represent one of these data sources and would like it removed, there are two options. The owner of this
server, {{ server_owner_callsign }}, can disable it on this server straight away. To have it removed from the
Spothole software itself, so that future versions of Spothole no longer support it on any server, please contact
Spothole's developer, <a href="https://ianrenton.com">Ian Renton, M0TRT</a>.</p>
<p>Spothole does not produce any real data of its own. Information such as spots and alerts that Spothole displays are <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 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> on their terms and conditions.</p>
+3 -3
View File
@@ -40,8 +40,8 @@
Vestigios de España (DMVE), Diploma Estaciones de Ferrocarril de España (DEFE), Diploma Teatri Musei e Belle Vestigios de España (DMVE), Diploma Estaciones de Ferrocarril de España (DEFE), Diploma Teatri Musei e Belle
Arti (DTMBA), British Inland Waterways on the Air (BIWOTA), Castles on the Air (COTA), Polish Gmina Award (PGA), Arti (DTMBA), British Inland Waterways on the Air (BIWOTA), Castles on the Air (COTA), Polish Gmina Award (PGA),
Diplôme des Moulins de France (DMF), RaDAR Rally, and Toilets on the Air.</p> Diplôme des Moulins de France (DMF), RaDAR Rally, and Toilets on the Air.</p>
<p>As of the time of writing in August 2026, I think Spothole captures most radio programmes that have a <p>As of the time of writing in August 2026, Spothole should capture most radio programmes that have a defined,
defined, downloadable reference list, and almost certainly those that have a spotting/alerting API. If you know downloadable reference list, and almost certainly those that have a spotting/alerting API. If you know of one
of one I've missed, please let me know!</p> that's missing, please let Spothole's developers know!</p>
{% end %} {% end %}
+2 -2
View File
@@ -2,7 +2,7 @@
{% block help_content %} {% block help_content %}
<h2 class="mt-4">Thanks</h2> <h2 class="mt-4">Thanks</h2>
<p>The software was written by <a href="https://ianrenton.com">Ian Renton, MØTRT</a> with code contributions by <p>The software was written by <a href="https://ianrenton.com">Ian Renton, M0TRT</a> with code contributions by
Steven, M1SDH.</p> Steven, M1SDH.</p>
<p>This project would not have been possible without those volunteers who have taken it upon themselves to run DX <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 clusters, xOTA programmes, DXpedition lists, callsign lookup databases, solar conditions and propagation
@@ -14,7 +14,7 @@
Norby LX1NO, Andrew VK3ARR, Mario DL4MFM, Mark M5TEA, Michael G7VJR, Rob G7LAS, Ed DD5LP, Raph F4LUB, Norby LX1NO, Andrew VK3ARR, Mario DL4MFM, Mark M5TEA, Michael G7VJR, Rob G7LAS, Ed DD5LP, Raph F4LUB,
Luc ON7KEC, Richard GD4OFB, Daniel PY2TDB, Alan VK1AO, Andrew WK1AD, Ullrich DF5WC, Wayne N3CDF, Jonathan G4IVV, Luc ON7KEC, Richard GD4OFB, Daniel PY2TDB, Alan VK1AO, Andrew WK1AD, Ullrich DF5WC, Wayne N3CDF, Jonathan G4IVV,
Erik N2EPE, Sorin YO9TSN, Matt HB9HWI, Priit ES1TEB, Leigh KG7WED, Jouni OH3CUF, Onno VK6FLAB, Bruce WA7BNM, and Erik N2EPE, Sorin YO9TSN, Matt HB9HWI, Priit ES1TEB, Leigh KG7WED, Jouni OH3CUF, Onno VK6FLAB, Bruce WA7BNM, and
Larry F5PYI. (If I've forgotten you, let me know!)</p> Larry F5PYI. (If you've been forgotten, please let Ian know!)</p>
<p>Spothole is also dependent on a number of Python libraries, such as pyhamtools, and many JavaScript <p>Spothole is also dependent on a number of Python libraries, such as 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 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> GeoJSON files for CQ and ITU zones from HA8TKS.</p>
+8 -8
View File
@@ -25,16 +25,16 @@
it from a terminal with <code>telnet {{ telnet_server_address }} {{ telnet_server_port }}</code>. it from a terminal with <code>telnet {{ telnet_server_address }} {{ telnet_server_port }}</code>.
</li> </li>
{% end %} {% end %}
<li>You can <b>write your own client using the Spothole API</b>, using the main Spothole instance to provide <li>You can <b>write your own client using the Spothole API</b>, using the main Spothole instance at
data, and do whatever you like with it. The <a href="/help/usage/clients">Writing your own Client</a> page <a href="https://spothole.app">spothole.app</a> (or any other Spothole server) to provide data, and do whatever
contains guidance on how to do this, and the full API docs can be found <a href="/apidocs">here</a>. You can you like with it. The <a href="/help/usage/clients">Writing your own Client</a> page contains guidance on how to
also find reference implementations in the form do this, and the full API docs can be found <a href="/apidocs">here</a>. You can also find reference
of Spothole's own web-based front end, plus my other two tools built on Spothole: <a implementations in the form of Spothole's own web-based front end, plus two other tools by Spothole's developer
href="https://fieldspotter.radio">Field Spotter</a> and the <a href="https://qsomap.m0trt.radio">QSO that are built on it: <a href="https://fieldspotter.radio">Field Spotter</a> and the <a
Map Tool</a>. href="https://qsomap.m0trt.radio">QSO Map Tool</a>.
</li> </li>
<li>If you want to <b>run your own version of Spothole</b> so you can customise the configuration, such as <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 <a enabling sources that are disabled on the main instance, you can do that too. The <a
href="/help/usage/running">Running your own Copy</a> page explains how to set up Spothole, and href="/help/usage/running">Running your own Copy</a> page explains how to set up Spothole, and
there are further pages on how to get it <a href="/help/usage/systemd">auto-starting with systemd</a>, there are further pages on how to get it <a href="/help/usage/systemd">auto-starting with systemd</a>,
<a href="/help/usage/nginx">using an nginx reverse proxy and setting up HTTPS support with certbot</a>, or <a href="/help/usage/nginx">using an nginx reverse proxy and setting up HTTPS support with certbot</a>, or
+24 -22
View File
@@ -30,7 +30,8 @@
"alerts"/"upcoming" page simply query the main spot API on a timer, whereas the spots, map and bands pages "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. combine this approach with using the Server-Sent Events (SSE) endpoint to update live.
</li> </li>
<li>Let me know if you get stuck, I'm happy to help.</li> <li>If you get stuck, get in touch with Spothole's developers who will be happy to help.
</li>
</ul> </ul>
<p>If you're fetching spot data, you're unlikely to need a sub-minute refresh time. For example, Spothole only queries <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 the POTA API once every two minutes, so if your client is interested in POTA data there's no need to poll Spothole
@@ -43,9 +44,9 @@
</p> </p>
<p>Remember, here at Spothole Inc. we offer an industry-standard "five nines" uptime on our server, with our own unique <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. 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 <code>spothole.app</code> runs on the same server a Minecraft server and all sorts of other stuff. It might go down
all means base your own project on data from the main server if you like, but if you want any control over without warning. By all means base your own project on data from the main server if you like, but if you want any
reliability and downtime, please run your own copy instead.)</p> control over reliability and downtime, please run your own copy instead.)</p>
<h3 class="mt-4" id="submitting-spots">Submitting Spots</h3> <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. <p>As well as reading data, clients can submit new spots to Spothole using the "add spot" API endpoint, e.g.
@@ -53,45 +54,46 @@
to other services such as the DX cluster. Check the <code>spot_allowed</code> and 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> <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, <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, which means you will need an <strong>API key</strong>. API keys are issued by the owner 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 not by the Spothole developer. This server is run by <strong>{{ server_owner_callsign }}</strong>, so get in touch
have a key, send it in the <code>X-API-Key</code> header of each add spot request. For example:</p> with them 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 \ <pre><code>curl --request POST \
--header "Content-Type: application/json" \ --header "Content-Type: application/json" \
--header "X-API-Key: your-api-key-here" \ --header "X-API-Key: your-api-key-here" \
--data '{"spot":{"dx_call":"M0TRT","time":1760019539,"freq":14200000,"de_call":"M0TRT"}}' \ --data '{"spot":{"dx_call":"M0TRT","time":1760019539,"freq":14200000,"de_call":"M0TRT"}}' \
https://spothole.app/api/v3/spot</code></pre> 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 <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 don't embed it in JavaScript or anywhere else your users could extract it. If a key is misused, the server owner
can revoke it, and spot submission from your client will stop working. Servers that don't protect spot submission 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> 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> <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 <p>The conditions are simple, and hopefully not onerous. They probably aren't legally binding, and nobody is likely to
for the Spothole API. These probably aren't legally binding, and I'm just a random guy on the internet, I'm not sue you for breaching them. But having them in place ensures Spothole can continue to operate without the people
going to sue you for breaching them. But having these conditions in place ensures Spothole can continue to operate running it burning out, and with no payment required. In the collaborative and respectful tradition of amateur
without me burning out and with no payment required. In the collaborative and respectful tradition of amateur radio, radio, please read and understand them.</p>
please read and understand them.</p>
<p>When creating a Spothole client, you agree that:</p> <p>When creating a Spothole client, you agree that:</p>
<ul> <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 <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, Actual Intelligence before asking the developer or server owner for help. If you don't understand the code,
not me. please ask the AI to fix it, not them.
</li> </li>
<li>When querying the API, you will send a useful referrer or user agent string that will help me uniquely identify <li>When querying the API, you will send a useful referrer or user agent string that will help the server owner
your software. This will allow me to diagnose the problem and figure out who to talk to if Spothole starts uniquely identify your software. If their server starts receiving too many, or malformed, requests, this will
receiving too many, or malformed, requests. allow them to diagnose the problem and figure out who to talk to about it.
</li> </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>You set a sensible query rate and will not try to take down the server by bombarding it with tons of requests.
</li> </li>
<li>You are OK with the server being down occasionally. There is no uptime guarantee. This is a hobby project and <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. sometimes stuff will accidentally break.
</li> </li>
<li>You check for API changes occasionally, e.g. using <a <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 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 notifications</a>, or by <a href="https://mastodon.radio/@ian">following Spothole's developer on
back on the Spothole documentation every so often. I will do my best to stop updates breaking older client code, Mastodon</a>, or just by checking back on the Spothole documentation every so often. Every effort is made to stop
but eventually I will need to turn off old versions of the API for my own sanity. updates breaking older client code, but eventually old versions of the API will need to be turned off for the
developer's sanity.
</li> </li>
</ul> </ul>
+8 -7
View File
@@ -8,11 +8,12 @@
<p>The source code can be found at <a href="https://git.ianrenton.com/ian/spothole">https://git.ianrenton.com/ian/spothole</a>. <p>The source code can be found at <a href="https://git.ianrenton.com/ian/spothole">https://git.ianrenton.com/ian/spothole</a>.
</p> </p>
<p>I'm sorry this isn't on GitHub. There's too much noise on there now it's been given over to Copilot agents. If you <p>Sorry this isn't on GitHub. There's too much noise on there now it's been given over to Copilot agents. If you
want to contribute code changes, that unfortunately means you'll have to sign up for an account on my Forgejo want to contribute code changes, that unfortunately means you'll have to sign up for an account on the developer's
server (linked above), or email me patch files the old-fashioned way. I'd hoped that Forgejo federation would be Forgejo server (linked above), or email patch files to <a href="https://ianrenton.com">Ian, M0TRT</a> the
working soon, so that at least you could use a Codeberg account rather than a new login specifically for my old-fashioned way. The hope was that Forgejo federation would be working soon, so that at least you could use a
instance, but unfortunately we're still waiting on that one!</p> Codeberg account rather than a new login specifically for that instance, but unfortunately we're still waiting on
that one!</p>
<h3 class="mt-4">Code structure</h3> <h3 class="mt-4">Code structure</h3>
<p>To navigate your way around the source code, this list may help.</p> <p>To navigate your way around the source code, this list may help.</p>
@@ -99,7 +100,7 @@
<p>Finally, simply add the appropriate config to the <code>spot_providers</code> section of <code>config.yml</code>, and <p>Finally, simply add the appropriate config to the <code>spot_providers</code> section of <code>config.yml</code>, and
your provider should be your provider should be
instantiated on startup.</p> instantiated on startup.</p>
<p>The same approach as above is also used for alerts, and other types of providers. Give me a shout if you need any <p>The same approach as above is also used for alerts, and other types of providers. Give Spothole's developers a shout
advice.</p> if you need any advice.</p>
{% end %} {% end %}
+2 -2
View File
@@ -85,8 +85,8 @@
} }
</code></pre> </code></pre>
<p>One further change you might want to make to the file above is the <code>add_header <p>One further change you might want to make to the file above is the <code>add_header
Access-Control-Allow-Origin</code> statements. These are what's used on my own Spothole server to make sure that Access-Control-Allow-Origin</code> statements. These are what's used on the main <code>spothole.app</code> server to make
other third-party web-based software can get the data from my instance, and applies to any endpoint underneath sure that other third-party web-based software can get the data from that instance, and applies to any endpoint underneath
<code>/api</code>. If you want <em>your</em> Spothole instance to be set up the same way, so that others can write <code>/api</code>. If you want <em>your</em> Spothole instance to be set up the same way, so that others can write
software in JavaScript that can access it, leave this intact. But if you want your Spothole instance to only be software in JavaScript that can access it, leave this intact. But if you want your Spothole instance to only be
usable by scripts running on the web server you write, you can remove these lines. (Note that this doesn't stop usable by scripts running on the web server you write, you can remove these lines. (Note that this doesn't stop
+3 -3
View File
@@ -27,9 +27,9 @@ cp config-example.yml config.yml
<p><code>config.yml</code> has an entry for a Clublog API key. If provided, this will allow Spothole to retrieve some <p><code>config.yml</code> has an entry for a Clublog API key. If provided, this will allow Spothole to retrieve some
more information about DX spots. The software will work just fine without it, but you may find a few country flags more information about DX spots. The software will work just fine without it, but you may find a few country flags
etc. are less accurate or missing. Clublog API keys are free, but you'll need to get your own by submitting a etc. are less accurate or missing. Clublog API keys are free, but you'll need to get your own by submitting a
helpdesk ticket and explaining what you'll use it for. The admin team are happy with the rate of requests made by my helpdesk ticket and explaining what you'll use it for. The admin team are happy with the rate of requests made by the
Spothole server, so unless you change the source code of yours to radically increase the rate of querying Clublog, main <code>spothole.app</code> server, so unless you change the source code of yours to radically increase the rate
I'm sure they will be fine with your server too.</p> of querying Clublog, they should be fine with your server too.</p>
<p>If your server is public and allows spots to be submitted, you may want to protect it from bots and spammers by <p>If your server is public and allows spots to be submitted, you may want to protect it from bots and spammers by
setting <code>protect_spot_submission</code> to <code>true</code> and setting the reCAPTCHA keys in setting <code>protect_spot_submission</code> to <code>true</code> and setting the reCAPTCHA keys in
<code>config.yml</code>. Users of the web interface will then need to solve a CAPTCHA to submit a spot. Third-party <code>config.yml</code>. Users of the web interface will then need to solve a CAPTCHA to submit a spot. Third-party
+1 -1
View File
@@ -6,7 +6,7 @@
<p>As well as a web interface and an HTTP API, Spothole offers a telnet server. This can be used to integrate Spothole's <p>As well as a web interface and an HTTP API, Spothole offers a telnet server. This can be used to integrate Spothole's
data into a traditional desktop logging program. The data Spothole produces is compatible with DXSpider, and data into a traditional desktop logging program. The data Spothole produces is compatible with DXSpider, and
therefore many loggers should accept it with no problems.</p> therefore many loggers should accept it with no problems.</p>
<p>This is a relatively new feature however, so if you run into problems, please do let me know.</p> <p>This is a relatively new feature however, so if you run into problems, please let Spothole's developers know.</p>
<p>The one caveat with the Spothole telnet server is that <em>it does not support any commands</em>, other than <p>The one caveat with the Spothole telnet server is that <em>it does not support any commands</em>, other than
<code>exit</code> or <code>bye</code>. <code>exit</code> or <code>bye</code>.
You cannot therefore issue commands to retrieve past entries, set up filters, etc. If you need to filter the data, You cannot therefore issue commands to retrieve past entries, set up filters, etc. If you need to filter the data,
+2 -2
View File
@@ -115,8 +115,8 @@
const CARTODB_API_KEY = "{{ web_ui_options.get('cartodb_api_key', '') }}"; const CARTODB_API_KEY = "{{ web_ui_options.get('cartodb_api_key', '') }}";
</script> </script>
<script src="/static/js/spotsbandsandmap.js?v=1790521968"></script> <script src="/static/js/spotsbandsandmap.js?v=1790524050"></script>
<script src="/static/js/map.js?v=1790521968"></script> <script src="/static/js/map.js?v=1790524050"></script>
<script>$(document).ready(function () { <script>$(document).ready(function () {
$("#nav-link-map").addClass("active"); $("#nav-link-map").addClass("active");
}); <!-- highlight active page in nav --></script> }); <!-- highlight active page in nav --></script>
+2 -2
View File
@@ -127,8 +127,8 @@
</div> </div>
<script src="/static/js/spotsbandsandmap.js?v=1790521968"></script> <script src="/static/js/spotsbandsandmap.js?v=1790524050"></script>
<script src="/static/js/spots.js?v=1790521968"></script> <script src="/static/js/spots.js?v=1790524050"></script>
<script>$(document).ready(function () { <script>$(document).ready(function () {
$("#nav-link-spots").addClass("active"); $("#nav-link-spots").addClass("active");
}); <!-- highlight active page in nav --></script> }); <!-- highlight active page in nav --></script>
+1 -1
View File
@@ -96,7 +96,7 @@
</div> </div>
</div> </div>
<script src="/static/js/status.js?v=1790521969"></script> <script src="/static/js/status.js?v=1790524051"></script>
<script> <script>
$(document).ready(function () { $(document).ready(function () {
$("#nav-link-status").addClass("active"); $("#nav-link-status").addClass("active");