Lighthouses Worldwide - Web app map of lighthouse signals worldwide
- Oliver Heisel
- Jul 22
- 10 min read
Lighthouses Worldwide is an interactive web application for displaying real lighthouses and their light signals worldwide. It is based on maritime OpenStreetMap seamark data, which is automatically retrieved via the Overpass API, processed with Python, and published as browser-optimized datasets.
The application allows users to search for lighthouses geographically, filter by light color and multicolored sectors, and display detailed information about their signal characteristics. This includes, among other things, color, signal sequence, repetition period, and the geographical orientation of individual light sectors.
In addition to the interactive map, the project provides the processed data via stable public download links. Compressed Gzip files are also available for regular or automated downloads.
The map can also be connected to an external detail or receiver application via a URL-based handover. A selected lighthouse is passed to the configured application as a Base64URL-encoded JSON packet. No login, database, or server-side session is required.
The rich dataset generated at the time of documentation contains 18,619 lighthouse and signal records . The application, daily data retrieval, data preparation, and deployment are all managed via GitHub. The GitHub Pages application is connected to the user's own domain via Cloudflare. Cloudflare handles DNS management, encrypted delivery over HTTPS, and upstream processing of public web traffic. No dedicated server infrastructure is required.
Project link: https://lighthouse.heiselanalytics.cloud/
Initial situation
Information on lighthouses and their light signals is available in OpenStreetMap via the Seamark data model. However, the raw data is not directly suitable for a user-friendly map application or standardized further processing.
The results from the Overpass API contain different OpenStreetMap element types, nested tag structures, and numbered fields for individual light sectors. The geographic location is also stored differently depending on the element type. While nodes already have direct coordinates, ways consist of multiple geographic points.
For users, working directly with this data would be time-consuming. They would have to understand the OpenStreetMap schema, manually identify suitable entries, and interpret the relevant seamark fields themselves.
The raw data was also of limited use for other applications. A receiving application would have to load the complete Overpass data, search for the desired lighthouse, and translate the complex tag structures into a usable format itself.
In addition, the aim was not only to use the processed data sets within the map, but also to make them available for in-house analyses, applications and recurring data processes.
This resulted in the following requirements:
interactive world map for geographical selection
Automatic processing of OpenStreetMap seamark data
Filtering by light colors and multicolored sectors
understandable presentation of the signal characteristics
geographical visualization of the light sectors
direct links to individual lighthouses
URL-based handoff to external applications
Public downloads in various data formats
Suitable files for regular automated downloads
daily update of source data
Operation without its own server or database
Defined solution
A static web application was developed, based on JSON datasets prepared daily. The raw OpenStreetMap data is not processed only upon a user request. Instead, it is automatically retrieved, normalized, and provided as optimized files for the map and external applications.
Interactive world map
Upon opening the application, an interactive world map is displayed immediately. Users can freely move and zoom the map and filter the visible lighthouses according to various signal characteristics.
Available options include:
Filtering according to one or more light colors
Targeted display of multicolored lighthouses
geographical selection via world map
Display of signal sequence and repetition period
Display of existing light sectors
direct linking of individual lighthouses
Passing a selection to an external application
At low zoom levels, the lighthouses are displayed as compact colored markers. At higher zoom levels, the display changes to graphic sector symbols for suitable datasets. This makes the spatial orientation of the respective light sectors visible in addition to the light color.
Clicking on a marker opens an information window with the name, signal characteristics, main color, and available sector data.
Downloads and handoff links
An additional page provides the current datasets for direct download and documents how the map can be connected to a custom application. The files have stable public URLs, allowing them to be downloaded manually or integrated into custom scripts, data pipelines, or scheduled update processes.
Each dataset is available in both an uncompressed JSON file and a compressed Gzip version. The compressed version is recommended for frequent or scheduled downloads, as it requires significantly less data.
URL handover
An external application can specify its own target address via the `url` parameter when opening the map. This address is then used as the base URL for all handover links within the lighthouse popups.
Example:
The procedure is as follows:
The external application opens the map using its URL as an encoded URL parameter.
The map uses this address as the destination for the detail links.
A user selects a lighthouse on the map.
The popup generates a link to the specified base URL.
The information for the selected lighthouse is appended to the cmd parameter.
The receiving application decodes the parameter and processes the contained JSON.
The link text can be customized using the linkText parameter:
https://lighthouse.heiselanalytics.cloud/?url=https%3A%2F%2Fexample.com%2Flighthouse&linkText=Open%20in%20Lighthouse%20AppThe following parameter names are also supported:
link_text
linkLabel
link_label
If no custom link text is specified, the map uses the default: "Link to your lighthouse"
Direct call to a lighthouse
A lighthouse can also be opened directly using its unique card key:
After loading the dataset, the application searches for the matching entry, automatically zooms to its position, and opens the corresponding information window.
In addition to the ID, the following parameters are also supported:
lighthouseId
lighthouse_id
This allows individual lighthouses to be linked directly, for example from documentation, data analyses or external applications.
Results & Added Value
Lighthouses Worldwide was developed from a large and technically complex OpenStreetMap dataset into a directly usable geographic application and public data source.
The dataset generated at the time of documentation contains:
18,619 records
18,017 Nodes
602 Ways
6,666 records with sector information
15,637 data records with identified main period
Users no longer need to analyze raw OpenStreetMap data or seamark tags. Instead, they can find real lighthouses directly on a world map, filter by signal characteristics, and visually verify the relevant properties.
The display of light colors and sectors makes it particularly easy to identify complex or multicolored signals. This allows lighthouses to be selected not only by their name, but also by their position and signal characteristics.
The download page expands the project from a simple map application to a publicly accessible data source. Developers can choose between a compact and an extended dataset and integrate the files into their own processes via stable links.
The Gzip versions significantly reduce the amount of data transferred and are particularly suitable for regularly performed downloads. No separate API query or authentication is required.
URL handover enables easy integration of external applications. All information required for the handover is contained within the generated link. This eliminates the need for user accounts, server-side sessions, or database entries.
A particular advantage lies in the fully automated and low-maintenance deployment. Both the website and the daily data retrieval, data processing, and deployment run via GitHub.
No dedicated server instance is required. Tasks such as operating system updates, server security, container management, database operation, or the maintenance of a public API are completely eliminated.
Despite this static architecture, the data is retrieved and processed daily from OpenStreetMap. Changes to lighthouses or their signal characteristics can thus be automatically incorporated into the published datasets and the map application. The project therefore combines up-to-the-minute information with very low operational complexity.
Technical design
The frontend was developed using HTML, CSS, and JavaScript . Leaflet 1.9.4 is used for map rendering . A dark CARTO basemap serves as the geographical basis.
The application does not use any additional frontend framework, package manager, or bundler. This keeps the technical structure compact and allows it to be deployed entirely as a static website via GitHub Pages.
All interactions take place directly in the browser. These include:
Loading and processing the dataset
Creating the map markers
Filtering of visible lighthouses
Generation of graphic light sectors
Display of detailed information
Processing of URL parameters
Generation of handover links
Base64URL encoding of the selected data
Server-side application logic is not required.
Data source and automated processing
The primary data source is the Overpass API from OpenStreetMap. Nodes and ways containing relevant seamark fields for light signals are retrieved worldwide.
The raw data is processed by a Python script. This process standardizes different OpenStreetMap structures and converts them into compact datasets for the web application and external downloads.
With Nodes, the geographic coordinates can be directly imported. With Ways, a central position for the map display is determined from the associated geometric points.
The processing includes, among other things:
Identification of relevant lighthouses and light objects
Standardization of OpenStreetMap IDs
Extraction of names
Processing of signal sequences
Normalization of light colors
Recognition of main period and signal character
Processing of numbered Seamark sectors
Normalization of geographic angles
Limit of a maximum of five exported sectors per data set
Public datasets
The application provides two different JSON datasets.
Rich Dataset - The Rich Dataset contains the complete information required for enhanced browser rendering and URL handover.
These include, among others:
unique card key
OpenStreetMap type and ID
geographical position
name
Light color
Signal sequence
Main color
Main period
Signal character
Sector information
Compact Dataset - The Compact Dataset is intended for applications that primarily require basic map data and the most important signal characteristics.
It contains, among other things:
unique card key
OpenStreetMap type and ID
geographical position
name
Color
Signal sequence
Browser-side processing
After opening the application, the rich dataset is loaded into the browser.
Due to the large number of data records, the map markers are not generated simultaneously, but rather built up in several processing steps. The application uses browser-based batch processing to ensure that the user interface remains usable even while processing thousands of entries.
Filter changes are also processed gradually. This means the application doesn't have to recalculate all markers simultaneously with every selection.
From zoom level 9 onwards, the display changes from simple color markers to graphic sector symbols, provided that usable angle data is available for the respective lighthouse.
The light sectors are dynamically generated as SVG graphics. Direction, angle range, and color are based on the previously processed Seamark data.
Structure of the handover payload
When the configured popup link is clicked, the application creates a compact JSON object containing the most important properties of the selected lighthouse.
Example:
{
"id": "n13391742",
"name": "Streiti",
"color": "green",
"sequence": "1.5+(4),1.5+(13)",
"main_period": null,
"main_character": "",
"sectors": [
{
"ss": "176",
"se": "217",
"c": "green",
"q": "1.5+(4),1.5+(13)",
"p": 20,
"ch": "Fl"
}
]
}The object is written directly in the browser as a Base64URL-encoded value to the cmd parameter:
The receiving application only needs to read the value of the cmd parameter, decode Base64URL, and process the contained JSON.
The application deliberately only implements the selection and transfer of data. How the receiving system uses the information is left to the discretion of the respective integration.
Hosting, Cloudflare and automatic updates
The entire solution is hosted on GitHub. The static frontend and public download files are provided via GitHub Pages. A dedicated virtual machine, web server, database, or container infrastructure is not required for operation.
The GitHub Pages website is connected to its own domain, lighthouse.heiselanalytics.cloud , via Cloudflare . Cloudflare handles DNS management and delivers the application securely over HTTPS. Public web traffic is routed through the Cloudflare infrastructure before the static content from GitHub Pages is served.
This allows the application to benefit from additional protection mechanisms at the network and web levels. These include, in particular, securing the connection via TLS, filtering suspicious requests, and basic protection against abusive or unusually high data traffic. At the same time, the actual application remains completely static and does not require its own publicly accessible server.
Data retrieval and processing also take place within GitHub. A scheduled GitHub Actions workflow is executed daily at 00:15 UTC.
The workflow:
sets up a Python environment
loads the latest data via the Overpass API
checks the downloaded file for basic validity
executes the Python script for data preparation.
regenerates the JSON, Gzip, and Parquet files
checks if the data has changed
incorporates existing changes into the repository
The updated website is automatically published when changes are made.
This ensures that both the map view and the public download files are updated daily, without the need for a permanently running in-house server.
Version control and deployment
The complete source code, data processing, and deployment configuration are versioned in a GitHub repository.
Once relevant changes are applied to the main branch, a GitHub Actions workflow automatically creates a new GitHub Pages artifact and publishes the updated website.
This means the publicly accessible application reflects the current state of the repository. No manual deployment step is required.
Storage and data protection
The application has:
no user accounts
no proprietary database
no server-side sessions
No saving of selected lighthouses
No backend secrets
No processing of confidential user data
The selection, filtering, encoding, and link creation are all done entirely in the browser. The generated handover link contains only publicly available technical information about the selected lighthouse.
Error handling and validation
The automated data process checks whether the downloaded Overpass file exists and is structurally valid.
Empty files or source data lacking the expected element structure will result in processing being aborted. This prevents a faulty or incomplete file from being published as a new dataset.
In the frontend, errors during loading or processing of the dataset are logged and displayed within the application.
During the creation and filtering of the markers, a status indicator provides information about the current processing status.
Data quality and security notice
The information presented is based on collaboratively maintained OpenStreetMap data. Despite automated processing, datasets may be incomplete, outdated, or incorrect.
The application and the provided files must therefore not be used for navigation or safety-critical maritime decisions.
Scalability and expandability
The static architecture does not require a scalable server application. GitHub Pages only delivers the prepared files, while the presentation and interaction take place in the browser.
For the current size of approximately 18,600 data records, this approach is practical due to the stepwise marker processing.
Possible future expansions include:
Marker clustering
geographical distribution of the data sets
Loading individual regions
additional filters for signal characteristics and periods
Search by name or OpenStreetMap ID
other export formats
automated browser and integration tests
additional validation of external handover targets
more detailed schemas for the public datasets
further direct integration options for external applications
Technologies and methods used: HTML · CSS · JavaScript · Leaflet · OpenStreetMap · Overpass API · Python · pandas · pyarrow · JSON · Gzip · Parquet · Base64URL · GitHub Actions · GitHub Pages · Cloudflare
