GeolocationPositionError.code — Eigenschaft · JavaScript-Referenz

Signatur

GeolocationPositionError.code

Beschreibung

Die Eigenschaft code eines GeolocationPositionError-Objekts gibt an, warum navigator.geolocation.getCurrentPosition() oder watchPosition() keine Position liefern konnte. Das Fehlerobjekt wird als einziges Argument an den Fehler-Callback übergeben.

Mögliche Werte (auch als statische Konstanten auf GeolocationPositionError verfügbar):

1 – PERMISSION_DENIED: Der Nutzer oder eine Richtlinie (z. B. Permissions-Policy, unsicherer Kontext) hat den Zugriff verweigert.
2 – POSITION_UNAVAILABLE: Die Position konnte nicht ermittelt werden, etwa weil keine Ortungsquelle (GPS, WLAN, Netzwerk) verfügbar ist.
3 – TIMEOUT: Die in options.timeout festgelegte Zeit ist abgelaufen, bevor eine Position vorlag.

Verwende code für die Programmlogik (z. B. Rückfall auf manuelle Ortseingabe, erneuter Versuch mit längerem Timeout) und nicht die Eigenschaft message, deren Text je nach Browser unterschiedlich und nur zur Fehlersuche gedacht ist.

Rückgabewert

Typ

number

Beschreibung

Ganzzahl 1, 2 oder 3 (entspricht PERMISSION_DENIED, POSITION_UNAVAILABLE bzw. TIMEOUT). Schreibgeschützt.

Beispiele

Fehlercode auswerten und passende Meldung anzeigen

const onSuccess = (pos) => {
  const { latitude, longitude } = pos.coords;
  console.log(`Position: ${latitude}, ${longitude}`);
};

const onError = (err) => {
  switch (err.code) {
    case GeolocationPositionError.PERMISSION_DENIED:
      console.warn('Standortzugriff wurde verweigert.');
      break;
    case GeolocationPositionError.POSITION_UNAVAILABLE:
      console.warn('Standort derzeit nicht ermittelbar.');
      break;
    case GeolocationPositionError.TIMEOUT:
      console.warn('Zeitüberschreitung bei der Standortabfrage.');
      break;
  }
};

navigator.geolocation.getCurrentPosition(onSuccess, onError, { timeout: 5000 });

Standortzugriff wurde verweigert. // z. B. nach Klick auf „Blockieren“

Promise-Wrapper mit Wiederholung bei Timeout

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

const locate = async () => {
  try {
    return await getPosition({ timeout: 3000 });
  } catch (err) {
    if (err.code === 3) {
      // Zweiter Versuch: länger warten, zwischengespeicherte Position erlauben
      return getPosition({ timeout: 15000, maximumAge: 60000 });
    }
    throw err; // 1 oder 2 weiterreichen
  }
};

locate()
  .then((pos) => console.log('Genauigkeit:', pos.coords.accuracy, 'm'))
  .catch((err) => console.error(`Fehler ${err.code}: ${err.message}`));

Genauigkeit: 25 m

Fehlercode in lesbaren Namen übersetzen (z. B. für Logging)

const codeNames = {
  1: 'PERMISSION_DENIED',
  2: 'POSITION_UNAVAILABLE',
  3: 'TIMEOUT',
};

const id = navigator.geolocation.watchPosition(
  (pos) => console.log(pos.coords.latitude, pos.coords.longitude),
  (err) => {
    console.log('Geolocation-Fehler:', codeNames[err.code] ?? err.code);
    if (err.code === err.PERMISSION_DENIED) {
      navigator.geolocation.clearWatch(id);
    }
  }
);

Geolocation-Fehler: POSITION_UNAVAILABLE

// Wichtig · Fallstricke

Nur sichere Kontexte: Die Geolocation-API funktioniert nur über HTTPS (oder localhost). Auf HTTP-Seiten kommt meist sofort code === 1 zurück, obwohl der Nutzer nie gefragt wurde.
iframes: Fehlt in einem eingebetteten Frame allow="geolocation", ist das Ergebnis ebenfalls PERMISSION_DENIED.
Kein Timeout voreingestellt: Der Standardwert von timeout ist Infinity. Ohne eigenen Wert wird code 3 also nie ausgelöst, und die Abfrage kann ewig hängen.
Kein Fehler-Callback, kein Fehler: Ohne zweiten Callback werden Fehler einfach verschluckt.
Vergleiche lieber mit den Konstanten (GeolocationPositionError.TIMEOUT oder err.TIMEOUT) als mit festen Zahlen, dann liest sich der Code besser. message ist nicht einheitlich und sollte nicht für Logik verwendet werden.
Der Name GeolocationPositionError ersetzt das ältere PositionError. In sehr alten Browsern gibt es den globalen Konstruktor unter dem neuen Namen eventuell nicht. Die Eigenschaft err.code selbst wird aber überall unterstützt.
Wenn der Nutzer eine Berechtigung einmal abgelehnt hat, fragt der Browser meist nicht erneut. Den aktuellen Stand kannst du vorab mit navigator.permissions.query({ name: 'geolocation' }) prüfen.

Siehe auch

GeolocationPositionError GeolocationPositionError.message Geolocation.getCurrentPosition() Geolocation.watchPosition() Geolocation.clearWatch() Permissions.query() WorkerLocation.hostname