Geolocation — Schnittstelle · JavaScript-Referenz

Signatur

interface Geolocation

Beschreibung

Die Schnittstelle Geolocation ist der Einstieg in die Geolocation-API. Es gibt kein eigenes Konstruktor-Objekt: Die einzige Instanz erreichen Sie über navigator.geolocation. Der Browser ermittelt die Position je nach Gerät über GPS, WLAN, Mobilfunkzellen oder die IP-Adresse und gibt sie als GeolocationPosition mit einem coords-Objekt (Breite, Länge, Genauigkeit, Höhe, Geschwindigkeit usw.) zurück.

Die Schnittstelle hat drei Methoden:

getCurrentPosition(success, error?, options?): fragt die aktuelle Position genau einmal ab.
watchPosition(success, error?, options?): ruft den Callback bei jeder Positionsänderung erneut auf und gibt eine numerische Watch-ID zurück.
clearWatch(id): beendet eine Überwachung, die mit watchPosition() gestartet wurde.

Die API arbeitet ausschließlich mit Callbacks und nicht mit Promises. Beim ersten Zugriff fragt der Browser den Nutzer um Erlaubnis. Lehnt er ab, wird der Fehler-Callback mit einem GeolocationPositionError (Code 1 = PERMISSION_DENIED) aufgerufen. Typische Einsatzgebiete sind Kartenanwendungen, Filial- oder Umkreissuche, Lauf- und Tracking-Apps sowie ortsbezogene Inhalte.

Über das options-Objekt steuern Sie Genauigkeit (enableHighAccuracy), maximale Wartezeit (timeout) und das erlaubte Alter einer zwischengespeicherten Position (maximumAge). Hohe Genauigkeit liefert meist bessere Werte, braucht aber mehr Zeit und mehr Akku.

Parameter

Name	Typ	Default	Beschreibung
$successCallback Pflicht	(position: GeolocationPosition) => void		Wird mit einem `GeolocationPosition`-Objekt aufgerufen, das `coords` und `timestamp` enthält. Gilt für `getCurrentPosition()` und `watchPosition()`.
$errorCallback	(error: GeolocationPositionError) => void	null	Wird im Fehlerfall aufgerufen. `error.code`: `1` PERMISSION_DENIED, `2` POSITION_UNAVAILABLE, `3` TIMEOUT.
$options.enableHighAccuracy	boolean	false	Fordert eine möglichst genaue Position an, etwa per GPS. Das dauert länger und verbraucht mehr Energie.
$options.timeout	number	Infinity	Maximale Wartezeit in Millisekunden, bis eine Position vorliegen muss. Danach kommt der Fehler `TIMEOUT`.
$options.maximumAge	number	0	Maximales Alter einer zwischengespeicherten Position in Millisekunden. Bei `0` wird immer eine neue Position ermittelt.
$id Pflicht	number		Nur bei `clearWatch()`: die Watch-ID, die `watchPosition()` zurückgegeben hat.

Beispiele

Aktuelle Position einmalig abfragen

if ('geolocation' in navigator) {
  navigator.geolocation.getCurrentPosition(
    (pos) => {
      const { latitude, longitude, accuracy } = pos.coords;
      console.log(`Position: ${latitude.toFixed(5)}, ${longitude.toFixed(5)} (±${Math.round(accuracy)} m)`);
    },
    (err) => console.error(`Fehler ${err.code}: ${err.message}`),
    { enableHighAccuracy: true, timeout: 10000, maximumAge: 60000 }
  );
} else {
  console.warn('Geolocation wird nicht unterstützt.');
}

Position: 52.52001, 13.40495 (±25 m)

Callback-API in ein Promise einpacken (async/await)

const getPosition = (options = {}) =>
  new Promise((resolve, reject) =>
    navigator.geolocation.getCurrentPosition(resolve, reject, options)
  );

const zeigeStandort = async () => {
  try {
    const { coords } = await getPosition({ timeout: 8000 });
    const url = `https://www.openstreetmap.org/?mlat=${coords.latitude}&mlon=${coords.longitude}#map=16/${coords.latitude}/${coords.longitude}`;
    console.log('Karte:', url);
  } catch (err) {
    const gruende = { 1: 'Zugriff verweigert', 2: 'Position nicht verfügbar', 3: 'Zeitüberschreitung' };
    console.error(gruende[err.code] ?? err.message);
  }
};

zeigeStandort();

Karte: https://www.openstreetmap.org/?mlat=52.52&mlon=13.405#map=16/52.52/13.405

Position fortlaufend verfolgen und wieder beenden

const strecke = [];

const watchId = navigator.geolocation.watchPosition(
  ({ coords, timestamp }) => {
    strecke.push({ lat: coords.latitude, lon: coords.longitude, zeit: timestamp });
    console.log(`Punkt ${strecke.length}: ${coords.latitude}, ${coords.longitude}`);
  },
  (err) => console.error('Tracking-Fehler:', err.message),
  { enableHighAccuracy: true, maximumAge: 0 }
);

// Tracking nach 5 Minuten stoppen
setTimeout(() => {
  navigator.geolocation.clearWatch(watchId);
  console.log(`Tracking beendet, ${strecke.length} Punkte erfasst.`);
}, 5 * 60 * 1000);

Punkt 1: 52.52001, 13.40495 Punkt 2: 52.52010, 13.40512 … Tracking beendet, 42 Punkte erfasst.

Berechtigungsstatus vorab prüfen

const status = await navigator.permissions.query({ name: 'geolocation' });
console.log('Status:', status.state); // 'granted' | 'prompt' | 'denied'

status.addEventListener('change', () => {
  console.log('Neuer Status:', status.state);
});

Status: prompt

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Die API funktioniert nur über HTTPS (oder localhost). Auf HTTP-Seiten schlägt der Aufruf mit PERMISSION_DENIED fehl.
Nutzerabsicht: Fragen Sie die Position erst nach einer Nutzeraktion ab, z. B. nach einem Klick auf „Standort verwenden“. Fragt die Seite direkt beim Laden, lehnen Nutzer häufig ab, und manche Browser unterdrücken die Abfrage dann.
Timeout setzen: Der Standardwert timeout: Infinity kann dazu führen, dass keiner der beiden Callbacks jemals aufgerufen wird. Geben Sie deshalb immer einen sinnvollen Timeout an.
iframes: In Cross-Origin-iframes ist Geolocation nur erlaubt, wenn der Einbettende das per allow="geolocation" freigibt (Permissions Policy).
Genauigkeit: Auf Desktop-Rechnern ohne GPS basiert die Position oft auf WLAN oder IP-Adresse und kann mehrere Kilometer abweichen. Werten Sie deshalb immer coords.accuracy aus.
Akku und Aufräumen: watchPosition() mit enableHighAccuracy verbraucht viel Energie. Beenden Sie die Überwachung mit clearWatch(), sobald sie nicht mehr gebraucht wird, z. B. beim Verlassen der Ansicht.
Datenschutz: Standortdaten sind personenbezogene Daten im Sinne der DSGVO. Übertragen oder speichern Sie sie nur mit Zweckbindung und Einwilligung.
Kompatibilität: Alle aktuellen Browser unterstützen die API. In Node.js gibt es sie nicht. Web Worker haben keinen Zugriff auf navigator.geolocation.

Siehe auch

Location Selection WorkerLocation Animation Navigation PushSubscription