Skip to main content

​
Geo Utils API Reference

The Geo Utils provide location detection, geographic calculations, and location-based routing.

​
LocationDetector

Automatic user location detection.

​
Constructor

new LocationDetector(options)
Parameters:
  • options (object): Location detection options

​
Methods

​
detect(request)

Detect location from request. 
const location = await locationDetector.detect(request);
Parameters:
  • request (Request): HTTP request
Returns: Promise resolving to location object

​
detectByIP(ip)

Detect location from IP address. 
const location = await locationDetector.detectByIP('192.168.1.1');
Parameters:
  • ip (string): IP address
Returns: Promise resolving to location object

​
enhance(location)

Enhance location data. 
const enhanced = await locationDetector.enhance(location);
Parameters:
  • location (object): Location object
Returns: Promise resolving to enhanced location

​
DistanceCalculator

Geographic distance calculations.

​
Constructor

new DistanceCalculator(options)
Parameters:
  • options (object): Distance calculation options

​
Methods

​
haversine(point1, point2)

Calculate haversine distance. 
const distance = distanceCalc.haversine(
  { lat: 40.7128, lng: -74.0060 },
  { lat: 34.0522, lng: -118.2437 }
);
Parameters:
  • point1 (object): First point
  • point2 (object): Second point
Returns: Distance in kilometers

​
batchCalculate(origin, points)

Calculate distances to multiple points. 
const distances = distanceCalc.batchCalculate(origin, points);
Parameters:
  • origin (object): Origin point
  • points (array): Array of points
Returns: Array of distances

​
NearestEndpointRouter

Route to nearest endpoints.

​
Constructor

new NearestEndpointRouter(endpointManager, options)
Parameters:
  • endpointManager (EndpointManager): Endpoint manager
  • options (object): Router options

​
Methods

​
findNearest(coordinates)

Find nearest endpoint. 
const endpoint = await router.findNearest({ lat: 40.7128, lng: -74.0060 });
Parameters:
  • coordinates (object): Geographic coordinates
Returns: Promise resolving to nearest endpoint

​
findNearestHealthy(coordinates)

Find nearest healthy endpoint. 
const endpoint = await router.findNearestHealthy(coordinates);
Parameters:
  • coordinates (object): Geographic coordinates
Returns: Promise resolving to nearest healthy endpoint

​
Geocoder

Address geocoding and reverse geocoding.

​
Constructor

new Geocoder(options)
Parameters:
  • options (object): Geocoding options

​
Methods

​
geocode(address)

Convert address to coordinates. 
const location = await geocoder.geocode('1600 Amphitheatre Parkway, Mountain View, CA');
Parameters:
  • address (string): Address string
Returns: Promise resolving to location object

​
reverseGeocode(coordinates)

Convert coordinates to address. 
const address = await geocoder.reverseGeocode({ lat: 37.4419, lng: -122.1430 });
Parameters:
  • coordinates (object): Geographic coordinates
Returns: Promise resolving to address object

​
Type Definitions

​
Location

interface Location {
  country: string;
  region: string;
  city: string;
  coordinates: {
    lat: number;
    lng: number;
  };
  timezone: string;
  accuracy: 'country' | 'region' | 'city';
}

​
Endpoint

interface Endpoint {
  id: string;
  url: string;
  location: {
    lat: number;
    lng: number;
  };
  health?: 'healthy' | 'unhealthy';
  latency?: number;
}

​
GeocodeResult

interface GeocodeResult {
  formattedAddress: string;
  coordinates: {
    lat: number;
    lng: number;
  };
  bounds?: {
    northeast: { lat: number; lng: number };
    southwest: { lat: number; lng: number };
  };
  addressComponents: AddressComponent[];
}