GeolocationPosition — Schnittstelle · JavaScript-Referenz

Signatur

interface GeolocationPosition

Beschreibung

Ein GeolocationPosition-Objekt erhalten Sie immer als Argument des Erfolgs-Callbacks von navigator.geolocation.getCurrentPosition() und navigator.geolocation.watchPosition(). Selbst erzeugen können Sie es nicht, denn einen öffentlichen Konstruktor gibt es nicht. Das Objekt ist schreibgeschützt und hält einen einzelnen Messpunkt fest.

Es hat zwei Eigenschaften:

coords: ein GeolocationCoordinates-Objekt mit latitude, longitude, accuracy (in Metern) und den optionalen Werten altitude, altitudeAccuracy, heading und speed. Die optionalen Werte können null sein.
timestamp: ein EPOCHTIMESTAMP, also Millisekunden seit dem 1.1.1970 UTC. Er gibt an, wann die Position ermittelt wurde.

Außerdem gibt es die Methode toJSON(), die in neueren Browsern verfügbar ist. Sie liefert eine serialisierbare Kopie des Objekts. Das ist praktisch, wenn Sie die Position per fetch an einen Server schicken oder in localStorage speichern wollen. Ohne toJSON() ergibt JSON.stringify(position) nur {}, weil die Eigenschaften Getter am Prototyp sind.

Rückgabewert

Typ

GeolocationPosition

Beschreibung

Wird als Argument an den Erfolgs-Callback der Geolocation-API übergeben. Enthält coords (GeolocationCoordinates) und timestamp (number).

Beispiele

Aktuelle Position einmalig abfragen

if (!('geolocation' in navigator)) {
  console.log('Geolocation wird nicht unterstützt');
} else {
  navigator.geolocation.getCurrentPosition(
    (position) => {
      // position ist ein GeolocationPosition-Objekt
      const { latitude, longitude, accuracy } = position.coords;
      console.log(position instanceof GeolocationPosition);
      console.log(`Breite: ${latitude.toFixed(5)}, Länge: ${longitude.toFixed(5)}`);
      console.log(`Genauigkeit: ±${Math.round(accuracy)} m`);
      console.log('Gemessen am:', new Date(position.timestamp).toLocaleString('de-DE'));
    },
    (error) => console.error(`Fehler ${error.code}: ${error.message}`),
    { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 }
  );
}

true Breite: 52.52001, Länge: 13.40495 Genauigkeit: ±15 m Gemessen am: 14.3.2024, 10:42:17

Als Promise kapseln und mit async/await nutzen

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

const zeigeStandort = async () => {
  try {
    const position = await getPosition({ timeout: 8000 });
    const { latitude, longitude } = position.coords;
    const url = `https://www.openstreetmap.org/?mlat=${latitude}&mlon=${longitude}#map=16/${latitude}/${longitude}`;
    console.log('Karte:', url);
  } catch (err) {
    console.warn('Standort nicht verfügbar:', err.message);
  }
};

zeigeStandort();

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

Bewegung verfolgen und optionale Werte prüfen

const watchId = navigator.geolocation.watchPosition(
  (position) => {
    const { speed, heading, altitude } = position.coords;
    // Optionale Werte können null sein
    const kmh = speed !== null ? (speed * 3.6).toFixed(1) : 'unbekannt';
    console.log(`Tempo: ${kmh} km/h, Richtung: ${heading ?? '–'}°, Höhe: ${altitude ?? '–'} m`);
  },
  (error) => console.error(error.message),
  { enableHighAccuracy: true }
);

// Nach 60 Sekunden aufhören, Akku sparen
setTimeout(() => navigator.geolocation.clearWatch(watchId), 60000);

Tempo: 18.4 km/h, Richtung: 270°, Höhe: 34 m

Position serialisieren und an den Server senden

navigator.geolocation.getCurrentPosition(async (position) => {
  // toJSON() gibt es in neueren Browsern; sonst von Hand übernehmen
  const data = typeof position.toJSON === 'function'
    ? position.toJSON()
    : {
        timestamp: position.timestamp,
        coords: {
          latitude: position.coords.latitude,
          longitude: position.coords.longitude,
          accuracy: position.coords.accuracy
        }
      };

  console.log(JSON.stringify(data.coords.latitude));
  await fetch('/api/standort', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });
});

52.52001

// Wichtig · Fallstricke

Nur in sicherem Kontext: Die Geolocation-API funktioniert nur über HTTPS (oder localhost). Außerdem muss der Nutzer die Berechtigung erteilen. Lehnt er ab, wird der Fehler-Callback mit GeolocationPositionError.PERMISSION_DENIED (Code 1) aufgerufen. In iframes brauchen Sie zusätzlich allow="geolocation" (Permissions-Policy).
Serialisierung: Ohne toJSON(), das in älteren Browsern fehlt, liefert JSON.stringify(position) nur {}. Kopieren Sie die Werte in diesem Fall von Hand.
Genauigkeit prüfen: coords.accuracy kann bei Ortung per WLAN oder IP mehrere Kilometer betragen. Werten Sie diesen Wert aus, bevor Sie die Position für präzise Zwecke nutzen.
Optionale Werte: altitude, altitudeAccuracy, heading und speed sind auf Desktop-Geräten fast immer null. heading ist auch dann NaN, wenn speed gleich 0 ist.
Zwischengespeicherte Positionen: Mit maximumAge > 0 kann eine ältere Position zurückkommen. Prüfen Sie timestamp, wenn es auf Aktualität ankommt.
Datenschutz: Standortdaten sind personenbezogen (DSGVO). Übertragen und speichern Sie sie nur mit Zweckbindung und Einwilligung.
Früher hieß das Interface Position. Ältere Browser kennen GeolocationPosition daher nicht als globalen Namen, und eine Prüfung mit instanceof GeolocationPosition würde dort fehlschlagen.

Siehe auch

Geolocation Navigator.geolocation GeolocationPositionError CaretPosition GeolocationCoordinates