Lighthouses Worldwide - Webapp Map Leuchtturmsignale weltweit

Lighthouses Worldwide ist eine interaktive Webanwendung zur weltweiten Darstellung realer Leuchttürme und ihrer Lichtsignale. Grundlage sind maritime OpenStreetMap-Seamark-Daten, die automatisiert über die Overpass API abgerufen, mit Python aufbereitet und als browseroptimierte Datensätze veröffentlicht werden.

Die Anwendung ermöglicht es, Leuchttürme geografisch zu suchen, nach Lichtfarben und mehrfarbigen Sektoren zu filtern und detaillierte Informationen zu ihren Signalcharakteristiken anzuzeigen. Dazu gehören unter anderem Farbe, Signalfolge, Wiederholungsperiode und die geografische Ausrichtung einzelner Lichtsektoren.

Neben der interaktiven Karte stellt das Projekt die aufbereiteten Daten über stabile öffentliche Download-Links bereit. Für regelmäßige oder automatisierte Downloads stehen zusätzlich komprimierte Gzip-Dateien zur Verfügung.

Über ein URL-basiertes Handover kann die Karte außerdem mit einer externen Detail- oder Empfängeranwendung verbunden werden. Ein ausgewählter Leuchtturm wird dabei als Base64URL-codiertes JSON-Paket an die konfigurierte Anwendung übergeben. Dafür sind keine Anmeldung, keine Datenbank und keine serverseitige Sitzung erforderlich.

Das zum Zeitpunkt der Dokumentation erzeugte Rich Dataset enthält 18.619 Leuchtturm- und Lichtsignal-Datensätze. Die Anwendung, der tägliche Datenabruf, die Datenaufbereitung und das Deployment werden vollständig über GitHub betrieben. Die GitHub-Pages-Anwendung ist über Cloudflare mit der eigenen Domain verbunden. Cloudflare übernimmt die DNS-Verwaltung, die verschlüsselte Bereitstellung über HTTPS und die vorgeschaltete Verarbeitung des öffentlichen Webverkehrs. Eine eigene Serverinfrastruktur ist nicht erforderlich.

Projektlink: https://lighthouse.heiselanalytics.cloud/

Screenshot

Ausgangslage

Informationen zu Leuchttürmen und ihren Lichtsignalen sind in OpenStreetMap über das Seamark-Datenmodell verfügbar. Die Rohdaten eignen sich jedoch nicht unmittelbar für eine benutzerfreundliche Kartenanwendung oder eine standardisierte Weiterverarbeitung.

Die Ergebnisse der Overpass API enthalten unterschiedliche OpenStreetMap-Elementtypen, verschachtelte Tag-Strukturen und nummerierte Felder für einzelne Lichtsektoren. Auch die geografische Position wird je nach Elementtyp unterschiedlich gespeichert. Während Nodes bereits über direkte Koordinaten verfügen, bestehen Ways aus mehreren geografischen Punkten.

Für Nutzerinnen und Nutzer wäre die direkte Arbeit mit diesen Daten aufwendig. Sie müssten das OpenStreetMap-Schema verstehen, passende Einträge manuell identifizieren und die relevanten Seamark-Felder selbst interpretieren.

Auch für andere Anwendungen waren die Rohdaten nur eingeschränkt nutzbar. Eine empfangende Anwendung müsste die vollständigen Overpass-Daten laden, den gewünschten Leuchtturm suchen und die komplexen Tag-Strukturen selbst in ein verwendbares Format übersetzen.

Zusätzlich bestand der Anspruch, die aufbereiteten Datensätze nicht nur innerhalb der Karte zu verwenden, sondern sie auch für eigene Analysen, Anwendungen und wiederkehrende Datenprozesse bereitzustellen.

Daraus ergaben sich folgende Anforderungen:

• interaktive Weltkarte zur geografischen Auswahl

• automatische Aufbereitung der OpenStreetMap-Seamark-Daten

• Filterung nach Lichtfarben und mehrfarbigen Sektoren

• verständliche Darstellung der Signalcharakteristiken

• geografische Visualisierung der Lichtsektoren

• direkte Links zu einzelnen Leuchttürmen

• URL-basierte Übergabe an externe Anwendungen

• öffentliche Downloads in unterschiedlichen Datenformaten

• geeignete Dateien für regelmäßige automatisierte Downloads

• tägliche Aktualisierung der Quelldaten

• Betrieb ohne eigenen Server oder Datenbank

Definierte Lösung

Entwickelt wurde eine statische Webanwendung, die auf täglich vorbereiteten JSON-Datensätzen basiert. Die OpenStreetMap-Rohdaten werden nicht erst bei einer Nutzeranfrage verarbeitet. Stattdessen werden sie automatisiert abgerufen, normalisiert und als optimierte Dateien für die Karte und externe Anwendungen bereitgestellt.

Interaktive Weltkarte

Beim Öffnen der Anwendung wird direkt eine interaktive Weltkarte angezeigt. Nutzerinnen und Nutzer können die Karte frei verschieben und zoomen sowie die sichtbaren Leuchttürme nach verschiedenen Signalmerkmalen filtern.

Zur Verfügung stehen unter anderem:

• Filterung nach einer oder mehreren Lichtfarben

• gezielte Anzeige mehrfarbiger Leuchttürme

• geografische Auswahl über die Weltkarte

• Anzeige von Signalfolge und Wiederholungsperiode

• Darstellung vorhandener Lichtsektoren

• direkte Verlinkung einzelner Leuchttürme

• Übergabe einer Auswahl an eine externe Anwendung

In niedrigen Zoomstufen werden die Leuchttürme als kompakte farbige Marker dargestellt. Bei stärkerem Hineinzoomen wechselt die Darstellung für geeignete Datensätze zu grafischen Sektorsymbolen. Dadurch wird neben der Lichtfarbe auch die räumliche Ausrichtung der jeweiligen Lichtsektoren sichtbar.

Beim Anklicken eines Markers öffnet sich ein Informationsfenster mit dem Namen, der Signalcharakteristik, der Hauptfarbe und den verfügbaren Sektordaten.

Downloads and handoff links

Eine zusätzliche Seite stellt die aktuellen Datensätze zum direkten Download bereit und dokumentiert, wie die Karte mit einer eigenen Anwendung verbunden werden kann. Die Dateien besitzen stabile öffentliche URLs. Dadurch können sie sowohl manuell heruntergeladen als auch in eigene Skripte, Datenpipelines oder geplante Aktualisierungsprozesse eingebunden werden.

Für jeden Datensatz stehen eine unkomprimierte JSON-Datei und eine komprimierte Gzip-Version bereit. Für häufige oder zeitgesteuerte Downloads wird die komprimierte Variante empfohlen, da sie deutlich weniger Datenvolumen benötigt.

URL-Handover

Eine externe Anwendung kann beim Öffnen der Karte ihre eigene Zieladresse über den Parameter url mitgeben. Diese Adresse wird anschließend als Basis-URL für alle Handover-Links innerhalb der Leuchtturm-Popups verwendet.

Beispiel:

https://lighthouse.heiselanalytics.cloud/?url=https%3A%2F%2Fexample.com%2Flighthouse

Der Ablauf ist wie folgt:

1. Die externe Anwendung öffnet die Karte mit ihrer URL als codiertem url-Parameter.

2. Die Karte übernimmt diese Adresse als Ziel für die Detail-Links.

3. Eine Nutzerin oder ein Nutzer wählt einen Leuchtturm auf der Karte aus.

4. Das Popup erzeugt einen Link zur angegebenen Basis-URL.

5. Die Informationen des ausgewählten Leuchtturms werden im Parameter cmd angehängt.

6. Die empfangende Anwendung decodiert den Parameter und verarbeitet das enthaltene JSON.

Der Linktext kann über den Parameter linkText angepasst werden:

https://lighthouse.heiselanalytics.cloud/?url=https%3A%2F%2Fexample.com%2Flighthouse&linkText=Open%20in%20Lighthouse%20App

Zusätzlich werden die folgenden Parameterbezeichnungen unterstützt:

• link_text

• linkLabel

• link_label

Wird kein eigener Linktext angegeben, verwendet die Karte standardmäßig: "Link to your lighthouse"

Direkter Aufruf eines Leuchtturms

Ein Leuchtturm kann auch direkt über seinen eindeutigen Kartenschlüssel geöffnet werden:

https://lighthouse.heiselanalytics.cloud/?id=n9544344520

Nach dem Laden des Datasets sucht die Anwendung nach dem passenden Eintrag, zoomt automatisch auf dessen Position und öffnet das zugehörige Informationsfenster.

Neben id werden auch folgende Parameter unterstützt:

• lighthouseId

• lighthouse_id

Dadurch lassen sich einzelne Leuchttürme direkt verlinken, beispielsweise aus Dokumentationen, Datenanalysen oder externen Anwendungen.

Ergebnisse & Mehrwert

Mit Lighthouses Worldwide wurde aus einem umfangreichen und technisch komplexen OpenStreetMap-Datensatz eine direkt nutzbare geografische Anwendung und öffentliche Datenquelle entwickelt.

Das zum Zeitpunkt der Dokumentation erzeugte Dataset enthält:

• 18.619 Datensätze

• 18.017 Nodes

• 602 Ways

• 6.666 Datensätze mit Sektorinformationen

• 15.637 Datensätze mit erkannter Hauptperiode

Nutzerinnen und Nutzer müssen keine OpenStreetMap-Rohdaten oder Seamark-Tags mehr analysieren. Stattdessen können sie reale Leuchttürme direkt auf einer Weltkarte finden, nach Signalmerkmalen filtern und die relevanten Eigenschaften visuell überprüfen.

Die Darstellung der Lichtfarben und Sektoren erleichtert insbesondere die Identifikation komplexer oder mehrfarbiger Signale. Leuchttürme können dadurch nicht nur anhand ihres Namens, sondern auch anhand ihrer Position und Signalcharakteristik ausgewählt werden.

Die Download-Seite erweitert das Projekt von einer reinen Kartenanwendung zu einer öffentlich nutzbaren Datenquelle. Entwicklerinnen und Entwickler können zwischen einem kompakten und einem erweiterten Dataset wählen und die Dateien über stabile Links in eigene Prozesse integrieren.

Die Gzip-Versionen reduzieren das übertragene Datenvolumen deutlich und eignen sich insbesondere für regelmäßig ausgeführte Downloads. Eine eigene API-Abfrage oder Authentifizierung ist dafür nicht erforderlich.

Das URL-Handover ermöglicht die einfache Anbindung externer Anwendungen. Alle für die Übergabe erforderlichen Informationen befinden sich im erzeugten Link. Dadurch werden keine Benutzerkonten, serverseitigen Sessions oder Datenbankeinträge benötigt.

Ein besonderer Mehrwert liegt in der vollständig automatisierten und wartungsarmen Bereitstellung. Sowohl die Website als auch der tägliche Datenabruf, die Datenverarbeitung und das Deployment laufen über GitHub.

Es ist keine eigene Serverinstanz erforderlich. Aufgaben wie Betriebssystem-Updates, Serverabsicherung, Containerverwaltung, Datenbankbetrieb oder die Wartung einer öffentlichen API entfallen vollständig.

Trotz dieser statischen Architektur werden die Daten täglich neu aus OpenStreetMap abgerufen und verarbeitet. Änderungen an Leuchttürmen oder ihren Signalmerkmalen können dadurch automatisiert in die veröffentlichten Datensätze und die Kartenanwendung übernommen werden. Das Projekt verbindet damit tagesaktuelle Informationen mit einer sehr geringen betrieblichen Komplexität.

Technische Ausgestaltung

Das Frontend wurde mit HTML, CSS und JavaScript entwickelt. Für die Kartendarstellung wird Leaflet 1.9.4 verwendet. Als geografische Grundlage dient eine dunkle CARTO-Basemap.

Die Anwendung verwendet kein zusätzliches Frontend-Framework, keinen Paketmanager und keinen Bundler. Der technische Aufbau bleibt dadurch kompakt und kann vollständig als statische Website über GitHub Pages bereitgestellt werden.

Alle Interaktionen erfolgen direkt im Browser. Dazu gehören:

• Laden und Verarbeiten des Datasets

• Erstellen der Kartenmarker

• Filterung der sichtbaren Leuchttürme

• Erzeugung der grafischen Lichtsektoren

• Anzeige der Detailinformationen

• Verarbeitung der URL-Parameter

• Generierung der Handover-Links

• Base64URL-Codierung der ausgewählten Daten

Eine serverseitige Anwendungslogik ist nicht erforderlich.

Datenquelle und automatisierte Aufbereitung

Die primäre Datenquelle ist die Overpass API von OpenStreetMap. Abgerufen werden weltweit Nodes und Ways, die relevante Seamark-Felder für Lichtsignale enthalten.

Die Rohdaten werden durch ein Python-Skript verarbeitet. Dabei werden unterschiedliche OpenStreetMap-Strukturen vereinheitlicht und in kompakte Datensätze für die Webanwendung und externe Downloads überführt.

Bei Nodes können die geografischen Koordinaten direkt übernommen werden. Bei Ways wird aus den zugehörigen Geometriepunkten eine zentrale Position für die Kartendarstellung ermittelt.

Die Aufbereitung umfasst unter anderem:

• Erkennung relevanter Leuchtturm- und Lichtobjekte

• Vereinheitlichung der OpenStreetMap-IDs

• Extraktion der Namen

• Verarbeitung der Signalfolgen

• Normalisierung der Lichtfarben

• Erkennung von Hauptperiode und Signalcharakter

• Verarbeitung nummerierter Seamark-Sektoren

• Normalisierung geografischer Winkel

• Begrenzung auf maximal fünf exportierte Sektoren pro Datensatz

Öffentliche Datensätze

Die Anwendung stellt zwei unterschiedliche JSON-Datasets bereit.

Rich Dataset - Das Rich Dataset enthält die vollständigen Informationen, die auch für die erweiterte Browserdarstellung und das URL-Handover benötigt werden.

Dazu gehören unter anderem:

• eindeutiger Kartenschlüssel

• OpenStreetMap-Typ und ID

• geografische Position

• Name

• Lichtfarbe

• Signalfolge

• Hauptfarbe

• Hauptperiode

• Signalcharakter

• Sektorinformationen

Compact Dataset - Das Compact Dataset ist für Anwendungen vorgesehen, die hauptsächlich Kartengrunddaten und die wichtigsten Signalmerkmale benötigen.

Es enthält unter anderem:

• eindeutigen Kartenschlüssel

• OpenStreetMap-Typ und ID

• geografische Position

• Name

• Farbe

• Signalfolge

Browserseitige Verarbeitung

Nach dem Öffnen der Anwendung wird das Rich Dataset in den Browser geladen.

Aufgrund der hohen Anzahl an Datensätzen werden die Kartenmarker nicht gleichzeitig erzeugt, sondern in mehreren Verarbeitungsschritten aufgebaut. Die Anwendung nutzt browserseitige Batches, damit die Benutzeroberfläche auch während der Verarbeitung mehrerer Tausend Einträge bedienbar bleibt.

Auch Filteränderungen werden schrittweise verarbeitet. Dadurch muss die Anwendung nicht bei jeder Auswahl alle Marker gleichzeitig neu berechnen.

Ab Zoomstufe 9 wechselt die Darstellung von einfachen Farbmarkern zu grafischen Sektorsymbolen, sofern für den jeweiligen Leuchtturm verwertbare Winkeldaten vorhanden sind.

Die Lichtsektoren werden dynamisch als SVG-Grafiken erzeugt. Richtung, Winkelbereich und Farbe basieren auf den zuvor aufbereiteten Seamark-Daten.

Struktur des Handover-Payloads

Beim Anklicken des konfigurierten Popup-Links erstellt die Anwendung ein kompaktes JSON-Objekt mit den wichtigsten Eigenschaften des ausgewählten Leuchtturms.

Beispiel:

{
  "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"
    }
  ]
}

Das Objekt wird direkt im Browser als Base64URL-codierter Wert in den Parameter cmd geschrieben:

https://example.com/lighthouse?cmd=<base64url-json-payload>

Die empfangende Anwendung muss lediglich den Wert des cmd-Parameters lesen, Base64URL-decodieren und das enthaltene JSON verarbeiten.

Die Anwendung implementiert bewusst nur die Auswahl und Übergabe. Wie das empfangende System die Informationen verwendet, bleibt der jeweiligen Integration überlassen.

Hosting, Cloudflare und automatische Aktualisierung

Die gesamte Lösung wird über GitHub betrieben. Das statische Frontend und die öffentlichen Download-Dateien werden über GitHub Pages bereitgestellt. Eine eigene virtuelle Maschine, ein Webserver, eine Datenbank oder eine Container-Infrastruktur sind für den Betrieb nicht erforderlich.

Die GitHub-Pages-Website ist über Cloudflare mit der eigenen Domain lighthouse.heiselanalytics.cloud verbunden. Cloudflare übernimmt die DNS-Verwaltung und stellt die Anwendung verschlüsselt über HTTPS bereit. Der öffentliche Webverkehr wird über die Cloudflare-Infrastruktur geleitet, bevor die statischen Inhalte von GitHub Pages ausgeliefert werden.

Dadurch profitiert die Anwendung von zusätzlichen Schutzmechanismen auf Netzwerk- und Webebene. Dazu gehören insbesondere die Absicherung der Verbindung über TLS, die Filterung auffälliger Anfragen sowie der grundlegende Schutz vor missbräuchlichem oder ungewöhnlich hohem Datenverkehr. Gleichzeitig bleibt die eigentliche Anwendung vollständig statisch und benötigt keinen eigenen öffentlich erreichbaren Server.

Auch der Abruf und die Verarbeitung der Daten erfolgen innerhalb von GitHub. Ein zeitgesteuerter GitHub-Actions-Workflow wird täglich um 00:15 Uhr UTC ausgeführt.

Der Workflow:

1. richtet eine Python-Umgebung ein

2. lädt die aktuellen Daten über die Overpass API

3. prüft die heruntergeladene Datei auf grundlegende Gültigkeit

4. führt das Python-Skript zur Datenaufbereitung aus

5. erzeugt die JSON-, Gzip- und Parquet-Dateien neu

6. prüft, ob sich die Daten verändert haben

7. übernimmt vorhandene Änderungen in das Repository

8. veröffentlicht bei Änderungen automatisch die aktualisierte Website

Dadurch bleiben sowohl die Kartenansicht als auch die öffentlichen Download-Dateien täglich aktualisiert, ohne dass ein dauerhaft laufender eigener Server erforderlich ist.

Versionsverwaltung und Deployment

Der vollständige Quellcode, die Datenverarbeitung und die Deployment-Konfiguration werden in einem GitHub-Repository versioniert.

Sobald relevante Änderungen in den Main-Branch übernommen werden, erstellt ein GitHub-Actions-Workflow automatisch ein neues GitHub-Pages-Artefakt und veröffentlicht die aktualisierte Website.

Damit entspricht die öffentlich erreichbare Anwendung dem aktuellen Stand des Repositories. Ein manueller Deployment-Schritt ist nicht erforderlich.

Speicherung und Datenschutz

Die Anwendung besitzt:

• keine Benutzerkonten

• keine eigene Datenbank

• keine serverseitigen Sitzungen

• keine Speicherung ausgewählter Leuchttürme

• keine Backend-Secrets

• keine Verarbeitung vertraulicher Nutzerdaten

Die Auswahl, Filterung, Codierung und Link-Erstellung erfolgen vollständig im Browser. Der erzeugte Handover-Link enthält ausschließlich öffentlich verfügbare technische Informationen des ausgewählten Leuchtturms.

Fehlerbehandlung und Validierung

Der automatisierte Datenprozess prüft, ob die heruntergeladene Overpass-Datei vorhanden und strukturell gültig ist.

Leere Dateien oder Quelldaten ohne die erwartete Elementstruktur führen zu einem Abbruch der Verarbeitung. Dadurch wird verhindert, dass eine fehlerhafte oder unvollständige Datei als neuer Datenbestand veröffentlicht wird.

Im Frontend werden Fehler beim Laden oder Verarbeiten des Datasets protokolliert und innerhalb der Anwendung angezeigt.

Während des Aufbaus und der Filterung der Marker informiert eine Statusanzeige über den aktuellen Verarbeitungsstand.

Datenqualität und Sicherheitshinweis

Die dargestellten Informationen basieren auf gemeinschaftlich gepflegten OpenStreetMap-Daten. Trotz automatisierter Aufbereitung können Datensätze unvollständig, veraltet oder fehlerhaft sein.

Die Anwendung und die bereitgestellten Dateien dürfen daher nicht für Navigation oder sicherheitskritische maritime Entscheidungen verwendet werden.

Skalierbarkeit und Erweiterbarkeit

Die statische Architektur benötigt keine skalierbare Serveranwendung. GitHub Pages liefert ausschließlich die vorbereiteten Dateien aus, während die Darstellung und Interaktion im Browser erfolgen.

Für die aktuelle Größe von rund 18.600 Datensätzen ist dieser Ansatz durch die schrittweise Markerverarbeitung praktikabel.

Mögliche zukünftige Erweiterungen sind:

• Marker-Clustering

• geografische Aufteilung der Datensätze

• Laden einzelner Regionen

• zusätzliche Filter für Signalcharakter und Perioden

• Suche nach Namen oder OpenStreetMap-ID

• weitere Exportformate

• automatisierte Browser- und Integrationstests

• zusätzliche Validierung externer Handover-Ziele

• ausführlichere Schemas für die öffentlichen Datensätze

• weitere direkte Integrationsmöglichkeiten für externe Anwendungen

Eingesetzte Technologien und Methoden: HTML · CSS · JavaScript · Leaflet · OpenStreetMap · Overpass API · Python · pandas · pyarrow · JSON · Gzip · Parquet · Base64URL · GitHub Actions · GitHub Pages · Cloudflare