JavaScript Geolocation API

Die Geolocation API ermöglicht es einer Webseite, den Browser nach dem Standort des Geräts zu fragen. Mit der Erlaubnis des Nutzers erhält man Koordinaten (Breiten- und Längengrad), die man verwenden kann, um Ergebnisse in der Nähe anzuzeigen, eine Karte zu zentrieren oder Inhalte mit einem Standort zu versehen. Dieser Leitfaden behandelt die gesamte API: Support prüfen, die aktuelle Position einmalig auslesen, Positionsänderungen im Zeitverlauf beobachten, die Optionen zur Steuerung von Genauigkeit und Timing sowie den korrekten Umgang mit Fehlern und Berechtigungen.

Einführung in die Geolocation API

Die Geolocation API ist Teil der Browserumgebung (das navigator-Objekt), nicht der JavaScript-Sprache selbst. Wenn Sie neu in der Unterscheidung zwischen Sprachfunktionen und vom Browser bereitgestellten APIs sind, lesen Sie das Kapitel Browserumgebung, Spezifikationen als Einstieg.

Die API stellt drei Methoden auf navigator.geolocation bereit:

getCurrentPosition() — Position einmalig abrufen.
watchPosition() — Position wiederholt abrufen, wenn sich das Gerät bewegt.
clearWatch() — ein watchPosition()-Abonnement beenden.

Zwei Voraussetzungen, die nicht übersprungen werden dürfen

Sicherer Kontext. Browser stellen Geolocation nur auf Seiten bereit, die über HTTPS ausgeliefert werden (oder über localhost bei der Entwicklung). Auf einer normalen http://-Seite fehlt navigator.geolocation möglicherweise, oder jeder Aufruf schlägt fehl. Dies ist eine Datenschutz- und Sicherheitsmaßnahme.
Nutzerberechtigung. Der Browser zeigt beim ersten Standortabruf einer Seite eine Aufforderung an. Es passiert nichts, bis der Nutzer auf Zulassen klickt. Wenn er Blockieren wählt, wird Ihr Fehler-Callback mit dem Code PERMISSION_DENIED aufgerufen.

Verfügbarkeit der API prüfen

Führen Sie immer eine Feature-Erkennung durch, bevor Sie die API verwenden, da ältere Browser und unsichere Seiten sie möglicherweise nicht bereitstellen.

javascript— editable

Aktuelle Position abrufen

Um den Standort des Geräts einmalig abzurufen, rufen Sie getCurrentPosition(success, error, options) auf. Nur das erste Argument ist erforderlich.

const options = {
  // Ask for the highest-accuracy position available (e.g. GPS on mobile).
  enableHighAccuracy: true,
  // Give up after 5 seconds if no position is returned.
  timeout: 5000,
  // Never use a cached position; always fetch a fresh one.
  maximumAge: 0
};

function success(position) {
  const { latitude, longitude, accuracy } = position.coords;
  console.log(`Latitude: ${latitude}, Longitude: ${longitude}`);
  console.log(`Accurate to within ${accuracy} meters`);
}

function error(err) {
  console.error(`Error (${err.code}): ${err.message}`);
}

navigator.geolocation.getCurrentPosition(success, error, options);

Das Position-Objekt

Der Erfolgs-Callback erhält ein GeolocationPosition-Objekt mit zwei Feldern:

position.timestamp — Zeitpunkt der Messung (Millisekunden seit dem Epoch).
position.coords — ein GeolocationCoordinates-Objekt mit folgenden Eigenschaften:

Eigenschaft	Beschreibung
`latitude`	Grad Nord/Süd (dezimal).
`longitude`	Grad Ost/West (dezimal).
`accuracy`	Genauigkeit von `latitude`/`longitude` in Metern.
`altitude`	Höhe in Metern über dem Meeresspiegel (oder `null`).
`altitudeAccuracy`	Genauigkeit von `altitude` in Metern (oder `null`).
`heading`	Bewegungsrichtung in Grad im Uhrzeigersinn von Norden (oder `null`).
`speed`	Bodengeschwindigkeit in Metern pro Sekunde (oder `null`).

Die Felder heading und speed werden in der Regel nur auf Geräten befüllt, die sich tatsächlich bewegen und über die entsprechenden Sensoren verfügen.

Das Options-Objekt

Alle drei Optionen sind optional. Wählen Sie sie entsprechend Ihrem Anwendungsfall:

Option	Standard	Funktion
`enableHighAccuracy`	`false`	Bei `true` wird die präziseste Quelle angefordert (GPS). Langsamer und verbraucht mehr Akku.
`timeout`	`Infinity`	Maximale Wartezeit in Millisekunden, bevor der Fehler-Callback mit `TIMEOUT` aufgerufen wird.
`maximumAge`	`0`	Maximales Alter (in ms) einer gecachten Position, bevor eine neue abgerufen werden muss. Ein größerer Wert ermöglicht die Wiederverwendung einer aktuellen Messung für schnellere Antworten.

Ein häufiger Kompromiss: enableHighAccuracy: false und einen Wert ungleich null für maximumAge setzen, wenn ein ungefähres, schnelles Ergebnis ausreicht (z. B. „Geschäfte in meiner Nähe"); enableHighAccuracy: true mit maximumAge: 0 für eine Schritt-für-Schritt-Navigation verwenden.

Fehlerbehandlung

Wenn eine Anfrage fehlschlägt, erhält der Fehler-Callback einen GeolocationPositionError. Dessen code-Eigenschaft zeigt genau an, was schiefgelaufen ist:

function error(err) {
  switch (err.code) {
    case err.PERMISSION_DENIED:      // 1
      console.error("User denied the request for location.");
      break;
    case err.POSITION_UNAVAILABLE:   // 2
      console.error("Location information is unavailable.");
      break;
    case err.TIMEOUT:                // 3
      console.error("The request to get location timed out.");
      break;
    default:
      console.error(`An unknown error occurred: ${err.message}`);
  }
}

PERMISSION_DENIED (1) — der Nutzer hat den Standortzugriff blockiert, oder die Seite ist kein sicherer Kontext.
POSITION_UNAVAILABLE (2) — das Gerät konnte seinen Standort nicht ermitteln (kein GPS-/WLAN-Signal usw.).
TIMEOUT (3) — innerhalb des festgelegten timeout wurde keine Position ermittelt.

Berechtigung im Voraus prüfen

Sie können die Geolocation-Berechtigung prüfen, ohne eine Aufforderung auszulösen, indem Sie die Permissions API verwenden. Dies ist nützlich, um die Benutzeroberfläche anzupassen (zum Beispiel, um die Schaltfläche „Standort finden" auszublenden, wenn der Zugriff bereits blockiert ist).

navigator.permissions.query({ name: "geolocation" }).then((result) => {
  // result.state is "granted", "prompt", or "denied"
  console.log(`Geolocation permission: ${result.state}`);
});

Kontinuierliche Positionsüberwachung

Für die Echtzeit-Verfolgung ruft watchPosition() Ihren Erfolgs-Callback jedes Mal auf, wenn sich die Position des Geräts ändert. Die Methode gibt eine numerische Watch-ID zurück, die Sie an clearWatch() übergeben, um die Verfolgung zu beenden — wird sie nicht aufgerufen, bleibt der Standort aktiv und entleert den Akku.

const watchID = navigator.geolocation.watchPosition(success, error, options);
// success() now fires every time the position updates.

// Later, when tracking is no longer needed:
navigator.geolocation.clearWatch(watchID);

Wenn Ihr Tracking davon abhängt, dass der Bildschirm zwischen Hoch- und Querformat wechselt, passt die Screen Orientation API gut zur Geolocation in Karten-Apps.

Ein vollständiges Beispiel: Standort auf einer Karte anzeigen

Dieses Beispiel verwendet die Geolocation API, um Ihre Koordinaten abzurufen, und die Bibliothek Leaflet.js, um sie auf einer OpenStreetMap-Ebene darzustellen.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Your Location on a Map</title>
    <link
      rel="stylesheet"
      href="https://unpkg.com/[email protected]/dist/leaflet.css"
    />
  </head>
  <body>
    <h1>Your Location on a Map</h1>
    <div id="map" style="height: 400px"></div>
    <script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
    <script>
      document.addEventListener("DOMContentLoaded", function () {
        if (navigator.geolocation) {
          navigator.geolocation.getCurrentPosition(function (position) {
            const lat = position.coords.latitude;
            const lon = position.coords.longitude;

            const map = L.map("map").setView([lat, lon], 13);
            L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", {
              maxZoom: 19,
              attribution: "© OpenStreetMap contributors",
            }).addTo(map);

            L.marker([lat, lon])
              .addTo(map)
              .bindPopup("You are here!")
              .openPopup();
          });
        } else {
          document.getElementById("map").textContent =
            "Geolocation is not supported by your browser.";
        }
      });
    </script>
  </body>
</html>

Probier es selbst »

Wenn Sie die Seite laden, wird sofort Ihr Standort abgerufen und anschließend ein Marker mit einem Popup „You are here!" an Ihrer Position auf der Karte angezeigt. Diese visuelle Darstellung hilft zu verstehen, wie Webseiten mit geografischen Daten interagieren können, um die Nutzererfahrung zu verbessern.

Best Practices

Immer Feature-Erkennung verwenden und über HTTPS ausliefern, sonst schlägt jeder Aufruf fehl.
Standort nur dann anfordern, wenn der Nutzer es erwartet — zum Beispiel nach dem Klick auf eine Schaltfläche „Standort finden" — damit die Berechtigungsanfrage einen klaren Kontext hat.
Jeden Fehlercode behandeln und eine hilfreiche Alternative anbieten (z. B. eine manuelle Standortsuche), wenn die Berechtigung verweigert wurde.
clearWatch() aufrufen, sobald keine kontinuierlichen Updates mehr benötigt werden, um den Akku zu schonen.
Optionen bewusst wählen: hohe Genauigkeit für die Navigation, ein Wert ungleich null für maximumAge bei schnellen „In meiner Nähe"-Abfragen.

Fazit

Die Geolocation API bietet Web-Apps eine datenschutzbewusste Möglichkeit, den Standort des Nutzers über drei Methoden auszulesen: getCurrentPosition() für eine einmalige Messung, watchPosition() für Live-Tracking und clearWatch() zum Beenden. Kombiniert mit durchdachten Optionen und einer korrekten Fehlerbehandlung ermöglicht sie Karten, lokale Suche und andere standortbasierte Funktionen. Für weitere verwandte Browser-APIs empfehlen sich die Screen Orientation API und das Kapitel Browserumgebung, Spezifikationen.

Übungen

Übung

Was sind die wesentlichen Funktionen der JavaScript Geolocation API?

Sie ermöglicht Echtzeit-Video-Streaming.Sie fordert die Zustimmung des Nutzers an, bevor auf Standortdaten zugegriffen wird.Sie liefert bei Anfrage hochgenaue Standortdaten.Sie ruft den Standort automatisch ohne Nutzerberechtigung ab.Sie kann die Position des Geräts in Echtzeit kontinuierlich überwachen.