GeolocationCoordinates — Schnittstelle · JavaScript-Referenz

Signatur

interface GeolocationCoordinates

Beschreibung

Die Schnittstelle GeolocationCoordinates enthält die eigentlichen Ortsdaten einer Geolocation-Abfrage. Du erzeugst sie nie selbst: Der Browser liefert sie über die Eigenschaft coords des GeolocationPosition-Objekts, das an die Erfolgs-Callbacks von navigator.geolocation.getCurrentPosition() und watchPosition() übergeben wird.

Alle Eigenschaften sind schreibgeschützt:

latitude / longitude – Breiten- und Längengrad in Dezimalgrad (WGS 84).
accuracy – Genauigkeit von Breite/Länge in Metern (Radius, 95 % Konfidenz).
altitude – Höhe über dem WGS-84-Ellipsoid in Metern oder null.
altitudeAccuracy – Genauigkeit der Höhe in Metern oder null.
heading – Bewegungsrichtung in Grad (0 = Norden, im Uhrzeigersinn), NaN bei Stillstand oder null.
speed – Geschwindigkeit in Metern pro Sekunde oder null.
toJSON() – liefert ein einfaches Objekt mit allen Eigenschaften (für Serialisierung).

Typische Einsatzgebiete sind Kartenanwendungen, Umkreissuchen, Lauf-/Fahrt-Tracking oder das Vorausfüllen von Standortangaben. Prüfe immer accuracy, bevor du eine Position weiterverarbeitest – gerade in Innenräumen oder bei WLAN-/IP-basierter Ortung kann die Ungenauigkeit mehrere hundert Meter oder Kilometer betragen.

Beispiele

Aktuelle Koordinaten auslesen

navigator.geolocation.getCurrentPosition(
  ({ coords }) => {
    const { latitude, longitude, accuracy } = coords;
    console.log(`Position: ${latitude.toFixed(5)}, ${longitude.toFixed(5)} (±${Math.round(accuracy)} m)`);
    console.log(coords instanceof GeolocationCoordinates);
  },
  (err) => console.error(`Fehler ${err.code}: ${err.message}`),
  { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 }
);

Position: 52.52001, 13.40495 (±12 m) true

Promise-Wrapper mit Genauigkeitsprüfung

const getCoords = (options = {}) =>
  new Promise((resolve, reject) =>
    navigator.geolocation.getCurrentPosition(
      (pos) => resolve(pos.coords),
      reject,
      { enableHighAccuracy: true, timeout: 8000, ...options }
    )
  );

const main = async () => {
  try {
    const coords = await getCoords();
    if (coords.accuracy > 100) {
      console.warn(`Ungenaue Position (±${Math.round(coords.accuracy)} m)`);
    }
    // toJSON() liefert ein serialisierbares Objekt
    await fetch('/api/standort', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(coords)
    });
  } catch (err) {
    console.error('Standort nicht verfügbar:', err.message);
  }
};

main();

Tracking mit Geschwindigkeit, Richtung und Höhe

const fmt = (v, unit, factor = 1) =>
  v === null || Number.isNaN(v) ? 'unbekannt' : `${(v * factor).toFixed(1)} ${unit}`;

const watchId = navigator.geolocation.watchPosition(
  ({ coords }) => {
    console.log(
      `Tempo: ${fmt(coords.speed, 'km/h', 3.6)}, ` +
      `Richtung: ${fmt(coords.heading, '°')}, ` +
      `Höhe: ${fmt(coords.altitude, 'm')}`
    );
  },
  (err) => console.error(err.message),
  { enableHighAccuracy: true }
);

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

Tempo: 14.4 km/h, Richtung: 87.0 °, Höhe: 41.3 m

Entfernung zwischen zwei Koordinaten (Haversine)

const distanzMeter = (a, b) => {
  const R = 6371000;
  const rad = (d) => (d * Math.PI) / 180;
  const dLat = rad(b.latitude - a.latitude);
  const dLon = rad(b.longitude - a.longitude);
  const h = Math.sin(dLat / 2) ** 2 +
    Math.cos(rad(a.latitude)) * Math.cos(rad(b.latitude)) * Math.sin(dLon / 2) ** 2;
  return 2 * R * Math.asin(Math.sqrt(h));
};

const ziel = { latitude: 48.13743, longitude: 11.57549 }; // München

navigator.geolocation.getCurrentPosition(({ coords }) => {
  console.log(`Noch ${(distanzMeter(coords, ziel) / 1000).toFixed(1)} km bis München`);
});

Noch 504.3 km bis München

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Die Geolocation-API funktioniert ausschließlich über HTTPS (bzw. localhost) und erfordert die Zustimmung des Nutzers. In iframes muss die Permissions Policy geolocation erlaubt sein.
null und NaN beachten: altitude, altitudeAccuracy, speed und heading sind auf Desktop-Geräten ohne GPS fast immer null. heading ist NaN, wenn speed 0 ist – prüfe mit Number.isNaN().
Kein Konstruktor: new GeolocationCoordinates() wirft einen TypeError. Für Tests eigene Objekte mit denselben Eigenschaften verwenden.
Serialisierung: Vor Einführung von toJSON() (ca. 2024) lieferte JSON.stringify(coords) nur {}, da die Eigenschaften Getter am Prototyp sind. Für ältere Browser die Felder manuell kopieren.
Datenschutz: Standortdaten sind personenbezogen (DSGVO). Nur so genau und so lange wie nötig speichern, ggf. Koordinaten runden.
Höhe: altitude bezieht sich auf das WGS-84-Ellipsoid, nicht auf Normalnull – die Abweichung kann in Deutschland ca. 35–50 m betragen.

Siehe auch

Geolocation Navigator.geolocation GeolocationPosition GeolocationPositionError DeprecationReport