@magmacomputing/tempo-plugin-geo

@magmacomputing/tempo-plugin-geo

A Community plugin for the Tempo ecosystem that provides IP geolocation lookup, browser hardware location services, forward & reverse geocoding gateway with pluggable providers, cultural locale synchronization, and 24-hour multi-tenant coordinate caching.

For geometric GIS math, Great-Circle navigation, and impossible travel anomaly detection, see @magmacomputing/tempo-plugin-spatial.

👉 View the full documentation on our GitHub Pages

Installation

npm install @magmacomputing/tempo-plugin-geo

Usage

1. Fluent OOP with Namespaced Tempo.geo

Installing GeoPlugin mounts an immutable, locked-down Tempo.geo namespace onto the Tempo class:

import { Tempo } from '@magmacomputing/tempo';
import { GeoPlugin } from '@magmacomputing/tempo-plugin-geo';

Tempo.use(GeoPlugin);

// 1. Universal Geolocation Lookup (cached for 24h)
const lookupResult = await Tempo.geo.lookup();
console.log(lookupResult.lat, lookupResult.lng, lookupResult.city);

// 2. Reverse Geocoding (Coordinates -> Address / City / Country)
const address = await Tempo.geo.reverse({ lat: -33.8688, lng: 151.2093 });
console.log(address?.city, address?.country); // 'Sydney', 'AU'

// 3. Inspect Current Ambient / Global Coordinates
console.log(Tempo.geo.current); // { latitude: ..., longitude: ..., city: ... }

// 4. Force Fresh Network Lookup (bypassing 24h cache)
const fresh = await Tempo.geo.lookup({ refresh: true });

// 5. Enrich a Tempo Instance Asynchronously with Cultural Sync
const t = new Tempo('2026-06-21T12:00:00Z', {
  geo: { lat: 30.0444, lng: 31.2357, country: 'EG' } // Cairo
});
const localTime = await t.geoLocate({ setLocale: 'native' });
console.log(localTime.locale); // 'ar-EG'

⚡ Try this live in the interactive Tempo Sandbox ↗

2. Functional Tree-Shakeable APIs

All underlying utilities can be imported as standalone tree-shakeable functions without augmenting Tempo:

import { Tempo } from '@magmacomputing/tempo';
import {
  geoLookup,
  reverseGeocode,
  forwardGeocode,
  resolveCulturalLocale,
  resolveGeoCoordinates,
  stashGeo,
  clearStashedGeo,
  getStashedGeo,
} from '@magmacomputing/tempo-plugin-geo';

// Standalone lookup & instance creation
const coords = await geoLookup();
const t = new Tempo('2026-06-21', { geo: coords });

Which Method Should I Choose?

Goal	Method to Use	Input	Output
"Where is this machine / user right now?"	Tempo.geo.lookup()	None / ambient options	{ latitude, longitude, city, ... }
"Convert place name / address to coordinates"	Tempo.geo.forward("Paris")	Address query string	{ latitude, longitude, ... }
"Convert GPS coordinates to street / city / country"	Tempo.geo.reverse({ lat, lng })	Coordinate object	{ city, country, ... }
"Extract or safely normalize coordinates from any input"	Tempo.geo.resolve(input)	Instance, config, or object	Canonical { latitude, longitude, ... }
"Localize a Tempo instance with timezone & cultural calendar"	await t.geoLocate()	Existing Tempo instance	New enriched Tempo instance

The Tempo.geo API Surface

Method / Property	Description
Tempo.geo.lookup(opts?)	Universal geolocation lookup (browser hardware GPS or server IP lookup) cached for 24h. Supports { refresh: true }.
Tempo.geo.forward(query, opts?)	Forward geocodes query string to coordinates using the active provider.
Tempo.geo.reverse(coords, opts?)	Reverse geocodes coordinates to place/locality metadata using the active provider.
Tempo.geo.setProvider(provider)	Sets the active custom geocoding provider (e.g. OpenStreetMap, Mapbox, internal IP proxy).
Tempo.geo.getProvider()	Retrieves the active custom geocoding provider.
Tempo.geo.resolve(input, opts?)	Asynchronously resolves coordinates from an instance, configuration, or ambient storage cache.
Tempo.geo.coerce(input)	Pure function normalizing various coordinate formats (lat/lng, latitude/longitude, etc.) into a canonical GeoConfig.
Tempo.geo.get(keyOrOpts?)	Reads stored coordinates for the specified tenant/IP or ambient default.
Tempo.geo.set(coords, ttl?, keyOrOpts?)	Sets coordinates in storage with an optional custom TTL (default: 24h) and multi-tenant partitioning.
Tempo.geo.clear(keyOrOpts?)	Purges stored coordinates from storage.
Tempo.geo.current	Read-only getter returning the active global/ambient coordinates snapshot (getStashedGeo() ?? Tempo.config.geo).
Tempo.geo.server(opts?)	Low-level server-side IP geolocation handler.
Tempo.geo.browser(opts?)	Low-level browser Geolocation API handler.

⚠️ Critical Operational Warnings

[!CAUTION] Server Environments (Node.js, Deno, Bun, Workers): In server environments without hardware GPS, calling Tempo.geo.lookup() falls back to server outbound public IP geolocation. When executing in multi-user request pipelines, do not use the default singleton ambient cache if requests come from multiple distinct users. Instead, pass explicit coordinate payloads (new Tempo({ geo: userGeo })) or use tenant keys with stashGeo(coords, ttl, tenantKey).

License

This is a Community plugin. It is completely free and open-source for personal and commercial use under the MIT license.