GeolocationPosition.coords — Eigenschaft · JavaScript-Referenz

Signatur

GeolocationPosition.coords

Beschreibung

Die Eigenschaft coords eines GeolocationPosition-Objekts enthält die eigentlichen Positionsdaten, die die Geolocation-API ermittelt hat. Sie ist schreibgeschützt und gibt ein GeolocationCoordinates-Objekt zurück.

Ein GeolocationPosition-Objekt erzeugt man nicht selbst. Der Browser übergibt es an den Erfolgs-Callback von navigator.geolocation.getCurrentPosition() oder navigator.geolocation.watchPosition(). Neben coords hat die Position noch die Eigenschaft timestamp, also den Zeitpunkt der Messung.

Das GeolocationCoordinates-Objekt enthält diese Werte:

latitude und longitude: Breiten- und Längengrad in Dezimalgrad (WGS 84)
accuracy: Genauigkeit in Metern (95 % Konfidenz)
altitude und altitudeAccuracy: Höhe und deren Genauigkeit in Metern, oft null
heading: Bewegungsrichtung in Grad, im Uhrzeigersinn ab geografisch Nord, oft null oder NaN
speed: Geschwindigkeit in m/s, oft null

Mit coords arbeitet man in Karten-Anwendungen, bei der Umkreissuche, beim Aufzeichnen von Strecken oder beim Vorausfüllen von Standortfeldern.

Rückgabewert

Typ

GeolocationCoordinates

Beschreibung

Ein schreibgeschütztes Objekt mit den Eigenschaften latitude, longitude, accuracy, altitude, altitudeAccuracy, heading und speed. Ab neueren Browserversionen gibt es außerdem die Methode toJSON().

Beispiele

Aktuelle Position einmalig abfragen

navigator.geolocation.getCurrentPosition(
  (position) => {
    const { latitude, longitude, accuracy } = position.coords;
    console.log(`Breite: ${latitude.toFixed(5)}, Länge: ${longitude.toFixed(5)}`);
    console.log(`Genauigkeit: ±${Math.round(accuracy)} m`);
  },
  (error) => console.error(`Fehler ${error.code}: ${error.message}`),
  { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 }
);

Breite: 52.52001, Länge: 13.40495 Genauigkeit: ±18 m

Position als Promise mit async/await

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

const showLocation = 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) {
    console.warn('Standort nicht verfügbar:', err.message);
  }
};

showLocation();

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

Bewegung verfolgen: Geschwindigkeit und Richtung

const watchId = navigator.geolocation.watchPosition(
  ({ coords, timestamp }) => {
    // speed/heading sind oft null – daher absichern
    const kmh = coords.speed != null ? (coords.speed * 3.6).toFixed(1) : '–';
    const heading = Number.isFinite(coords.heading) ? `${Math.round(coords.heading)}°` : '–';
    console.log(`${new Date(timestamp).toLocaleTimeString('de-DE')}: ${kmh} km/h, Richtung ${heading}`);
  },
  (error) => console.error(error.message),
  { enableHighAccuracy: true }
);

// Nach 60 Sekunden beenden
setTimeout(() => navigator.geolocation.clearWatch(watchId), 60000);

14:32:05: 4.7 km/h, Richtung 87°

Koordinaten serialisieren und speichern

navigator.geolocation.getCurrentPosition(({ coords }) => {
  // Eigenschaften liegen auf dem Prototyp – JSON.stringify(coords) ergab früher '{}'
  const data = {
    lat: coords.latitude,
    lng: coords.longitude,
    accuracy: coords.accuracy,
  };
  localStorage.setItem('lastLocation', JSON.stringify(data));
  console.log(localStorage.getItem('lastLocation'));
});

{"lat":52.52001,"lng":13.40495,"accuracy":18}

// Wichtig · Fallstricke

Sicherer Kontext: Die Geolocation-API funktioniert nur über HTTPS (oder localhost). Außerdem muss der Nutzer die Freigabe erlauben. In iframes aus anderen Quellen braucht es zusätzlich allow="geolocation" (Permissions Policy).
Optionale Werte: altitude, altitudeAccuracy, heading und speed sind auf Desktop-Geräten fast immer null. heading ist NaN, wenn speed gleich 0 ist. Diese Werte vor der Nutzung prüfen.
Genauigkeit: Ohne GPS schätzt der Browser die Position über WLAN oder IP. Dann kann accuracy mehrere Kilometer betragen. Wenn es auf Präzision ankommt, accuracy auswerten und zu ungenaue Messungen verwerfen.
Serialisierung: Die Eigenschaften von GeolocationCoordinates sind Getter auf dem Prototyp. Deshalb ergeben Spread-Syntax ({...coords}) und in älteren Browsern auch JSON.stringify(coords) ein leeres Objekt. Neuere Browser haben toJSON(). Wer sichergehen will, kopiert die Felder von Hand.
Datenschutz: Standortdaten sind personenbezogen (DSGVO). Die Position erst nach einer Nutzeraktion abfragen und den Zweck erklären.

Siehe auch

GeolocationPosition.timestamp GeolocationPositionError.code GeolocationPositionError.message GeolocationCoordinates.speed Location.origin