Interaktive Karten zu Ihrer Website hinzufuegen | JavaScript Tutorial (2026) | MapAtlas Blog

Jedes Logistik-Dashboard, jedes Immobilieninserat und jede Lieferapp haben etwas gemeinsam: eine Karte. Wenn Ihre Website noch keine hat, lassen Sie wichtigen Kontext liegen. Kontext, der Benutzern hilft, Orte, Entfernungen und raeumliche Beziehungen auf einen Blick zu verstehen.

Dieses Tutorial zeigt Ihnen, wie Sie eine vollstaendig interaktive Karte zu jedem JavaScript-Projekt hinzufuegen. Sie beginnen mit einer gerenderten Karte, fuegen Marker und Popups hinzu, verbinden eine Adresssuche mit der Geocoding API und enden mit einer produktionsreifen React-Komponente, die sauber in Next.js integiert.

Das werden Sie am Ende bauen:

Eine Live-Vektor-Karte, authentifiziert mit Ihrem API-Schluessel
Anklickbare Marker mit benutzerdefiniertem Popup-Inhalt
Eine Geocoding-gesteuerte Adressensuchfunktion
Eine wiederverwendbare React-Komponente mit angemessenem Cleanup und Next.js SSR-Handhabung
Eine Checkliste von Performance-Optimierungen fuer die Produktion

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie haben:

Ein MapAtlas API-Schluessel (kostenlos anmelden, keine Kreditkarte erforderlich). Dieser einzelne Schluessel authentifiziert jeden MapAtlas-Dienst: Kacheln, Geocoding und Routing.
Ein JavaScript-Projekt. Plain HTML, React, Vue oder Svelte funktionieren alle.
Node.js 18+ wenn Sie ueber npm installieren.

Schritt 1: MapAtlas SDK installieren

Ziehen Sie das SDK mit npm in Ihr Projekt:

npm install @mapmetrics/mapmetrics-gl

Wenn Sie stattdessen mit einer einfachen HTML-Seite arbeiten, fuegen Sie die CDN-Links in Ihren <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>

Ueberspringen Sie nicht den CSS-Import. Ohne ihn werden Kartenbedienelemente und Popups unstyled gerendert. Funktional, aber visuell beschaedigt.

Schritt 2: Einen Karten-Container erstellen

Das SDK fuellt das Element aus, auf das Sie es zeigen, also brauchen Sie ein <div> mit einer expliziten Hoehe. Dies ist das einzelne haeufigstes Setup-Fehler: wenn der Container height: 0 hat, wird die Karte initialisiert, bleibt aber unsichtbar.

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

Ein fester Pixelwert oder eine Viewport-Einheit (100vh, 50vh) funktionieren beide. Prozentuale Hoehen funktionieren nur, wenn das Parent-Element auch eine definierte Hoehe hat.

Schritt 3: Ihre erste interaktive Karte rendern

Drei Zeilen Konfiguration sind alles, was Sie brauchen: ein Container, eine Style-URL mit Ihrem API-Schluessel und eine Anfangsposition.

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

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
  center: [4.9041, 52.3676], // [longitude, latitude]
  zoom: 12,
});

Oeffnen Sie die Seite und Sie sehen eine Vektor-Karte, die Sie ziehen, scrollen und pinchen koennen, um sie zu navigieren. Kacheln werden bei Bedarf von MapAtlas-Servern geladen, also gibt es keinen schweren vorherigen Download.

Einen Karten-Stil auswaehlen

Tauschen Sie das Pfad-Segment in der Style-URL aus, um das Aussehen komplett zu aendern:

Style	URL-Pfad	Am besten fuer
Basic	`/styles/basic/style.json`	Allgemeine Apps
Bright	`/styles/bright/style.json`	Datenvisualisierungs-Overlays
Dark	`/styles/dark/style.json`	Dashboards, Nachtmodus, Analysen

Quick Win: Verwenden Sie den Dark-Stil fuer Admin-Panels und Tools, die in Low-Light-Umgebungen verwendet werden. Es reduziert Augenbelastung und laesst Datenschichten wie Waermekarten und Routenlinien visuell gegenueber dem Hintergrund hervorstechen.

Schritt 4: Marker und Popups zu Ihrer Karte hinzufuegen

Eine Karte ohne Marker ist nur ein Hintergrundbild. Marker verwandeln eine statische Ansicht in etwas, mit dem Benutzer interagieren koennen.

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 oeffnet sich. Sie koennen beliebig HTML einfuegen: Adressen, Miniaturen, CTA-Buttons, was auch immer Ihre UI erfordert.

Mehrere Marker aus Daten zeichnen

Die meisten realen Apps brauchen mehr als einen Pin. Durchlaufen Sie ein Array und erstellen Sie fuer 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);
});

Performance-Hinweis: Wenn Sie ungefaehr 100 bis 200 Marker ueberschreiten, wird das Rendering bei verkleinerten Ansichten deutlich langsamer. Aktivieren Sie GeoJSON-Quellen-Clustering (wird vom SDK standardmaessig unterstuetzt), um nahegelegene Marker bei niedriger Zoomstufe zu gruppieren. Weitere Informationen finden Sie in der SDK-Dokumentation.

Schritt 5: Adresssuche mit der Geocoding API hinzufuegen

Die Geocoding API verwandelt eine Textabfrage (eine Straeenadresse, einen Stadtnamen oder einen Ort) in Koordinaten, zu denen Sie schwenken, markieren oder in eine Routing-Anfrage einspeisen koennen.

async function searchAddress(query) {
  const url = new URL('https://api.mapatlas.eu/geocoding/v1/search');
  url.searchParams.set('text', query);
  url.searchParams.set('key', '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);
}

// Try it
searchAddress('Rijksmuseum, Amsterdam');

Ergebnisse kommen als GeoJSON-Features zurueck, also integieren sie sich direkt in jede GeoJSON-kompatible Schicht, Tabelle oder nachgelagerte API-Aufrufe.

Bauen Sie eine Live-Suchleiste in unter 30 Zeilen: Befestigen Sie searchAddress am input-Event eines Textfeldes, entfernde Sie es um 300ms, und Sie haben Autocomplete-artige Kartensuche ohne zusaetzliche Abhaengigkeiten.

Interaktive Karten mit React integrieren

Eine wiederverwendbare Karten-Komponente

Wickeln Sie die Karten-Initialisierung in useEffect ein, damit sie nach dem DOM-Einbinden ausgefuehrt wird, und geben Sie eine Cleanup-Funktion zurueck, um Speicherlecks beim Entfernen zu verhindern:

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://tiles.mapatlas.eu/styles/basic/style.json?key=${apiKey}`,
      center,
      zoom,
    });

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

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

Verwenden Sie sie ueberall in Ihrem Komponenten-Baum:

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

Next.js Server-Side Rendering behandeln

Das Karten-SDK haengt von Browser-APIs (window, document) ab, die waehrend SSR nicht vorhanden sind. Importieren Sie die Komponente dynamisch 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 haelt Ihr Layout stabil, waehrend das Karten-Bundle heruntergeladen wird, und verhindert kumulative Layoutverschiebung (CLS), was sowohl fuer die Benutzererfahrung als auch fuer Core Web Vitals wichtig ist.

Produktion Performance Checkliste

Bevor Sie versenden, gehen Sie diese Optimierungen durch:

Lazy-Load-Karten unterhalb des Umbruchs. Verwenden Sie IntersectionObserver, um die Karte nur dann zu initialisieren, wenn ihr Container in den Sichtbereich scrollt. Dies verschiebt ungefaehr 200 KB JavaScript vom initialen Seitenladung.
Bleiben Sie bei Vektor-Kacheln. Vektor-Kacheln skalieren sauber auf jede Bildschirmdichte, laden schneller als Rasterbilder und koennen client-seitig ohne zusaetzliche Server-Anfragen erneuert werden. MapAtlas serviert standardmaessig Vektor-Kacheln.
Cluster grosse Marker-Sets. Ueber 100 bis 200 Marker hinaus fuehrt unklugertes Rendering in einer verkleinerten Ansicht zu merklichen Frame-Drops. Clustering loest dies komplett.
Behalten Sie Ihren API-Schluessel server-seitig. Commitieren Sie niemals Schluessel zu einem oeffentlichen Repository. Verwenden Sie Umgebungsvariablen (NEXT_PUBLIC_MAPATLAS_KEY in Next.js) oder Proxy-Anfragen ueber Ihr Backend fuer sensible Operationen.
Legen Sie maxBounds fuer regionale Apps fest. Wenn sich Ihre Benutzer nur um eine Geographie kuemmern, beschraenken Sie die Ansicht, damit Kacheln ausserhalb dieses Bereichs niemals angefordert werden. Weniger Netzwerkanrufe, schnellere Auslastung.

Was als Naechstes gebaut wird

Sie haben eine Karte, die rendert, Marker zeigt, Adressen sucht und mit React integriert. Hier geht es weiter:

Routing API: Fordern Sie Turn-by-Turn-Anweisungen zwischen zwei Koordinaten an. Gibt eine Routen-Polyline, Gesamtentfernung und geschaetzte Reisezeit zurueck.
Isochrone API: Generieren Sie ein Polygon, das jeden Punkt abdeckt, der innerhalb von n Minuten erreichbar ist. Wird fuer Lieferzonen, Service-Coverage-Maps und Einzugsbereits-Analysen verwendet.
Matrix API: Berechnen Sie Reisezeit und Entfernung zwischen mehreren Urspruengen und Zielen in einer einzelnen Anfrage. Essentiell fuer Fleet-Dispatch und Logistik-Optimierung.

Vollstaendige SDK-Referenz, Style-Dokumentation und API-Anleitungen finden Sie unter docs.mapatlas.xyz.

Haeufig gestellte Fragen

Kann ich kostenlos interaktive Karten zu meiner Website hinzufuegen?

Ja. MapAtlas bietet einen kostenlosen Tarif ohne Kreditkarte bei der Anmeldung. Er umfasst Vektor-Kachel-Rendering, die Geocoding API und die Routing API. Das ist genug fuer Entwicklung und kleinere Produktionsnutzung.

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

Wickeln Sie die Karten-Initialisierung in einen useEffect-Hook ein, damit er nach dem DOM-Einbinden ausgefuehrt wird. In Next.js verwenden Sie dynamic() mit ssr: false, um Fehler beim Server-seitigen Rendering zu vermeiden. Beide Ansaetze werden mit copy-paste-Beispielen in diesem Tutorial behandelt.

Was sind Vektor-Kacheln und warum sollte ich sie gegenueber Rastern verwenden?

Vektor-Kacheln beschreiben Kartenfunktionen (Strassen, Gebaeude, Labels) als mathematische Geometrie anstelle von vorgerenderten Pixel-Bildern. Sie skalieren scharf auf jede Aufloesung, werden schneller heruntergeladen und koennen komplett auf dem Client ohne zusaetzliche Server-Roundtrips erneuert werden.

Wie viele Marker kann ich hinzufuegen, bevor sich die Performance verschlechtert?

Das Rendering verschlechtert sich typischerweise ueber 100 bis 200 Marker bei niedriger Zoomstufe. Die Loesung ist Clustering: Das MapAtlas SDK unterstuetzt GeoJSON-Quellen-Clustering nativ und gruppiert nahegelegene Marker bei niedriger Zoomstufe und erweitert sie, wenn der Benutzer vergroessert.

Brauche ich GIS-Erfahrung, um MapAtlas zu verwenden?

Nein. Das SDK ist fuer Web-Entwickler konzipiert, nicht fuer GIS-Spezialisten. Sie initialisieren eine Karte mit Koordinaten und Zoomstufe, fuegen Marker mit Laengen-/Breitengradpaaren hinzu und rufen die Geocoding API mit einfachem Text auf. Keine raeuumlichen Datenbanken oder GIS-Tools erforderlich.

Interaktive Karten zu Ihrer Website hinzufuegen | JavaScript Tutorial (2026)