JavaScript Heatmap Tutorial: Interaktive Dichtekarte bauen

Eine Heatmap verwandelt eine Wolke aus Koordinaten in eine Dichteoberfläche, die man auf einen Blick lesen kann. Warme Farben zeigen, wo sich Ereignisse häufen, kühle Farben zeigen, wo sie seltener werden. Nutzer erkennen das Muster, bevor sie ein einziges Label lesen. Deshalb sind Heatmaps die erste Wahl für Passantenfrequenz-Analysen, Prognosen der Liefernachfrage, Tools für Kriminalitätsstatistiken und die Recherche von Immobilienpreisen.

Dieses Tutorial baut mit dem MapAtlas SDK eine interaktive Heatmap von Grund auf. Sie strukturieren Punktdaten als gewichtetes GeoJSON, rendern einen Dichte-Layer mit eigenem Farbverlauf, binden einen Schieberegler an und schließen mit einem realen Beispiel zur Liefernachfrage ab. Am Ende steht ein wiederverwendbares Muster, das Sie in jedes JavaScript- oder React-Projekt übernehmen können.

Wenn Sie das MapAtlas SDK noch nicht kennen, lesen Sie zuerst Interaktive Karten in die eigene Website einbinden. Dort geht es um Installation, Initialisierung der Karte und Marker. Dieses Tutorial setzt genau dort an.

Wann sich eine Heatmap eignet

Eine Heatmap ist das richtige Werkzeug, wenn Sie viele einzelne Punktstandorte haben und Dichte zeigen wollen, nicht Identität. Einzelne Marker verlieren ab einigen hundert Punkten ihre Aussagekraft. Eine Heatmap macht Strukturen sichtbar, die mit noch so vielen Pins nicht erkennbar wären.

Typische Anwendungsfälle:

• Analyse der Passantenfrequenz: Standortwahl im Einzelhandel, Stadtplanung, Modellierung von Besucherströmen bei Events. Setzen Sie für jeden Kunden, der eine Tür passiert hat, einen GPS-Ping, und die Heatmap zeigt, welche Bereiche einer Stadt, eines Einkaufszentrums oder eines Veranstaltungsorts die meisten Menschen anziehen.
• Liefernachfrage: Aggregieren Sie die Herkunft von Bestellungen nach Postleitzahl oder Rohkoordinate, damit Disponenten sehen, wo sich die Nachfrage konzentriert. Das fließt direkt in die Zonenplanung und die Einteilung der Fahrer ein.
• Kriminalitäts- und Vorfallsdaten: Analytics-Dashboards der Polizei, Risikokarten von Versicherungen und Tools für die öffentliche Sicherheit nutzen Dichte-Heatmaps, um räumliche Risiken zu vermitteln, ohne Nutzer mit einzelnen Markern zu überfordern.
• Preisgefälle bei Immobilien: Mit gewichteten Werten kombiniert zeigt eine Heatmap, wo die Preise in einer Stadt am höchsten sind. Mehr zum Bau von Kartentools für Immobilien steht im Tutorial zur Immobilienkarte.

Lautet Ihre Frage "Wo passiert am meisten?", dann ist eine Heatmap die Antwort.

Datenformat: gewichtete GeoJSON-Punkte

Der Heatmap-Layer von MapAtlas liest eine Standard-GeoJSON-FeatureCollection aus Point-Features. Jedes Feature kann eine weight-Property tragen, die seinen Beitrag zur Dichteoberfläche skaliert. Eine Lieferung mit 10 Artikeln erzeugt mehr Hitze als eine Bestellung mit einem Artikel, ein großer Verkehrsknoten erzeugt mehr Passantenfrequenz als eine Seitenstraße.

const demandData = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      geometry: { type: "Point", coordinates: [4.8952, 52.3702] },
      properties: { weight: 8, zone: "centrum" }
    },
    {
      type: "Feature",
      geometry: { type: "Point", coordinates: [4.9123, 52.3601] },
      properties: { weight: 3, zone: "oost" }
    },
    {
      type: "Feature",
      geometry: { type: "Point", coordinates: [4.8801, 52.3780] },
      properties: { weight: 12, zone: "west" }
    },
    {
      type: "Feature",
      geometry: { type: "Point", coordinates: [4.9041, 52.3540] },
      properties: { weight: 1, zone: "south" }
    }
  ]
};

Der weight-Wert ist dimensionslos. Normalisieren Sie ihn relativ zur Spannweite Ihres Datensatzes. Erzeugt Ihre stärkste Zone 500 Bestellungen und Ihre ruhigste 10, bilden Sie diese Werte vor der Übergabe auf eine Skala von 1 bis 10 ab. So bleibt die Heatmap auch bei Datensätzen mit sehr unterschiedlichen absoluten Zahlen aussagekräftig.

Ohne weight-Property trägt jeder Punkt gleich viel bei, und die Heatmap bildet die reine Anzahldichte ab.

Voraussetzungen

Bevor Sie beginnen:

• Ein MapAtlas API-Schlüssel (kostenlos registrieren, keine Kreditkarte nötig)
• Node.js 18+ für npm-basierte Projekte, oder eine einfache HTML-Seite, wenn Sie das CDN bevorzugen

Schritt 1: SDK installieren und Karte initialisieren

Installieren Sie das SDK:

npm install @mapmetrics/mapmetrics-gl

Oder laden Sie es in einer einfachen HTML-Datei über das CDN:

<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>

Legen Sie einen Container mit definierter Höhe an:

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

Initialisieren Sie die Karte mit einem dunklen Style aus Ihrem Account. Auf einer dunklen Basis heben sich die Farbverläufe der Heatmap deutlich vom Hintergrund ab, deshalb ist sie die bevorzugte Basis für Dichtevisualisierungen:

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_DARK_STYLE_ID/style.json&token=YOUR_API_KEY',
  center: [4.9041, 52.3676], // Amsterdam
  zoom: 12,
});

Schritt 2: Heatmap-Layer hinzufügen

Registrieren Sie Ihr GeoJSON als Source und fügen Sie dann einen Heatmap-Layer hinzu, der daraus liest. Der Callback map.on('load', ...) stellt sicher, dass der Style vollständig geladen ist, bevor Sie ihn verändern.

map.on('load', () => {
  map.addSource('demand', {
    type: 'geojson',
    data: demandData,
  });

  map.addLayer({
    id: 'demand-heatmap',
    type: 'heatmap',
    source: 'demand',
    paint: {
      // Jeden Punkt nach seiner 'weight'-Property gewichten (Standard 1, falls nicht vorhanden)
      'heatmap-weight': [
        'interpolate', ['linear'],
        ['get', 'weight'],
        0, 0,
        12, 1
      ],
      // Radius in Pixeln; größer = glatter, aber ungenauer
      'heatmap-radius': 30,
      // Gesamtdeckkraft des Heatmap-Layers
      'heatmap-opacity': 0.85,
    },
  });
});

Damit haben Sie eine funktionierende Heatmap. Blaugrüne Bereiche stehen für geringe Dichte, bei hoher Dichte wechselt der Standardverlauf zu Gelb und Rot. Im nächsten Schritt ersetzen Sie die Standardpalette durch ein bewusst gewähltes Farbschema.

Schritt 3: Farbverlauf anpassen

Die Property heatmap-color ordnet Dichtewerten (0 bis 1) Farben zu. Sie nutzt dieselbe interpolate-Expression wie das übrige Paint-System von MapAtlas. Dichte 0 ist transparent, damit in leeren Bereichen die Basiskarte sichtbar bleibt.

map.addLayer({
  id: 'demand-heatmap',
  type: 'heatmap',
  source: 'demand',
  paint: {
    'heatmap-weight': [
      'interpolate', ['linear'],
      ['get', 'weight'],
      0, 0,
      12, 1
    ],
    'heatmap-radius': 30,
    'heatmap-opacity': 0.85,
    'heatmap-color': [
      'interpolate', ['linear'],
      ['heatmap-density'],
      0,    'rgba(0, 0, 255, 0)',   // transparent bei Dichte null
      0.2,  'rgba(0, 128, 255, 0.6)',
      0.4,  'rgba(0, 230, 200, 0.7)',
      0.6,  'rgba(100, 230, 0, 0.8)',
      0.8,  'rgba(255, 200, 0, 0.9)',
      1.0,  'rgba(255, 50, 0, 1)'   // leuchtendes Rot bei maximaler Dichte
    ],
  },
});

Dieser Verlauf reicht von Blau (dünn besetzt) über Grün und Gelb bis Rot (dicht). Das entspricht dem Bild, das die meisten Nutzer von Wetterradar und Wärmebildern kennen. Hat Ihre App eine eigene Markenpalette, ersetzen Sie die RGB-Werte durch eigene Stopps. Die Interpolation sorgt automatisch für weiche Übergänge.

Design-Tipp: Halten Sie in professionellen Dashboards und Analytics-Tools das Ende mit geringer Dichte fast transparent. So bleibt die Basiskarte in ruhigen Bereichen lesbar, und der Blick wandert von selbst zu den Hotspots.

Schritt 4: Radius-Schieberegler für interaktive Steuerung

Der Heatmap-Radius bestimmt, wie weit jeder Punkt seinen Einfluss "ausstrahlt". Ein kleiner Radius (10 bis 15px) zeigt feinkörnige Cluster, ein großer Radius (50 bis 80px) erzeugt eine breitere, glattere Fläche. Unterschiedliche Anwendungsfälle brauchen unterschiedliche Standardwerte: Passantenfrequenz in einer dichten Innenstadt braucht einen kleinen Radius, landesweite Liefernachfrage einen großen.

Geben Sie Nutzern einen Schieberegler, mit dem sie den Wert live anpassen:

<div id="controls" style="position: absolute; top: 16px; left: 16px; z-index: 1;
     background: white; padding: 12px 16px; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.2);">
  <label style="font-size: 14px; font-weight: 600;">
    Radius: <span id="radius-value">30</span>px
  </label>
  <br />
  <input id="radius-slider" type="range" min="5" max="80" value="30" style="width: 180px; margin-top: 6px;" />
</div>

Verbinden Sie den Regler mit setPaintProperty. Die Methode aktualisiert den Layer, ohne ihn neu hinzuzufügen:

const slider = document.getElementById('radius-slider');
const radiusLabel = document.getElementById('radius-value');

slider.addEventListener('input', () => {
  const radius = Number(slider.value);
  radiusLabel.textContent = radius;
  map.setPaintProperty('demand-heatmap', 'heatmap-radius', radius);
});

setPaintProperty aktualisiert live und ohne Flackern. Die Heatmap wird im selben Frame auf der GPU neu gerendert. Das Muster funktioniert für jede Paint-Property: Deckkraft, Intensität, Farbstopps.

Schritt 5: Intensität abhängig von der Zoomstufe skalieren

Bei niedrigen Zoomstufen (Ansicht der ganzen Stadt) überlappen benachbarte Punkte stark, und die Heatmap wirkt gleichmäßig gesättigt. Bei hohem Zoom (Straßenebene) verteilen sich dieselben Punkte, und die Dichteoberfläche wirkt spärlich. Eine an den Zoom gekoppelte Intensität gleicht das aus und hält die Visualisierung auf jeder Stufe lesbar.

paint: {
  // ...weitere Paint-Properties...
  'heatmap-intensity': [
    'interpolate', ['linear'],
    ['zoom'],
    8,  1,   // niedriger Zoom: normale Intensität
    14, 3    // hoher Zoom: Intensität erhöhen, um die Punktstreuung auszugleichen
  ],
  'heatmap-radius': [
    'interpolate', ['linear'],
    ['zoom'],
    8,  20,  // kleiner Radius im Stadtmaßstab
    14, 50   // größerer Radius auf Straßenebene
  ],
},

Beide Properties nutzen dieselbe interpolate-Expression über zoom. Werte zwischen den Stopps werden linear interpoliert, der Übergang beim Zoomen bleibt also fließend.

Praxisbeispiel: Heatmap der Liefernachfrage

Hier folgt eine vollständige, eigenständige Implementierung für ein Dashboard zur Liefernachfrage. Die Bestellungen kommen von einer API als GeoJSON-FeatureCollection. Die Heatmap aktualisiert sich, sobald der Nutzer den Zeitfilter ändert.

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

const API_KEY = 'YOUR_API_KEY';

const map = new mapmetricsgl.Map({
  container: 'map',
  style: `https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_DARK_STYLE_ID/style.json&token=${API_KEY}`,
  center: [4.9041, 52.3676],
  zoom: 11,
});

async function loadOrders(hourFrom, hourTo) {
  const res = await fetch(
    `/api/orders/geojson?hour_from=${hourFrom}&hour_to=${hourTo}`
  );
  return res.json(); // liefert eine GeoJSON FeatureCollection
}

map.on('load', async () => {
  const orders = await loadOrders(8, 12); // Morgenspitze

  map.addSource('orders', { type: 'geojson', data: orders });

  map.addLayer({
    id: 'order-heatmap',
    type: 'heatmap',
    source: 'orders',
    paint: {
      'heatmap-weight': [
        'interpolate', ['linear'], ['get', 'items'],
        0, 0, 20, 1
      ],
      'heatmap-color': [
        'interpolate', ['linear'], ['heatmap-density'],
        0,   'rgba(0, 0, 255, 0)',
        0.2, 'rgba(0, 128, 255, 0.5)',
        0.5, 'rgba(0, 230, 150, 0.8)',
        0.8, 'rgba(255, 200, 0, 0.9)',
        1.0, 'rgba(255, 50, 0, 1)'
      ],
      'heatmap-radius': [
        'interpolate', ['linear'], ['zoom'],
        8, 20, 14, 50
      ],
      'heatmap-intensity': [
        'interpolate', ['linear'], ['zoom'],
        8, 1, 14, 3
      ],
      'heatmap-opacity': 0.9,
    },
  });

  // Filter-Buttons nach Tageszeit
  document.querySelectorAll('[data-hour-range]').forEach((btn) => {
    btn.addEventListener('click', async () => {
      const [from, to] = btn.dataset.hourRange.split('-').map(Number);
      const newOrders = await loadOrders(from, to);
      map.getSource('orders').setData(newOrders);
    });
  });
});

Der Aufruf setData auf einer bestehenden Source ersetzt das GeoJSON, ohne den Layer neu hinzuzufügen. Die Heatmap wird automatisch neu gerendert. Das Muster lässt sich auf jeden zeitbasierten Filter übertragen: Tageszeit, Wochentag, Wetterlage.

Den Layer für die Routenplanung, der eine Heatmap der Liefernachfrage meist ergänzt, zeigt das Tutorial zur Route Optimization API. Liegt eine optimierte Lieferroute über der Nachfrage-Heatmap, sehen Disponenten das gesamte operative Bild in einer einzigen Ansicht.

Performance-Tipps für große Datensätze

Der Heatmap-Layer von MapAtlas nutzt WebGL und rendert schnell. Bei großen Datenmengen kann aber die Daten-Pipeline davor zum Engpass werden.

Sehr große Datensätze auf dem Server voraggregieren. Bei Millionen von GPS-Pings schicken Sie nicht alle an den Browser. Führen Sie serverseitig eine räumliche Aggregation aus (hexagonales H3-Raster, Quadtree oder einfaches Runden auf ein Raster), die 1 Million Rohpunkte auf 10.000 Rasterzellen mit einem count- und weight-Feld reduziert. Bei typischen Zoomstufen sieht die Heatmap nahezu identisch aus, sie lädt aber in einem Bruchteil der Zeit.

Updates inkrementell streamen. Nutzen Sie für Live-Daten (Passantenfrequenz in Echtzeit, eingehende Bestellungen) setData mit einem gleitenden Fenster aktueller Punkte, statt ein ständig wachsendes GeoJSON-Objekt aufzubauen. Begrenzen Sie die Source auf eine feste maximale Punktzahl und entfernen Sie alte Datensätze.

maxzoom auf der Source setzen. Mit maxzoom: 14 im addSource-Aufruf fordert das SDK oberhalb von Zoomstufe 14 keine Tile-Daten mehr an. Für Heatmaps spielt das selten eine Rolle, weil Heatmap-Layer eine einzelne flache GeoJSON-Source statt gekachelter Daten lesen. Es verhindert aber unnötige Neuberechnungen bei hohen Zoomstufen.

Paint-Expressions einfach halten. Der Farbverlauf von heatmap-color wird beim Setzen einmalig in eine Farbrampen-Textur umgerechnet, zusätzliche Farbstopps kosten pro Frame also fast nichts. Auf Mobilgeräten sind ein großer heatmap-radius und eine hohe Punktzahl die größeren Kostenfaktoren, optimieren Sie deshalb zuerst diese beiden Werte.

Karte per Lazy Initialization laden. Packen Sie die gesamte Initialisierung der Karte in einen IntersectionObserver-Callback, damit sie erst läuft, wenn der Container in den sichtbaren Bereich scrollt. Das nimmt das SDK-Bundle aus dem initialen Seitenaufruf und lohnt sich besonders auf Marketingseiten, auf denen die Karte unterhalb des sichtbaren Bereichs liegt.

Weitere Performance-Muster für Karten, darunter Lazy Loading und Clustering, fasst die Produktions-Checkliste in Interaktive Karten in die eigene Website einbinden vollständig zusammen.

Integration in React

Eine Heatmap in einer React-Komponente folgt demselben Muster wie jede MapAtlas-Karte: in useEffect initialisieren, den Zustand für Schieberegler und Filter über useState bereitstellen und beim Unmount aufräumen.

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

export function DeliveryHeatmap({ geojson, apiKey }) {
  const containerRef = useRef(null);
  const mapRef       = useRef(null);
  const [radius, setRadius] = useState(30);

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

    map.on('load', () => {
      map.addSource('orders', { type: 'geojson', data: geojson });
      map.addLayer({
        id: 'order-heatmap',
        type: 'heatmap',
        source: 'orders',
        paint: {
          'heatmap-radius': radius,
          'heatmap-opacity': 0.9,
        },
      });
    });

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

  // Radius aktualisieren, ohne die Karte neu zu mounten
  useEffect(() => {
    const map = mapRef.current;
    if (!map || !map.getLayer('order-heatmap')) return;
    map.setPaintProperty('order-heatmap', 'heatmap-radius', radius);
  }, [radius]);

  return (
    <div>
      <div style={{ padding: '8px 0' }}>
        <label>
          Radius: {radius}px
          <input
            type="range" min={5} max={80} value={radius}
            onChange={e => setRadius(Number(e.target.value))}
            style={{ marginLeft: 8, width: 160 }}
          />
        </label>
      </div>
      <div ref={containerRef} style={{ width: '100%', height: '600px' }} />
    </div>
  );
}

Importieren Sie die Komponente in Next.js mit dynamic(() => import('./DeliveryHeatmap'), { ssr: false }), um Fehler beim serverseitigen Rendering durch das reine Browser-SDK zu vermeiden.

Wie es weitergeht

Sie haben jetzt eine funktionierende interaktive Heatmap mit gewichteten Daten, eigenem Farbverlauf, Radius-Schieberegler und zoomabhängiger Intensität. So bauen Sie sie aus:

• Legen Sie einen Routing-Layer über die Heatmap, um geplante Lieferrouten vor der Nachfrageoberfläche zu zeigen. Das Tutorial zur Route Optimization API beschreibt die vollständige Implementierung.
• Ergänzen Sie eine Zeitanimation: Durchlaufen Sie stündliche Snapshots mit einer setInterval-Schleife, die setData auf der Source aufruft. Aus der statischen Dichtekarte wird so ein Zeitraffer, der zeigt, wie sich die Nachfrage über den Tag verschiebt.
• Kombinieren Sie die Heatmap mit Immobilienpreisen, um Preisgefälle nach Stadtviertel zu zeigen. Das Tutorial zur Immobilienkarte behandelt Muster für gewichtete Daten auf Immobilienplattformen.
• Auf der MapAtlas-Preisseite finden Sie den passenden Tarif für Ihren Produktions-Traffic.

Die vollständige SDK-Referenz und weitere Beispiele finden Sie unter docs.mapatlas.xyz.

Häufig gestellte Fragen

Was ist der Unterschied zwischen einer Heatmap und einer Choroplethenkarte?

Eine Heatmap visualisiert Punktdichte, indem sie benachbarte Punkte zu einem kontinuierlichen Farbverlauf verschmilzt. Sie eignet sich für Rohkoordinaten wie GPS-Pings oder Ereignisorte. Eine Choroplethenkarte färbt vordefinierte geografische Flächen (Länder, Postleitzahlgebiete, Zensusbezirke) nach einem statistischen Wert ein. Nutzen Sie eine Heatmap, wenn Sie viele einzelne Punkte haben, und eine Choroplethenkarte, wenn Ihre Daten bereits nach Regionen aggregiert sind.

Wie viele Datenpunkte verarbeitet eine JavaScript-Heatmap?

Der Heatmap-Layer von MapAtlas rendert per WebGL auf der GPU und verarbeitet deshalb Zehntausende Punkte auf typischer Hardware flüssig. Bei deutlich größeren Datensätzen, ab einigen Hunderttausend Punkten, erreichen Sie auf schwächeren Geräten eine bessere Performance, wenn Sie die Daten serverseitig zu einem gröberen Raster voraggregieren und auf einen GeoJSON-Layer vom Typ fill-extrusion oder circle wechseln.

Kann ich MapAtlas-Heatmaps kostenlos nutzen?

Ja. MapAtlas bietet einen kostenlosen Tarif mit Rendering von Karten-Tiles, Unterstützung für GeoJSON-Layer und Heatmap-Layern. Der kostenlose Tarif deckt die Entwicklung und Produktivbetrieb mit geringem Volumen ab. Alle Details zu den Tarifen stehen unter mapatlas.eu/pricing.

Funktionieren Heatmaps in mobilen Browsern?

Ja. Das MapAtlas SDK rendert mit WebGL, das alle modernen mobilen Browser unterstützen, darunter Safari auf iOS und Chrome auf Android. Bei sehr großen Datensätzen auf schwacher mobiler Hardware bleibt die Framerate flüssig, wenn Sie die Punktzahl reduzieren oder den Heatmap-Radius vergrößern.

Weiterführende Artikel:

• Interaktive Karten in die eigene Website einbinden
• Immobilienkarte mit Clustering bauen
• Route Optimization API: Lieferkosten um 30 % senken
• Kostenlos loslegen