# ![Spothole](/static/img/logo.png)

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, and its own telnet server for integration with desktop loggers.

A "main" or example server runs at [https://spothole.app](https://spothole.app/) in case you'd like to try it out.

![Screenshot](/images/screenshot.png)

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 large 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.

The API is deliberately well-defined with an OpenAPI specification and auto-generated API documentation. 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.

Spothole itself is also open source, Public Domain licenced code that anyone can take and modify.

Supported data sources include DX Clusters, the Reverse Beacon Network (RBN), the APRS Internet Service (APRS-IS), POTA,
SOTA, WWFF, GMA, WWBOTA, HEMA, Parks 'n' Peaks, ZLOTA, WOTA, BOTA, LLOTA, WWTOTA, Tiles on the Air, the UK Packet
Repeater Network, NG3K, and any site based on the xOTA software by nischu. It also integrates with QRZ.com and HamQTH,
retrieves solar data from various sources, provides information about upcoming contests, and more.

You can read more about Spothole on [the "About" page of the main server instance](https://spothole.app/about).

![Screenshot](/images/screenshot2.png)

![Screenshot](/images/screenshot3.png)

## Accessing the public version

You can access the public version's web interface at [https://spothole.app](https://spothole.app), and
see [https://spothole.app/apidocs](https://spothole.app/apidocs) for the API details.

This is a Progressive Web App, so you can also "install" it to your Android or iOS device by accessing it in Chrome or
Safari respectively, and following the menu-driven process for installing PWAs.

You are more than welcome to use the data and the API that Spothole provides to power your own software, to run your own
Spothole server, or to modify it in any way. More details can be found in the following sections:

* [Embedding Spothole in another website](docs/embedding.md)
* [Writing your own client](docs/clients.md)
* [Running your own copy](docs/running.md)
    * [nginx reverse proxy configuration](docs/nginx.md)
    * [systemd service file](docs/systemd.md)
    * [Running in Docker](docs/docker.md)
    * [Use of multiple cluster logins](docs/multicluster.md)
* [Modifying the source code](docs/modifying.md)

![Screenshot](/images/screenshot4.png)

## Thanks

[Spothole's "About" page](https://spothole.app/about) contains the full details of the thanks I owe to the various
programme teams, software library providers, bug fixers etc. The extra detail below contains the extra detail of
specific files in this repository which are not all my own work and may be subject to other licences.

The project contains GeoJSON files for CQ and ITU zones, in the `/datafiles/` directory. These are MIT-licenced and, to
my knowledge, created by HA8TKS for his CQ and ITU zone layers for Leaflet. `/datafiles` also contains a
`MUNICIPIOS.csv` file, from the "Nomenclátor Geográfico de Municipios y Entidades de Población" data set sourced from
[el Centro Nacional de Información Geográfica](https://centrodedescargas.cnig.es/CentroDescargas/home).
`didbase-stations.csv` and the TOTA file were created by me based on publicly available data from GIRO and from maps of
conference centres.

The project contains a set of flag icons generated using the "Noto Color Emoji" font on a Debian system, in the
`/static/img/flags/` directory.

The software uses a number of Python libraries as listed in `requirements.txt`, and a number of JavaScript libraries
which are self-hosted in the `/static/vendor/` directory. This project would not have been possible without these
libraries, so many thanks to their developers. These libraries are subject to their own licences and are not covered by
the overall licence declared in Spothole's `LICENSE` file.

Sound effects are CC0-licenced and sourced from [Pixabay](https://pixabay.com).