Geolocation

Detect and track the user's geographic location using the browser Geolocation API with an automatic IP-based fallback. Calculate distances with the Haversine formula. Access via Aura.geo.

Quick Start

js
import Aura from 'aura.js';

Aura.init();

// Detect location (browser GPS or IP fallback)
const loc = await Aura.geo.detect();
console.log(`${loc.latitude}, ${loc.longitude} (${loc.source})`);

// Watch for real-time updates
const unsub = Aura.geo.watch(loc => {
  console.log('Moved to:', loc.latitude, loc.longitude);
});

// Calculate distance between two points
const km = Aura.geo.distance(40.7128, -74.0060, 51.5074, -0.1278);
console.log(`NYC to London: ${km.toFixed(0)} km`);

detect()

Detects the user's location. If geolocation permission is already granted, uses the browser Geolocation API with high accuracy. Otherwise, falls back to IP-based geolocation via ipapi.co. The result is cached internally.

async detect(): Promise<GeoLocation>

js
const loc = await Aura.geo.detect();

console.log(loc.latitude);  // 37.7749
console.log(loc.longitude); // -122.4194
console.log(loc.accuracy);  // 25 (meters, browser only)
console.log(loc.source);    // "browser" or "ip"

getLocation()

Returns the last cached location, or null if no location has been detected yet. This is a synchronous read of whatever detect() or watch() last resolved.

getLocation(): GeoLocation | null

js
const cached = Aura.geo.getLocation();

if (cached) {
  console.log(`Last known: ${cached.latitude}, ${cached.longitude}`);
} else {
  console.log('No location cached — call detect() first');
}

checkPermission()

Queries the current geolocation permission state without triggering a prompt. Returns 'prompt' as a fallback if the Permissions API is unavailable.

async checkPermission(): Promise<PermissionState>

js
const perm = await Aura.geo.checkPermission();
// "granted" | "denied" | "prompt"

if (perm === 'denied') {
  showLocationDeniedMessage();
}

requestPermission()

Explicitly requests geolocation permission by calling the browser Geolocation API. This will trigger the browser permission prompt if not yet granted. If the browser denies or fails, falls back to IP-based location.

async requestPermission(): Promise<GeoLocation>

js
try {
  const loc = await Aura.geo.requestPermission();
  console.log('Got location:', loc);
} catch (err) {
  console.error('Location unavailable', err);
}

watch()

Starts watching the user's position in real time using navigator.geolocation.watchPosition with high accuracy enabled. The callback fires on each position update. Returns an unsubscribe function that calls unwatch().

watch(fn: (loc: GeoLocation) => void): () => void

Param	Type	Description
fn	(loc: GeoLocation) => void	Callback invoked with updated location on each position change

js
const stop = Aura.geo.watch(loc => {
  updateMapPin(loc.latitude, loc.longitude);
  console.log(`Accuracy: ${loc.accuracy}m`);
});

// Stop watching later
stop();

unwatch()

Stops the active position watcher started by watch(). Clears the internal watch ID. Safe to call even if no watcher is active.

unwatch(): void

js
Aura.geo.unwatch();

distance()

Calculates the great-circle distance in kilometers between two geographic coordinates using the Haversine formula.

distance(lat1: number, lon1: number, lat2: number, lon2: number): number

Param	Type	Description
lat1	number	Latitude of the first point (degrees)
lon1	number	Longitude of the first point (degrees)
lat2	number	Latitude of the second point (degrees)
lon2	number	Longitude of the second point (degrees)

Returns: distance in kilometers.

js
// New York to London
const km = Aura.geo.distance(40.7128, -74.0060, 51.5074, -0.1278);
console.log(km); // ~5570

// Paris to Tokyo
const d = Aura.geo.distance(48.8566, 2.3522, 35.6762, 139.6503);
console.log(`${d.toFixed(0)} km`); // ~9713 km

distanceFrom()

Calculates the distance in kilometers from the user's last cached location to a given point. Returns null if no location has been detected yet.

distanceFrom(lat: number, lon: number): number | null

Param	Type	Description
lat	number	Latitude of the target point (degrees)
lon	number	Longitude of the target point (degrees)

js
// First detect location
await Aura.geo.detect();

// Then calculate distance to a point of interest
const km = Aura.geo.distanceFrom(48.8566, 2.3522); // Paris

if (km !== null) {
  console.log(`You are ${km.toFixed(1)} km from Paris`);
}

Types

GeoLocation

ts
interface GeoLocation {
  latitude: number;
  longitude: number;
  accuracy?: number;        // meters (browser source only)
  source: 'browser' | 'ip';
}