Web APIs Cheatsheet

Geolocation

Use this Web APIs reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

Checking Support

if ('geolocation' in navigator) {
  // API available
}

getCurrentPosition

navigator.geolocation.getCurrentPosition(
  successCallback,
  errorCallback,   // optional
  options          // optional
);

// Example
navigator.geolocation.getCurrentPosition(
  pos => {
    const { latitude, longitude, accuracy, altitude,
            altitudeAccuracy, heading, speed } = pos.coords;
    const timestamp = pos.timestamp; // ms since epoch
    console.log(latitude, longitude);
  },
  err => {
    // err.code: 1=PERMISSION_DENIED, 2=POSITION_UNAVAILABLE, 3=TIMEOUT
    // err.message: human-readable string
    console.error(err.code, err.message);
  },
  {
    enableHighAccuracy: true,  // GPS (battery-intensive); default false
    timeout: 5000,             // ms until error; default Infinity
    maximumAge: 0,             // ms to use cached position; 0 = always fresh
  }
);

Promise wrapper

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

try {
  const pos = await getPosition({ enableHighAccuracy: true, timeout: 8000 });
  console.log(pos.coords.latitude, pos.coords.longitude);
} catch (e) {
  console.error(e.code, e.message);
}

watchPosition

const watchId = navigator.geolocation.watchPosition(
  pos => {
    // Called whenever position changes
    updateMap(pos.coords.latitude, pos.coords.longitude);
  },
  err => console.error(err),
  { enableHighAccuracy: true, maximumAge: 1000 }
);

// Stop watching
navigator.geolocation.clearWatch(watchId);

GeolocationCoordinates Properties

Property	Type	Description
`latitude`	number	Decimal degrees (-90 to 90)
`longitude`	number	Decimal degrees (-180 to 180)
`accuracy`	number	Meters radius of uncertainty
`altitude`	number \| null	Meters above WGS84 ellipsoid
`altitudeAccuracy`	number \| null	Meters uncertainty for altitude
`heading`	number \| null	Degrees clockwise from true north (0–360), `NaN` if speed is 0
`speed`	number \| null	Meters per second; null if unavailable

Error Codes

Code	Constant	Cause
`1`	`PERMISSION_DENIED`	User denied or site not allowed
`2`	`POSITION_UNAVAILABLE`	Network down, GPS unavailable
`3`	`TIMEOUT`	Response took longer than `timeout` ms

Options Reference

Option	Type	Default	Description
`enableHighAccuracy`	boolean	`false`	Request GPS-level accuracy
`timeout`	number	`Infinity`	Max ms to wait for a position
`maximumAge`	number	`0`	Accept cached position up to N ms old

Permissions API Integration

// Check permission status without triggering a prompt
const status = await navigator.permissions.query({ name: 'geolocation' });
status.state; // 'granted' | 'denied' | 'prompt'
status.addEventListener('change', () => console.log(status.state));

Distance Between Two Points (Haversine)

function haversineKm(lat1, lon1, lat2, lon2) {
  const R = 6371; // Earth radius km
  const dLat = (lat2 - lat1) * Math.PI / 180;
  const dLon = (lon2 - lon1) * Math.PI / 180;
  const a = Math.sin(dLat / 2) ** 2
    + Math.cos(lat1 * Math.PI / 180)
    * Math.cos(lat2 * Math.PI / 180)
    * Math.sin(dLon / 2) ** 2;
  return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
}

Geolocation in a Worker

navigator.geolocation is not available inside Web Workers or Service Workers. Call it on the main thread and postMessage the coordinates.

// main.js
navigator.geolocation.getCurrentPosition(pos => {
  worker.postMessage({ lat: pos.coords.latitude, lon: pos.coords.longitude });
});

Common Patterns and Gotchas

HTTPS required: Geolocation is blocked on plain HTTP (except localhost).
User gesture: Some browsers require a user gesture to trigger the permission prompt.
Coordinates from watchPosition may jump. Apply smoothing (e.g., Kalman filter or rolling average) for smoother tracking.
heading is NaN when speed is 0 on most devices.
altitude and altitudeAccuracy are null on many desktop browsers.

// Timeout + high-accuracy with fallback to low-accuracy
async function getBestPosition() {
  try {
    return await getPosition({ enableHighAccuracy: true, timeout: 5000 });
  } catch (e) {
    if (e.code === 3 /* TIMEOUT */) {
      return getPosition({ enableHighAccuracy: false, timeout: 10000 });
    }
    throw e;
  }
}

Reverse Geocoding (Coordinates to Address)

The Geolocation API only gives coordinates. Use an external service for addresses.

const { latitude: lat, longitude: lon } = position.coords;

// Nominatim (OpenStreetMap, free, rate-limited)
const res = await fetch(
  `https://nominatim.openstreetmap.org/reverse?lat=${lat}&lon=${lon}&format=json`
);
const { display_name } = await res.json();

// Google Maps Geocoding API
const res2 = await fetch(
  `https://maps.googleapis.com/maps/api/geocode/json?latlng=${lat},${lon}&key=API_KEY`
);