# ![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.

![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.

Additional Special Interest Groups (SIGs) without their own specific data source include WAB, WAI and DME.

![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)

## Thanks

As well as being my work, I have also gratefully received feature patches from Steven, M1SDH.

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.
This project would not have been possible without these libraries, so many thanks to their developers.

### Third Party Libraries

A number of third-party libraries are self-hosted in the `/static/vendor/` directory. These files are subject to
their own licences and are not covered by the overall licence declared in the `LICENSE` file.

A number of third-party libraries are self-hosted in the `/webassets/vendor/` directory. These files are subject to
their own licences and are not covered by the overall licence declared in the `LICENSE` file.

Particular thanks go to country-files.com for providing country lookup data for amateur radio, to K0SWE
for [this JSON-formatted DXCC data](https://github.com/k0swe/dxcc-json/), and to the developers of `pyhamtools` for
making it easy to use country-files.com data as well as QRZ.com and Clublog lookup.

Amateur radio clusters, outdoor programmes, propagation data providers etc. are almost all volunteer-run services that
make no or little profit, and are done for the love of amateur radio. Services like Spothole, which build on top of
them, are truly standing on the shoulders of giants. None of this would have been possible without the hard work and
dedication of many other people within the amaetur radio community.

The project's name was suggested by Harm, DK4HAA. Thanks!