Geo Utils API

Complete API reference for geographic utilities

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[];
}