Signatur
Beschreibung
Die Eigenschaft heading eines GeolocationCoordinates-Objekts gibt an, in welche Richtung sich das Gerät gerade bewegt. Der Wert ist in Grad angegeben (0 bis unter 360) und wird im Uhrzeigersinn ab geografisch Nord gezählt: 0 = Norden, 90 = Osten, 180 = Süden, 270 = Westen.
Wichtig: heading ist die Bewegungsrichtung und keine Kompassausrichtung. Das Gerät kann nach Osten zeigen, während es sich nach Norden bewegt. Wer wissen will, wohin das Gerät zeigt, braucht die Sensor-APIs (z. B. DeviceOrientationEvent oder AbsoluteOrientationSensor).
Der Wert ist null, wenn das Gerät die Richtung nicht ermitteln kann. Das ist häufig der Fall bei Desktop-Browsern, bei WLAN- oder IP-basierter Ortung und oft auch bei der ersten Messung. Steht das Gerät still (speed ist 0), ist heading laut Spezifikation NaN. Die Eigenschaft ist deshalb vor allem bei watchPosition() mit enableHighAccuracy: true sinnvoll, etwa für Navigation, Fahrrad- oder Lauf-Tracking und um eine Pfeilmarkierung auf einer Karte zu drehen.
Rückgabewert
NaN, wenn das Gerät stillsteht, und null, wenn die Richtung nicht ermittelt werden kann.Beispiele
Richtung einmalig abfragen und robust prüfen
navigator.geolocation.getCurrentPosition(
({ coords }) => {
const { heading, speed } = coords;
if (heading === null) {
console.log('Richtung nicht verfügbar');
} else if (Number.isNaN(heading)) {
console.log('Gerät steht still');
} else {
console.log(`Richtung: ${heading.toFixed(1)}° bei ${speed} m/s`);
}
},
(err) => console.error('Fehler:', err.message),
{ enableHighAccuracy: true }
);Grad in Himmelsrichtung umrechnen
const toCompass = (deg) => {
const dirs = ['N', 'NO', 'O', 'SO', 'S', 'SW', 'W', 'NW'];
return dirs[Math.round(deg / 45) % 8];
};
navigator.geolocation.getCurrentPosition(({ coords }) => {
if (Number.isFinite(coords.heading)) {
console.log(`Sie bewegen sich Richtung ${toCompass(coords.heading)}`);
}
});Pfeilmarkierung beim Tracking drehen
const arrow = document.querySelector('#arrow');
let lastHeading = 0;
const watchId = navigator.geolocation.watchPosition(
({ coords }) => {
// Letzten gültigen Wert behalten, falls null/NaN geliefert wird
if (Number.isFinite(coords.heading)) {
lastHeading = coords.heading;
}
arrow.style.transform = `rotate(${lastHeading}deg)`;
},
(err) => console.warn(err.message),
{ enableHighAccuracy: true, maximumAge: 0 }
);
// Tracking nach 5 Minuten beenden
setTimeout(() => navigator.geolocation.clearWatch(watchId), 5 * 60 * 1000);// Wichtig · Fallstricke
- Auf
nullundNaNprüfen:NaNbedeutet Stillstand,nullbedeutet, dass der Wert nicht verfügbar ist.Number.isFinite(heading)deckt beide Fälle in einer Prüfung ab. Ein Vergleich wieheading === NaNfunktioniert nie. - Kein Kompass: Der Wert wird aus aufeinanderfolgenden Positionen abgeleitet (meist per GPS). Bei geringer Geschwindigkeit schwankt er stark. Deshalb glätten oder Werte unterhalb einer Mindestgeschwindigkeit (
speed) verwerfen. - Geografisch statt magnetisch Nord: Wer mit Kompasswerten vergleicht, muss die Missweisung (Deklination) berücksichtigen.
- Übergang bei 0°/360°: Beim Mitteln oder Animieren von Winkeln auf den Sprung zwischen 359° und 0° achten, sonst dreht sich z. B. ein Pfeil einmal komplett um sich selbst.
- Kompatibilität: Die Eigenschaft wird in allen modernen Browsern unterstützt, die Geolocation-API funktioniert aber nur in sicheren Kontexten (HTTPS) und nach Zustimmung der Nutzerin oder des Nutzers. Desktop-Geräte ohne GPS liefern praktisch immer
null. - Datenschutz: Bewegungsdaten sind personenbezogen. Das Tracking mit
clearWatch()beenden, sobald es nicht mehr gebraucht wird.