Interaktive Karten zu Ihrer Website hinzufügen | JavaScript Tutorial

Jedes Logistik-Dashboard, jedes Immobilieninserat und jede Lieferdienst-App hat eines gemeinsam: eine Karte. Fehlt Ihrer Website noch eine, verschenken Sie Kontext. Gemeint ist der Kontext, mit dem Nutzer Lage, Entfernungen und räumliche Zusammenhänge auf einen Blick erfassen.

Dieses Tutorial zeigt Schritt für Schritt, wie Sie eine voll interaktive Karte in ein beliebiges JavaScript-Projekt einbauen. Sie beginnen mit einer gerenderten Karte, ergänzen Marker und Popups, binden eine Adresssuche über die Geocoding API an und schließen mit einer produktionsreifen React-Komponente ab, die sich sauber in Next.js einfügt.

Das haben Sie am Ende gebaut:

• Eine Live-Vektorkarte, authentifiziert mit Ihrem API-Schlüssel
• Klickbare Marker mit eigenem Popup-Inhalt
• Eine Adresssuche auf Basis der Geocoding API
• Eine wiederverwendbare React-Komponente mit sauberem Cleanup und SSR-Handling für Next.js
• Eine Checkliste mit Performance-Optimierungen für den Produktivbetrieb

Voraussetzungen

Bevor Sie loslegen, brauchen Sie:

• Einen MapAtlas-API-Schlüssel (kostenlos registrieren, keine Kreditkarte nötig). Dieser eine Schlüssel authentifiziert alle MapAtlas-Dienste: Kacheln, Geocoding und Routing.
• Ein JavaScript-Projekt. Reines HTML, React, Vue oder Svelte funktionieren gleichermaßen.
• Node.js 18 oder neuer, falls Sie über npm installieren.

Schritt 1: MapAtlas SDK installieren

Installieren Sie das SDK mit npm in Ihrem Projekt:

npm install @mapmetrics/mapmetrics-gl

Arbeiten Sie stattdessen mit einer einfachen HTML-Seite, fügen Sie die CDN-Links in den <head> ein:

<link
  rel="stylesheet"
  href="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css"
/>
<script src="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.js"></script>

Lassen Sie den CSS-Import nicht weg. Ohne ihn werden Kartensteuerelemente und Popups ohne Styles gerendert. Das funktioniert zwar, sieht aber kaputt aus.

Schritt 2: Karten-Container anlegen

Das SDK füllt das Element aus, auf das Sie es ansetzen. Sie brauchen also ein <div> mit einer expliziten Höhe. Das ist der häufigste Fehler beim Setup: Hat der Container height: 0, wird die Karte zwar initialisiert, bleibt aber unsichtbar.

<div id="map" style="width: 100%; height: 500px;"></div>

Ein fester Pixelwert und eine Viewport-Einheit (100vh, 50vh) funktionieren beide. Prozentuale Höhen greifen nur, wenn auch das Elternelement eine definierte Höhe hat.

Schritt 3: Die erste interaktive Karte rendern

Mehr als drei Konfigurationsangaben brauchen Sie nicht: einen Container, eine Style-URL mit Ihrem API-Schlüssel und eine Startposition.

import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=YOUR_API_KEY',
  center: [4.9041, 52.3676], // [Längengrad, Breitengrad]
  zoom: 12,
});

Öffnen Sie die Seite, und Sie sehen eine Vektorkarte, die sich per Ziehen, Scrollen und Pinch-Geste bedienen lässt. Die Kacheln werden bei Bedarf von den MapAtlas-Servern geladen, einen großen Download vorab gibt es nicht.

Kartenstil auswählen

Kartenstile liegen in Ihrem Konto. Öffnen Sie im MapMetrics-Portal den Bereich Styles, erstellen oder bearbeiten Sie einen Stil, speichern Sie ihn und kopieren Sie seine Style-URL. Die URL enthält bereits Ihren Token und kommt deshalb direkt in die Option style. Legen Sie für jedes benötigte Erscheinungsbild einen eigenen Stil an, etwa einen hellen Stil für allgemeine Anwendungen und einen dunklen für Dashboards, und wechseln Sie mit map.setStyle() zwischen ihnen.

Schneller Gewinn: Verwenden Sie einen dunklen Stil für Admin-Panels und Tools, die bei wenig Licht genutzt werden. Viele Nutzer bevorzugen ihn in abgedunkelten Räumen, und er hebt Daten-Layer wie Heatmaps und Routenlinien deutlich vom Hintergrund ab.

Schritt 4: Marker und Popups zur Karte hinzufügen

Eine Karte ohne Marker ist nur ein Hintergrundbild. Erst Marker machen aus einer statischen Ansicht etwas, mit dem Nutzer interagieren können.

Einzelner Marker mit Popup

const popup = new mapmetricsgl.Popup().setHTML(`
  <strong>Amsterdam Central</strong>
  <p>Stationsplein, 1012 AB Amsterdam</p>
`);

new mapmetricsgl.Marker({ color: '#97C70A' })
  .setLngLat([4.9001, 52.3791])
  .setPopup(popup)
  .addTo(map);

Klicken Sie auf den Marker, und das Popup öffnet sich. Darin kann beliebiges HTML stehen: Adressen, Vorschaubilder, CTA-Buttons oder was Ihre Oberfläche sonst braucht.

Mehrere Marker aus Daten darstellen

Die meisten Anwendungen in der Praxis brauchen mehr als einen Pin. Ein Live-Beispiel ist OnlyHere, ein täglicher Guide für Unternehmungen in London, der jede Veranstaltung auf einer interaktiven MapAtlas-Karte darstellt. So sehen Sie nach Veranstaltungsort und Stadtviertel, was gerade los ist. Iterieren Sie über ein Array und erzeugen Sie für jeden Eintrag einen Marker:

const locations = [
  { name: 'Amsterdam', coords: [4.9041, 52.3676] },
  { name: 'Rotterdam', coords: [4.4777, 51.9244] },
  { name: 'Utrecht',   coords: [5.1214, 52.0907] },
];

locations.forEach(({ name, coords }) => {
  const popup = new mapmetricsgl.Popup().setHTML(`<strong>${name}</strong>`);
  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat(coords)
    .setPopup(popup)
    .addTo(map);
});

Hinweis zur Performance: HTML-Marker sind DOM-Elemente, daher bremsen schon einige hundert davon die Karte in herausgezoomten Ansichten aus. Verschieben Sie die Punkte dann in eine GeoJSON-Quelle mit Clustering (das SDK unterstützt es ab Werk) und zeichnen Sie sie als Layer. Die Konfiguration des Clusterings beschreibt die SDK-Dokumentation.

Schritt 5: Adresssuche mit der Geocoding API ergänzen

Die Geocoding API wandelt eine Textanfrage (eine Straßenadresse, einen Ortsnamen oder eine Sehenswürdigkeit) in Koordinaten um. Zu diesen Koordinaten können Sie die Karte schwenken, einen Marker setzen oder sie an eine Routing-Anfrage übergeben.

async function searchAddress(query) {
  const url = new URL('https://gateway.mapmetrics-atlas.net/forward-geocode/');
  url.searchParams.set('text', query);
  url.searchParams.set('token', 'YOUR_API_KEY');

  const res  = await fetch(url);
  const data = await res.json();

  if (!data.features.length) return;

  const [lng, lat] = data.features[0].geometry.coordinates;
  const label      = data.features[0].properties.label;

  map.flyTo({ center: [lng, lat], zoom: 14 });

  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat([lng, lat])
    .setPopup(new mapmetricsgl.Popup().setHTML(`<strong>${label}</strong>`))
    .addTo(map);
}

// Ausprobieren
searchAddress('Rijksmuseum, Amsterdam');

Die Ergebnisse kommen als GeoJSON-Features zurück. Sie lassen sich daher direkt in jeden GeoJSON-kompatiblen Layer, eine Datentabelle oder einen nachgelagerten API-Aufruf übernehmen.

Eine Live-Suchleiste in unter 30 Zeilen: Hängen Sie searchAddress an das input-Event eines Textfelds, versehen Sie den Aufruf mit einem Debounce von 300 ms, und Sie haben eine Kartensuche mit Autocomplete-Verhalten ohne zusätzliche Abhängigkeiten.

Interaktive Karten in React integrieren

Eine wiederverwendbare Kartenkomponente

Legen Sie die Initialisierung der Karte in useEffect, damit sie erst nach dem Mounten des DOM läuft. Geben Sie außerdem eine Cleanup-Funktion zurück, um Speicherlecks beim Unmount zu vermeiden:

import { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

export function MapAtlasMap({
  apiKey,
  center = [4.9041, 52.3676],
  zoom   = 12,
}) {
  const containerRef = useRef(null);

  useEffect(() => {
    const map = new mapmetricsgl.Map({
      container: containerRef.current,
      style: `https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=${apiKey}`,
      center,
      zoom,
    });

    return () => map.remove();
  }, [apiKey]);

  return <div ref={containerRef} style={{ width: '100%', height: '500px' }} />;
}

Anschließend können Sie die Komponente an beliebiger Stelle im Komponentenbaum verwenden:

<MapAtlasMap
  apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY}
  center={[4.9041, 52.3676]}
  zoom={13}
/>

Serverseitiges Rendering in Next.js behandeln

Das Karten-SDK braucht Browser-APIs (window, document), die beim SSR nicht existieren. Importieren Sie die Komponente deshalb dynamisch und mit deaktiviertem SSR:

import dynamic from 'next/dynamic';

const MapAtlasMap = dynamic(
  () => import('./MapAtlasMap').then(m => m.MapAtlasMap),
  {
    ssr: false,
    loading: () => (
      <div style={{ height: 500, background: '#f0f1f3', borderRadius: 12 }} />
    ),
  }
);

Der loading-Platzhalter hält Ihr Layout stabil, während das Karten-Bundle lädt. Das verhindert Cumulative Layout Shift (CLS), der sowohl für die Nutzererfahrung als auch für die Core Web Vitals zählt.

Checkliste für die Performance im Produktivbetrieb

Gehen Sie vor dem Release diese Optimierungen durch:

• Karten unterhalb des sichtbaren Bereichs per Lazy Loading laden. Initialisieren Sie die Karte mit IntersectionObserver erst, wenn ihr Container in den Viewport scrollt. So fallen rund 250 KB komprimiertes JavaScript aus dem initialen Seitenaufruf heraus.
• Bei Vektorkacheln bleiben. Vektorkacheln skalieren verlustfrei auf jede Pixeldichte, benötigen beim Zoomen weniger Anfragen und lassen sich clientseitig ohne zusätzliche Serveranfragen umstylen. MapAtlas liefert standardmäßig Vektorkacheln aus.
• Große Marker-Mengen clustern. Einige hundert HTML-Marker führen in herausgezoomten Ansichten zu spürbaren Frame-Drops. Ein geclusterter GeoJSON-Layer vermeidet das.
• Browser-Schlüssel einschränken. Ein Schlüssel, der im Browser verwendet wird, auch einer in einer NEXT_PUBLIC_-Umgebungsvariable, ist für jeden sichtbar, der die DevTools öffnet. Committen Sie Schlüssel nie in ein öffentliches Repository, beschränken Sie Browser-Schlüssel im Portal auf Ihre eigenen Domains und leiten Sie Anfragen für sensible Vorgänge über Ihr Backend.
• maxBounds für regionale Anwendungen setzen. Interessieren sich Ihre Nutzer nur für eine bestimmte Region, begrenzen Sie den Kartenausschnitt, damit Kacheln außerhalb dieses Gebiets gar nicht erst angefordert werden. Weniger Netzwerkanfragen, schnellere Ladezeiten.

Was Sie als Nächstes bauen können

Sie haben jetzt eine Karte, die rendert, Marker anzeigt, Adressen sucht und sich in React einfügt. So geht es weiter:

• Routing API: Fragen Sie eine Wegbeschreibung mit Abbiegehinweisen zwischen zwei Koordinaten ab. Die Antwort enthält die Route als Polyline, die Gesamtstrecke und die geschätzte Fahrzeit.
• Isochrone API: Erzeugen Sie ein Polygon, das jeden Punkt abdeckt, der innerhalb von n Minuten erreichbar ist. Typische Einsätze sind Liefergebiete, Karten zur Serviceabdeckung und Einzugsgebietsanalysen.
• Matrix API: Berechnen Sie Fahrzeiten und Entfernungen zwischen mehreren Start- und Zielpunkten in einer einzigen Anfrage. Für Flottendisposition und Logistikoptimierung ist das unverzichtbar.

Die vollständige SDK-Referenz, die Dokumentation der Kartenstile und API-Anleitungen finden Sie unter docs.mapatlas.xyz.

Weiterlesen: So findet KI Ihre Website 2026 erklärt, warum strukturierte, per API zugängliche Daten wie diese heute entscheidend dafür sind, von KI-Agenten gefunden zu werden.

Häufig gestellte Fragen

Kann ich meiner Website kostenlos interaktive Karten hinzufügen?

Ja. MapAtlas bietet einen kostenlosen Tarif, für die Registrierung ist keine Kreditkarte nötig. Er umfasst das Rendering von Vektorkacheln, die Geocoding API und die Routing API. Das reicht für die Entwicklung und für kleinere Produktivprojekte.

Wie binde ich eine Karte in eine React- oder Next.js-App ein?

Legen Sie die Initialisierung der Karte in einen useEffect-Hook, damit sie nach dem Mounten des DOM läuft. In Next.js verwenden Sie dynamic() mit ssr: false, um Fehler beim serverseitigen Rendering zu vermeiden. Beide Varianten zeigt dieses Tutorial mit Beispielen zum Kopieren.

Was sind Vektorkacheln, und warum sind sie Rasterkacheln vorzuziehen?

Vektorkacheln beschreiben Kartenobjekte (Straßen, Gebäude, Beschriftungen) als mathematische Geometrie statt als vorgerenderte Pixelbilder. Sie bleiben in jeder Auflösung scharf, benötigen beim Zoomen weniger Downloads und lassen sich vollständig im Client umstylen, ohne zusätzliche Roundtrips zum Server.

Wie viele Marker kann ich hinzufügen, bevor die Performance leidet?

Bei niedrigen Zoomstufen lässt das Rendering in der Regel nach, sobald einige hundert HTML-Marker erreicht sind. Die Lösung ist Clustering: Das MapAtlas SDK unterstützt Clustering für GeoJSON-Quellen nativ. Es fasst nahe Marker bei niedrigem Zoom zusammen und löst sie beim Hineinzoomen wieder auf.

Brauche ich GIS-Erfahrung, um MapAtlas zu nutzen?

Nein. Das SDK richtet sich an Webentwickler, nicht an GIS-Spezialisten. Sie initialisieren eine Karte mit Koordinaten und Zoomstufe, setzen Marker über Längen- und Breitengrade und rufen die Geocoding API mit einfachem Text auf. Räumliche Datenbanken oder GIS-Werkzeuge sind nicht nötig.

Weiterführende Artikel:

• Eine Immobilienkarte mit Clustering erstellen
• Einen Store Locator mit einer Maps API bauen
• Alternativen zur Google Maps API für Entwickler in der EU
• Kostenlos loslegen