📍 Geolocation API

What the Geolocation API Does

The Geolocation API exposes a single object, navigator.geolocation, that answers one question: where is this device right now? The browser figures that out by blending several signals and reporting the best estimate it can:

• GPS — most accurate (a few metres), needs hardware, works best outdoors
• Wi-Fi positioning — good in cities and indoors, matches nearby networks to a database
• Cell-tower triangulation — wide coverage, lower accuracy
• IP address lookup — the rough fallback, often only city-level

You don't choose the method — you ask for a position and (optionally) hint at how much accuracy you want. It's like a rideshare app: it just knows where you are, quietly switching between satellites and Wi-Fi as conditions change.

Permissions & HTTPS

Location is sensitive personal data, so the API is gated by two hard rules:

• Explicit consent. The first request triggers a browser permission prompt. The user can allow once, allow always, or block — and revoke later in site settings.
• Secure context. Geolocation only works over HTTPS (or localhost for development). On plain http:// the request fails immediately.

💡 Ask at the right moment. Don't demand location on page load — users reflexively block prompts they don't understand. Request it right after a clear action like tapping "Find stores near me," when the reason is obvious.

Getting Position Once

getCurrentPosition takes a success callback, an optional error callback, and an optional options object. Here's the modern promise-wrapped version, which reads much more cleanly with async/await:

// Wrap the callback API in a promise
function getPosition(options) {
  return new Promise((resolve, reject) => {
    navigator.geolocation.getCurrentPosition(resolve, reject, options);
  });
}

async function showLocation() {
  if (!('geolocation' in navigator)) {
    console.warn('Geolocation is not supported');
    return;
  }
  try {
    const position = await getPosition({
      enableHighAccuracy: true, // prefer GPS
      timeout: 8000,            // give up after 8s
      maximumAge: 0             // no cached position
    });
    const { latitude, longitude, accuracy } = position.coords;
    console.log(`You are at ${latitude}, ${longitude} (±${accuracy} m)`);
  } catch (err) {
    handleLocationError(err);
  }
}

The Position Object

A successful call hands you a GeolocationPosition with a coords object and a timestamp. Some fields are null when the device can't supply them.

Handling Errors

The error callback receives a GeolocationPositionError whose code matches one of four constants. Handle each with a distinct, helpful response:

function handleLocationError(error) {
  switch (error.code) {
    case error.PERMISSION_DENIED:      // 1
      showMessage('Location blocked. You can enter your city manually.');
      offerManualEntry();
      break;
    case error.POSITION_UNAVAILABLE:   // 2
      showMessage('Could not determine your location right now.');
      break;
    case error.TIMEOUT:                // 3
      showMessage('Location request timed out — try again.');
      break;
    default:                           // unknown
      showMessage('An unexpected error occurred.');
      console.error(error);
  }
}

The most common code by far is PERMISSION_DENIED. Treat it as a normal path, not a crash: every location feature should degrade to a manual address input so blocked users aren't stuck.

Continuous Tracking & Battery

For live navigation or a running tracker, watchPosition fires your callback every time the location updates. It returns a watch ID you later pass to clearWatch to stop.

const watchId = navigator.geolocation.watchPosition(
  (position) => updateMap(position.coords),
  handleLocationError,
  { enableHighAccuracy: true, maximumAge: 1000, timeout: 10000 }
);

// Stop tracking when the feature is closed — critical for battery
function stopTracking() {
  navigator.geolocation.clearWatch(watchId);
}

Measuring distance: the Haversine formula

Coordinates alone aren't useful until you can compute the distance between two of them. The Haversine formula gives great-circle distance across the Earth's surface:

// Distance in metres between two lat/lng points
function distanceMeters(lat1, lng1, lat2, lng2) {
  const R = 6371e3;                 // Earth's radius in metres
  const toRad = (d) => d * Math.PI / 180;
  const dPhi = toRad(lat2 - lat1);
  const dLambda = toRad(lng2 - lng1);
  const a = Math.sin(dPhi / 2) ** 2 +
            Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) *
            Math.sin(dLambda / 2) ** 2;
  return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
}

Hands-on: Distance Tool

<button id="measure">Measure distance</button>
<p id="result" aria-live="polite"></p>

const TARGET = { lat: 48.8584, lng: 2.2945 }; // Eiffel Tower
const result = document.getElementById('result');

function getPosition(opts) {
  return new Promise((res, rej) =>
    navigator.geolocation.getCurrentPosition(res, rej, opts));
}

document.getElementById('measure').addEventListener('click', async () => {
  result.textContent = 'Locating…';
  try {
    const pos = await getPosition({ enableHighAccuracy: false, timeout: 8000 });
    const { latitude, longitude, accuracy } = pos.coords;
    const meters = distanceMeters(latitude, longitude, TARGET.lat, TARGET.lng);
    const km = (meters / 1000).toFixed(1);
    const miles = (meters / 1609.34).toFixed(1);
    result.textContent =
      `You are ${km} km (${miles} mi) from the Eiffel Tower — location accurate to ±${Math.round(accuracy)} m.`;
  } catch (err) {
    result.textContent = err.code === err.PERMISSION_DENIED
      ? 'Location permission is needed to measure distance.'
      : 'Could not get your location. Please try again.';
  }
});

Best Practices

Summary & Quiz

📚 Further Reading

• MDN — Geolocation API
• MDN — Permissions API
• Leaflet.js — open-source mapping library

🚀 What's Next?

You can now read where the user is. Next we tackle a different kind of direct manipulation: the Drag and Drop API, which lets users grab elements and files with the cursor to build sortable lists, kanban boards, and upload zones.