Geolocation.watchPosition() — Methode · JavaScript-Referenz

Signatur

Geolocation.prototype.watchPosition(success, error, options)

Beschreibung

navigator.geolocation.watchPosition() überwacht die Position des Geräts laufend. Anders als getCurrentPosition(), das die Position nur einmal abfragt, ruft watchPosition() den Erfolgs-Callback so lange auf, bis Sie die Überwachung mit clearWatch() beenden. Das erste Mal geschieht das, sobald eine Position vorliegt, danach bei jeder erkannten Änderung.

Typische Einsatzfälle sind Navigations- und Tracking-Anwendungen, Lauf- und Fahrrad-Apps, Karten mit „Mein Standort“-Markierung oder ortsbezogene Hinweise. Die Methode gibt sofort eine ganzzahlige ID zurück. Die eigentlichen Positionsdaten kommen asynchron über den Callback als GeolocationPosition-Objekt mit coords (Breitengrad, Längengrad, Genauigkeit, Höhe, Geschwindigkeit, Richtung) und timestamp.

Beim ersten Aufruf fragt der Browser die Nutzerin oder den Nutzer um Erlaubnis. Lehnt die Person ab, wird der Fehler-Callback mit code === 1 (PERMISSION_DENIED) aufgerufen. Über options steuern Sie, wie genau die Position sein soll (enableHighAccuracy), wie lange auf eine Position gewartet wird (timeout) und wie alt ein zwischengespeicherter Wert höchstens sein darf (maximumAge).

Parameter

Name	Typ	Default	Beschreibung
$success Pflicht	(position: GeolocationPosition) => void		Callback, der mit einem `GeolocationPosition`-Objekt aufgerufen wird: zuerst mit der Startposition, danach bei jeder Positionsänderung.
$error	(error: GeolocationPositionError) => void \| null	null	Callback für Fehler. `error.code` ist `1` (PERMISSION_DENIED), `2` (POSITION_UNAVAILABLE) oder `3` (TIMEOUT). `error.message` enthält eine Beschreibung des Fehlers.
$options	{ enableHighAccuracy?: boolean, timeout?: number, maximumAge?: number }	{ enableHighAccuracy: false, timeout: Infinity, maximumAge: 0 }	`enableHighAccuracy`: möglichst genaue Position anfordern, z. B. per GPS (braucht mehr Akku). `timeout`: maximale Wartezeit in ms pro Positionsabfrage. `maximumAge`: maximales Alter einer zwischengespeicherten Position in ms.

Rückgabewert

Typ

number

Beschreibung

Eine ganzzahlige Watch-ID, die diese Überwachung eindeutig kennzeichnet. Übergeben Sie sie an navigator.geolocation.clearWatch(id), um die Überwachung zu beenden.

Beispiele

Position laufend überwachen und wieder beenden

if (!('geolocation' in navigator)) {
  console.log('Geolocation wird nicht unterstützt');
} else {
  const watchId = navigator.geolocation.watchPosition(
    ({ coords, timestamp }) => {
      console.log(`Lat ${coords.latitude.toFixed(5)}, Lng ${coords.longitude.toFixed(5)} (±${Math.round(coords.accuracy)} m) um ${new Date(timestamp).toLocaleTimeString()}`);
    },
    (err) => console.error(`Fehler ${err.code}: ${err.message}`),
    { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 }
  );

  // Nach 60 Sekunden die Überwachung stoppen
  setTimeout(() => {
    navigator.geolocation.clearWatch(watchId);
    console.log('Überwachung beendet');
  }, 60_000);
}

Lat 52.52001, Lng 13.40495 (±12 m) um 14:03:21 … Überwachung beendet

Zurückgelegte Strecke messen (Lauf-Tracker)

const toRad = (deg) => (deg * Math.PI) / 180;

// Haversine-Formel: Entfernung in Metern
const distance = (a, b) => {
  const R = 6371e3;
  const dLat = toRad(b.latitude - a.latitude);
  const dLng = toRad(b.longitude - a.longitude);
  const h = Math.sin(dLat / 2) ** 2 +
    Math.cos(toRad(a.latitude)) * Math.cos(toRad(b.latitude)) * Math.sin(dLng / 2) ** 2;
  return 2 * R * Math.asin(Math.sqrt(h));
};

let last = null;
let total = 0;

const id = navigator.geolocation.watchPosition(
  ({ coords }) => {
    // Ungenaue Messwerte ignorieren
    if (coords.accuracy > 30) return;
    if (last) total += distance(last, coords);
    last = coords;
    console.log(`Strecke: ${(total / 1000).toFixed(2)} km`);
  },
  (err) => console.warn(err.message),
  { enableHighAccuracy: true }
);

document.querySelector('#stop')?.addEventListener('click', () => {
  navigator.geolocation.clearWatch(id);
});

Strecke: 0.00 km Strecke: 0.03 km Strecke: 0.07 km

Fehler gezielt behandeln und in ein Promise-freundliches Muster packen

const watchLocation = (onUpdate, options = {}) => {
  const messages = {
    1: 'Standortzugriff wurde verweigert.',
    2: 'Position nicht verfügbar.',
    3: 'Zeitüberschreitung bei der Standortabfrage.'
  };
  const id = navigator.geolocation.watchPosition(
    onUpdate,
    (err) => console.error(messages[err.code] ?? err.message),
    { timeout: 15000, maximumAge: 5000, ...options }
  );
  // Rückgabe: Funktion zum Aufräumen (z. B. in React useEffect)
  return () => navigator.geolocation.clearWatch(id);
};

const stop = watchLocation((pos) => console.log(pos.coords.latitude, pos.coords.longitude));
// später: stop();

52.52001 13.40495

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Die Methode funktioniert nur über HTTPS (oder localhost). Auf HTTP-Seiten schlägt sie mit PERMISSION_DENIED fehl. In iframes muss die Permissions Policy geolocation erlaubt sein (<iframe allow="geolocation">).
Immer aufräumen: Beenden Sie die Überwachung mit clearWatch(id), sobald sie nicht mehr gebraucht wird, z. B. beim Verlassen einer Ansicht. Sonst verbraucht das Gerät weiter Akku, vor allem mit enableHighAccuracy: true.
Häufigkeit der Aufrufe: Der Callback kann sehr oft oder mit fast gleichen Koordinaten aufgerufen werden. Filtern Sie Werte über coords.accuracy oder einen Mindestabstand und drosseln Sie teure Aktualisierungen der Oberfläche.
Standardwert von timeout: Er ist Infinity. Ohne eigenen Wert wird der Fehler-Callback bei ausbleibender Position also nie aufgerufen.
Hintergrund: Mobile Browser pausieren die Überwachung meist, wenn der Tab im Hintergrund oder der Bildschirm gesperrt ist. Für echtes Hintergrund-Tracking brauchen Sie eine native App.
Datenschutz: Standortdaten sind personenbezogene Daten. Fragen Sie den Standort erst nach einer Aktion der Nutzerin oder des Nutzers ab, etwa einem Klick, und nicht direkt beim Laden der Seite. Den aktuellen Berechtigungsstatus können Sie vorab mit navigator.permissions.query({ name: 'geolocation' }) abfragen.

Siehe auch

Geolocation Geolocation.getCurrentPosition() Geolocation.clearWatch() GeolocationPosition GeolocationCoordinates GeolocationPositionError Permissions.query()