@trap_stevo/geotide

🌊 @trap_stevo/geotide

The ultimate event-driven, precision-powered geolocation engine — from IP to doorstep, in real-time.
Fuses IP intelligence, reverse geocoding, and radio/Wi-Fi triangulation into a single, real-time, precision-crafted API.
Trace a single packet’s origin, map a million connections, or power real-time location-aware apps with elegance, accuracy, and streaming insight.

🚀 Features

• 🌍 Multi-Provider IP Intelligence – Auto-races top geo APIs (ipwhois, ipapi, ipinfo, ipgeolocation) with scoring and failover
• 🛰 Reverse Geocoding – Converts coordinates to human-readable addresses
• ⚡ Real-Time Event System – Subscribe to lookups, cache hits, provider health, and reverse-geocoding events as they happen
• 🧩 Custom Provider Injection – Append your own IP lookup, reverse geocoding, or triangulation services
• 📦 Batch Mode – Resolve thousands of IPs at once with bounded concurrency and preserved order
• 🛡 Resilient & Cached – LRU caching and automatic provider failover for speed and reliability
• 🔍 Confidence Scoring – Each lookup is scored for trustworthiness

🧠 Use Cases

• Live geolocation dashboards
• Security and fraud prevention
• Multiplayer game region detection
• Content localization and targeting
• Network monitoring and analytics
• Emergency response systems

⚙️ System Requirements

Requirement	Version
Node.js	≥ 19.x
npm	≥ 9.x (recommended)
OS	Windows, macOS, Linux

🔍 API Specifications

🔧 Methods

Method	Signature	Returns	Description	Async?
lookup(ip)	lookup(ip: string)	Promise<GeoResult | null>	Resolves a public IP into normalized location metadata. Uses provider race + scoring + TTL cache.	Yes
lookupMany(ips, opts?)	lookupMany(ips: string[], opts?: { concurrency?: number })	Promise<(GeoResult | null)[]>	Batch IP lookup with bounded concurrency (default = maxConcurrency).	Yes
reverse(lat, lon, opts?)	reverse(lat: number, lon: number, opts?: { deadlineMs?: number, cacheTtlMs?: number })	Promise<ReverseResult | null>	Reverse-geocodes coordinates to a human address by racing Mapbox/Google/Nominatim with caching.	Yes
getClientIP(req)	getClientIP(req: IncomingMessage | Express.Request)	string | null	Extracts the client's IP from HTTP request headers and connection info, supporting proxies and IPv6 normalization.	No
on(event, handler)	on(event: GeoTideEvent, handler: (payload: any) => void)	this	Subscribe to real-time events (telemetry, results, cache hits, health).	No
off(event, handler)	off(event: GeoTideEvent, handler: Function)	this	Unsubscribe a previously registered listener.	No

📦 Return Types

type GeoResult = {
  source: string;              // provider name
  ip: string;
  city: string | null;
  region: string | null;
  country: string | null;
  org: string | null;
  isp: string | null;
  loc: string | null;          // "lat,lon"
  timezone: string | null;
  postal: string | null;
  flag: string | null;         // emoji when available
  continent: string | null;
  confidence: number;          // 0..1
};

type ReverseResult = {
  provider: string;            // provider name
  formatted: string;
  components: any;
  lat: number;
  lon: number;
};

📡 Events

Event	Payload	Description
lookup:start	{ ip }	A lookup has started.
lookup:cache_hit	{ ip, result }	Result served from cache.
lookup:result	{ ip, result }	Fresh lookup result returned.
provider:success	{ provider, ip, durationMs, score }	A provider returned data successfully.
provider:fail	{ provider, ip, error }	A provider failed.
provider:unhealthy	{ provider, reason }	Provider marked temporarily unhealthy.
reverse:start	{ lat, lon }	Reverse geocoding started.
reverse:cache_hit	{ lat, lon, result }	Reverse geocoding served from cache.
reverse:result	{ lat, lon, result }	Fresh reverse geocoding result returned.

📦 Installation

npm install @trap_stevo/geotide

🛠️ Usage

🌐 IP Lookup

const GeoTide = require("@trap_stevo/geotide");

const geo = new GeoTide({ enableGeoDebug : true });

const result = await geo.lookup("203.0.113.42");

console.log(result);
// {
//   source: 'ipwhois',
//   ip: '203.0.113.42',
//   city: 'Sample City',
//   region: 'Sample Region',
//   country: 'Sample Country',
//   org: 'Sample ISP Org',
//   isp: 'Sample ISP',
//   loc: '37.4221,-122.0841',
//   timezone: 'America/Los_Angeles',
//   postal: '94043',
//   flag: '🌍',
//   continent: 'North America',
//   confidence: 1
// }

📦 Batch IP Lookup

const results = await geo.lookupMany([
  "203.0.113.42",
  "8.8.8.8"
]);

console.log(results);

🗺 Reverse Geocoding

const address = await geo.reverse(40.712776, -74.005974);

console.log(address.formatted);
// "Example Building, 123 Example Street, Sample City, NY, United States"

⚡ Real-Time Events

geo.on("lookup:result", ({ ip, result }) => {
  console.log(`[GeoTide] ${ip} → ${result.city}, ${result.country}`);
});

📜 License

See License in LICENSE.md

🌊 GeoTide — The Pulse of the Planet, in Real-Time.
From the ocean of IPs to the pinpoint of a doorstep, GeoTide flows with accuracy, speed, and live awareness.