// stack · schnittstelle
Mapbox ist eine Kartenplattform, deren Kern nicht die Karte ist, sondern ihre Gestaltung. Farben, Beschriftungen, sichtbare Ebenen, Zoomstufen — das Kartenbild wird vorab gebaut und von der Website geladen. siteway setzt Mapbox dort ein, wo die Karte selbst zum Gestaltungselement wird. Diese Seite beschreibt die Technik dahinter: Style, Standortdaten, Token und den Weg ins CMS.
// definition
Mapbox ist eine Kartenplattform für Websites und Apps. Sie liefert Kartendaten, eine Bibliothek, die daraus im Browser eine Karte rendert, und einige Dienste drumherum — Adresssuche, statische Kartenbilder, eigene Datenebenen. Die Kartendaten stammen aus mehreren Quellen; die vorgeschriebene Quellenangabe nennt neben Mapbox ausdrücklich OpenStreetMap, bei Satellitenansichten zusätzlich den Bildlieferanten.
Der eigentliche Grund, Mapbox zu wählen, ist aber ein anderer: der Style. In der Dokumentation ist das ein Konfigurationsdokument, das das visuelle Erscheinungsbild einer Karte festlegt — Farben, Schriften, Linienbreiten, die Reihenfolge der Ebenen und mehr. Gebaut wird er im visuellen Editor Mapbox Studio, veröffentlicht unter einer eigenen Style-URL, die die Website beim Laden der Karte angibt. Das Kartenbild ist damit nicht Beiwerk, sondern Entwurf.
Technisch trägt das ein Prinzip: Vektor-Tiles enthalten Geometrien und Metadaten, aber laut Dokumentation keine eigenen Stileigenschaften. Gerendert wird erst im Browser, aus Daten plus Stilregeln. Genau deshalb lässt sich dieselbe Karte in völlig unterschiedlichen Farbwelten ausspielen — hell, dunkel, reduziert, plakativ. Wie wir eine Karte als buchbaren Baustein in eine Website einbauen, steht unter Karten & Standorte; hier geht es um die Schnittstelle darunter.
// praxis
erst der style, dann die karte
Die Arbeit beginnt nicht im Code, sondern im Kartenbild. Wir bauen den Style vorab: Farbwerte für Wasser, Grün, Bebauung und Straßen, Linienstärken je Straßenklasse, Schrift und Größe der Beschriftungen, die Reihenfolge der Ebenen — und die Entscheidung, welche Ebene ab welcher Zoomstufe überhaupt erscheint. Eine Karte, die nur Standorte zeigen soll, braucht keine Hausnummern; eine Karte, die eine Reise erzählt, braucht sie ab einem bestimmten Punkt sehr wohl. Der fertige Style wird veröffentlicht, die Website lädt ihn über seine Style-URL. Zwei Varianten für hell und dunkel gehören dazu, weil die Seite beide Modi kennt.
Die Standortdaten liegen im CMS, nicht im JavaScript. Ein Standort ist eine eigene Inhaltsart mit Name, Adresse, Öffnungszeiten, Bild und Beschreibung, dazu zwei Feldern für Breiten- und Längengrad. Gefüllt werden die Koordinaten per Geocoding — serverseitig, beim Speichern oder in einem geplanten Lauf, nicht bei jedem Seitenaufruf. Die Redaktion pflegt eine Adresse und muss nie eine Koordinate abtippen.
Im Frontend lädt die Karte erst nach Einwilligung. Davor steht ein Platzhalter, der schon etwas taugt: ein statisches Kartenbild aus dem eigenen Bestand oder die Standortliste mit Adresse, Öffnungszeiten und Anfahrtslink. Erst mit der Zustimmung werden Bibliothek, Style und Kacheln nachgeladen. Das ist zugleich der Performance-Gewinn: Eine Kartenbibliothek ist schwer, und was nicht beim ersten Aufruf lädt, belastet die Core Web Vitals nicht.
Neben der Karte steht immer eine bedienbare Liste derselben Standorte — echte Überschriften, echte Links, in der Tastaturreihenfolge erreichbar. Ziehen und Zoomen sind mit Tastatur und Screenreader schwer zu bedienen; die Liste ist der gleichwertige Zugang zum selben Inhalt, nicht die Notlösung. Mehr dazu unter Barrierefreiheit.
Und der Zugriffstoken: Im Browser läuft ausschließlich ein öffentlicher Token, beschränkt auf die eigenen Domains. Alles, was mehr Rechte braucht — Geocoding im Hintergrund, Style-Verwaltung, das Erzeugen eigener Datenebenen — bleibt auf dem Server. Die Quellenangabe der Karte bleibt sichtbar; ihre Schriftfarbe und Größe passen wir dem Design an, das Logo nicht. Wie wir Schnittstellen insgesamt planen und betreiben, steht in der Leistung Schnittstellenentwicklung.
// technik · 6 details
belegt aus der doku
Was hier steht, stammt aus der öffentlichen Dokumentation von Mapbox — Begriffe, Endpunkte und Grenzwerte im Original. Was sie nicht hergibt, steht hier auch nicht: Tarife, Kontingente und Preismodelle ändern sich, deshalb prüfen wir sie im Projekt statt sie hier zu behaupten.
// d-01gestaltung
Ein Style ist ein Konfigurationsdokument für das Erscheinungsbild der Karte: Farben, Schriften, Linienbreiten, Ebenenreihenfolge. Gebaut wird er im visuellen Editor Mapbox Studio, benutzt über seine Style-URL nach dem Muster mapbox://styles/{owner}/{style_id}.
zweck: kartenbild
// d-02ebenen
Der Style verweist auf Datenquellen und beschreibt je Ebene, wie sie dargestellt wird. Damit lässt sich steuern, was sichtbar ist und ab welcher Zoomstufe: Beschriftungen reduzieren, Straßenklassen staffeln, ganze Ebenen ausblenden — ohne die Daten anzufassen.
zweck: lesbarkeit
// d-03frontend
Die Kartenbibliothek von Mapbox rendert die Karte per WebGL im Browser — Vektor-Tiles plus Stilregeln, nicht fertige Bildkacheln vom Server. Für die Initialisierung braucht sie drei Angaben: Zugriffstoken, Ziel-Element im Markup und Style-URL.
zweck: interaktive karte
// d-04adressen
Adresse zu Koordinaten und zurück, über getrennte Endpunkte für forward, reverse und batch. Wichtig für eine Website: Die Doku unterscheidet temporäre und dauerhafte Ergebnisse — nur die dauerhafte Variante darf gespeichert werden, und genau das braucht ein CMS.
zweck: koordinaten
// d-05platzhalter
Die Static Images API liefert eigenständige Kartenbilder aus einem Studio-Style, die sich laut Doku ohne Kartenbibliothek anzeigen lassen — als PNG, JPEG oder WebP, mit Breite und Höhe zwischen 1 und 1280 Pixeln und optional in doppelter Auflösung.
zweck: bild statt bibliothek
// d-06eigene daten
Tilesets halten Kartendaten in einem festen Format; Vektor-Tilesets speichern Geometrien wie Punkte, Linien und Flächen samt Metadaten. Eigene Daten lassen sich als eigenes Tileset erzeugen — der Weg für Netze aus sehr vielen Punkten oder eigene Gebietsgrenzen.
zweck: viele marker
Jede Kartenanfrage trägt einen Zugriffstoken, und der steht im Browser für jeden lesbar da. Deshalb gilt die Regel, die die Dokumentation selbst formuliert: erlaubte URLs hinterlegen. Ist eine solche Liste gesetzt, funktioniert der Token nur noch für Anfragen, die von diesen Adressen kommen — abgeschrieben und auf einer fremden Seite eingesetzt, ist er wertlos.
Dazu kommt die Trennung nach Zweck. Im Browser läuft ausschließlich ein Token mit öffentlichen Rechten; alles, was geheime Rechte braucht, läuft serverseitig — so steht es in der Doku, und so bauen wir es. Je Anwendung ein eigener Token, damit sich die Nutzung zuordnen lässt. Token lassen sich jederzeit austauschen, wenn ein Verdacht besteht.
Bleibt der Blick auf die Nutzung. Kartenaufrufe werden gezählt, und eine Karte auf einer stark besuchten Seite zählt schnell. Wir klären die Kontingente des gewählten Tarifs vor dem Go-live, beobachten die Nutzung je Token und bauen so, dass sie niedrig bleibt: die Karte erst nach Einwilligung, ein statisches Kartenbild als Platzhalter, keine Karte auf Seiten, die keine braucht.
// integration
drei systeme · ein muster
Der Weg ist in jedem System derselbe, und er beginnt beim Ausliefern: Die Karte lädt erst nach Einwilligung. Bis dahin steht an ihrer Stelle ein Platzhalter, der bereits Auskunft gibt — ein statisches Kartenbild aus dem eigenen Bestand oder die Standortliste mit Adresse, Öffnungszeiten und Anfahrtslink. Erst der Klick auf die Zustimmung lädt Bibliothek, Style und Kacheln nach. Das ist keine Zusatzarbeit, sondern die Bauweise: Die Seite muss auch ohne geladene Karte vollständig funktionieren, sonst ist die Einwilligung keine echte Wahl.
Darunter liegt eine klare Aufteilung. Kartendaten und Marker liegen im CMS — Standorte als eigene Inhaltsart mit Koordinatenfeldern, gepflegt von der Redaktion, ausgeliefert aus dem eigenen Bestand. Das Kartenbild kommt aus dem selbst gestalteten Style, den die Website über seine Style-URL lädt. Der Zugriffstoken steht in der Konfiguration des Systems, nicht im Template, und ist auf die eigenen Domains beschränkt. Und das Geocoding läuft serverseitig, beim Speichern oder in einem geplanten Lauf, damit weder ein Schlüssel noch eine Besucheranfrage im Browser landet. Was sich zwischen den Systemen unterscheidet, sind die Werkzeuge — nicht die Kette.
// cms-01typo3
In TYPO3 bauen wir die Anbindung als eigene Extension. Standorte sind Records in einem Systemordner, ihr Datenmodell beschreibt das TCA — mit den Feldern für Adresse und Kontakt und zwei Feldern für Breiten- und Längengrad. Das Geocoding läuft als Scheduler-Task und trägt die Koordinaten nach, sobald eine Adresse neu ist oder sich geändert hat. Der Zugriffstoken liegt in der Extension-Konfiguration, nicht im Template. Im Frontend rendert Fluid zuerst den Consent-Platzhalter samt Standortliste und tauscht ihn nach der Zustimmung gegen die Karte; die Standortdaten kommen dabei als Datenattribute aus denselben Records. Die Redaktion pflegt Standorte im Backend wie jeden anderen Inhalt.
// cms-02wordpress
In WordPress entsteht die Anbindung als eigenes Plugin und nicht als Theme-Code — so überlebt sie den nächsten Theme-Wechsel. Die Standorte werden ein Custom Post Type mit Meta-Feldern für Adresse, Kontakt und Koordinaten, dazu Taxonomien für Filter wie Region oder Standorttyp. Das Geocoding läuft beim Speichern serverseitig und schreibt die Koordinaten direkt in die Meta-Felder. Der Zugriffstoken steht in der wp-config.php oder in einer Umgebungsvariable. Fürs Frontend kommen ein Block für den Editor und Template-Dateien dazu, die den Consent-Platzhalter, die Standortliste und die Karte ausgeben.
// cms-03statamic
Statamic läuft auf Laravel, und das macht den Weg kurz. Ein Blueprint beschreibt den Standort als Entry in einer eigenen Collection, mit Feldern für Adresse, Kontakt und den beiden Koordinatenfeldern. Das Geocoding übernimmt ein Artisan-Command, den der Laravel-Scheduler regelmäßig aufruft oder der nach dem Speichern läuft. Der Zugriffstoken liegt in der .env-Datei und wird über die Konfiguration gelesen. Antlers oder Blade rendern Platzhalter, Standortliste und Karte aus denselben Entries; Static Caching liefert die Seite aus, ohne dass die Karte darin steckt — sie kommt erst nach der Zustimmung dazu.
// datenschutz
sachlich, kein rechtsrat
Eine interaktive Karte lädt Kartenkacheln, Schriften und Symbole von einem externen Dienst nach. Dabei geht die IP-Adresse der Besucherin an diesen Dienst — das ist keine Einstellungssache, sondern liegt in der Natur der Sache: Ohne Anfrage kein Kartenbild.
Auf einer Website, die sonst ohne Tracking und ohne Fremdcode auskommt, ist die Karte damit der eine Punkt, an dem etwas nach außen geht. Deshalb behandeln wir sie auch so: Consent-Platzhalter statt Karte beim ersten Aufruf, Laden erst nach Zustimmung, und ein Platzhalter, der die Auskunft schon selbst gibt — statisches Kartenbild aus dem eigenen Bestand oder Standortliste mit Adresse und Anfahrtslink. Wer nicht zustimmt, sieht trotzdem, wo der Standort liegt.
Zwei Dinge kommen technisch dazu. Das Geocoding läuft serverseitig: Gibt jemand eine Postleitzahl in eine Umkreissuche ein, spricht unser Server mit dem Dienst, nicht der Browser der Besucherin — ihre IP-Adresse bleibt außen vor. Und der Zugriffstoken liegt in der Konfiguration, domainbeschränkt, mit öffentlichen Rechten im Browser und geheimen Rechten ausschließlich auf dem Server.
Was daraus rechtlich folgt, entscheidet ihr mit eurer Rechtsberatung — wir liefern die Technik und die Dokumentation dazu: welcher Dienst wann geladen wird, was dabei übertragen wird und wie die Einwilligung erfasst ist. Wie wir Seiten grundsätzlich trackingfrei und mit sauberen Security-Headern ausliefern, steht unter Sicherheit & Datenschutz. Wer den Bestand prüfen lassen will, findet das im Datenschutz-Audit.
// faq
Mapbox ist eine Kartenplattform für Websites und Apps. Ihr Kern ist der Karten-Style: ein Konfigurationsdokument, das laut Dokumentation das visuelle Erscheinungsbild einer Karte festlegt — Farben, Schriften, Linienbreiten, die Reihenfolge der Ebenen und mehr. Gebaut wird ein solcher Style im visuellen Editor Mapbox Studio, veröffentlicht wird er unter einer eigenen Style-URL, die die Website beim Laden der Karte angibt. Die Kartendaten stammen aus mehreren Quellen; die vorgeschriebene Attribution nennt neben Mapbox ausdrücklich OpenStreetMap, bei Satellitenansichten zusätzlich den Bildlieferanten. Rund um die Karte stehen weitere Bausteine bereit: eine Geocoding-API, statische Kartenbilder und eigene Datenebenen.
Das Kartenbild selbst. Der Style beschreibt, welche Datenebenen überhaupt sichtbar sind und wie sie aussehen: Farbwerte für Wasser, Grünflächen, Bebauung und Straßen, Linienstärken je Straßenklasse, Schriftart und Größe der Beschriftungen, Symbole, die Reihenfolge der Ebenen und ab welcher Zoomstufe eine Ebene erscheint. Vektor-Tiles bringen ausdrücklich keine eigenen Stileigenschaften mit — gerendert wird im Browser aus Daten plus Stilregeln, und deshalb ist das Aussehen frei bestimmbar. Praktisch heißt das: eine Karte in der Farbwelt der Marke, in hell und dunkel, mit reduzierter Beschriftung dort, wo sie stören würde. Nicht gestaltbar ist die Attribution — Logo und Quellenangabe bleiben sichtbar, ihre Schriftfarbe und Größe dürfen sich dem Design anpassen.
In der Regel arbeiten wir mit der Google-Maps-API, weil sie das dichteste Adress- und Routing-Material liefert — Filialfinder, Umkreissuche, Anfahrt. Mapbox kommt dort zum Zug, wo die Karte selbst zum Gestaltungselement wird: eigene Farbwelt, eigene Ebenen, ein Kartenbild, das zur Marke gehört statt zum Anbieter. Ein Zoomweg vom Kontinent bis zur Straße, der durchgehend im eigenen Look bleibt, eine Karte als Bühne für Inhalte, eine Datenebene, die neben den Basisdaten liegt: das ist Mapbox-Terrain. Die Frage wird im Konzept beantwortet, nicht im Angebot — und sie hängt am Zweck der Karte, nicht am Geschmack.
Aus dem CMS. Die Redaktion pflegt einen Standort wie jeden anderen Inhalt — Name, Adresse, Öffnungszeiten, Bild, Beschreibung — und das Datenmodell bekommt zwei zusätzliche Felder für Breiten- und Längengrad. Gefüllt werden sie über Geocoding: Die Adresse geht an den Geocoding-Dienst, zurück kommen Koordinaten, die im Datensatz gespeichert werden. Das läuft serverseitig und einmalig beim Speichern oder in einem geplanten Lauf, nicht bei jedem Seitenaufruf. Wichtig dabei: Die Dokumentation unterscheidet temporäres und dauerhaftes Geocoding, und nur die dauerhafte Variante erlaubt es, Ergebnisse zu speichern. Das gehört vor dem Bauen geklärt. Im Frontend liegen die Marker danach als eigene Datenebene über dem Kartenbild; bei sehr vielen Punkten wird daraus ein eigenes Tileset.
Über vier Regeln, die die Dokumentation selbst nennt. Erstens Domainbeschränkung: Wird für einen Token eine Liste erlaubter URLs hinterlegt, funktioniert er nur noch für Anfragen, die von diesen Adressen kommen — ein abgeschriebener Token nützt auf einer fremden Seite nichts mehr. Zweitens getrennte Token: je Anwendung ein eigener, damit sich die Nutzung zuordnen lässt. Drittens die Trennung der Rechte: Im Browser läuft ausschließlich ein Token mit öffentlichen Rechten, alles mit geheimen Rechten bleibt auf dem Server. Viertens Beobachtung: Token lassen sich jederzeit austauschen, und die Nutzung je Token zeigt, wenn etwas aus dem Rahmen fällt. Dazu kommt der Blick auf die Kontingente des gewählten Tarifs, bevor eine Karte auf eine stark besuchte Seite geht.
Eine interaktive Karte lädt ihre Kacheln, Schriften und Symbole von einem externen Dienst nach. Damit geht die IP-Adresse der Besucherin an diesen Dienst — technisch unvermeidbar, sobald die Karte läuft. Auf einer Website, die sonst ohne Tracking und ohne Fremdcode auskommt, ist die Karte damit der eine Punkt, an dem etwas nach außen geht. Deshalb bauen wir sie mit Consent-Platzhalter: Vor der Zustimmung steht ein statisches Kartenbild aus dem eigenen Bestand oder die Standortliste mit Adresse und Anfahrtslink, und erst mit der Einwilligung wird die Karte nachgeladen. Was wir sonst noch tun: Geocoding serverseitig statt aus dem Browser, keine Besucherdaten an den Kartendienst, den Dienst in der Datenschutzerklärung benannt. Die Bewertung im konkreten Fall trefft ihr mit eurer Rechtsberatung — wir liefern die Technik dazu.
Eine Karte allein ist es nicht. Ziehen, Zoomen und das Anklicken kleiner Marker sind mit Tastatur schwer und mit Screenreader kaum zu bewältigen — eine gerenderte Fläche gibt für sich genommen keine Struktur her. Deshalb gehört neben die Karte immer eine bedienbare Liste derselben Standorte: als echte Überschriften, Adressen und Links, in der Tastaturreihenfolge erreichbar, mit demselben Informationsstand wie die Marker. Wer die Karte nutzen kann, nutzt sie; wer nicht, kommt über die Liste genauso ans Ziel. Karte und Liste hängen an derselben Datenquelle, damit sie nicht auseinanderlaufen.
Ja, in allen dreien — und in allen dreien bauen wir die Anbindung selbst, mit den Bordmitteln des jeweiligen Systems. Die Kette ist überall dieselbe: Standorte als eigene Inhaltsart mit Koordinatenfeldern, Geocoding serverseitig, der Zugriffstoken in der Konfiguration statt im Template, die Karte im Frontend hinter einem Consent-Platzhalter. In TYPO3 entsteht dafür eine eigene Extension mit Standorten als Records, Geocoding als Scheduler-Task, dem Token in der Extension-Konfiguration und Fluid für die Ausgabe. In WordPress ein eigenes Plugin statt Theme-Code, mit Custom Post Type für die Standorte, Geocoding beim Speichern und dem Token in der wp-config.php oder einer Umgebungsvariable. In Statamic arbeitet Laravel darunter: Blueprint mit Koordinatenfeldern, ein Artisan-Command fürs Geocoding, der Token in der .env-Datei, Antlers oder Blade für Karte und Liste.
// womit das zusammenhängt
karten, grundlagen & leistung
// stack · schnittstelle
Der Regelfall bei uns: dichtes Adress- und Routing-Material für Filialfinder, Umkreissuche und Anfahrt.
zur technik →
// leistung · buchen
Die Karte als buchbarer Baustein: Marker, Cluster, Umkreissuche, Route — einzeln buchbar nach Briefing.
zur leistung →
// stack · grundlage
Warum neben jede Karte eine bedienbare Liste gehört — und was Tastaturbedienung sonst noch verlangt.
zur technik →
// stack · grundlage
Kartenbibliotheken sind schwer. Was verzögertes Laden für die Core Web Vitals bedeutet und wie wir messen.
zur technik →
// stack · grundlage
Trackingfrei ausliefern, Schlüssel serverseitig halten, Security-Header setzen — die Grundlage unter der Karte.
zur technik →
// leistung · buchen
Die Technik hier, das Angebot dort: Analyse, Konzept, Umsetzung, Monitoring und Betrieb der Anbindung.
zur leistung →
// Eine Karte, die zu deiner Marke passt?
Projekt anfragen