@georavity/sdk

Official TypeScript/JavaScript SDK for the Georavity Geospatial API — routing, geocoding, isochrones, and more.

Installation

npm install @georavity/sdk

Quick Start

import { Georavity } from '@georavity/sdk';

const geo = new Georavity('gr_your_api_key');

// Route between two points
const route = await geo.route({
  locations: [
    { lon: 13.388860, lat: 52.517037 }, // Berlin Hauptbahnhof
    { lon: 13.397634, lat: 52.529407 }, // Mauerpark
  ],
  costing: 'auto',
});
console.log(`Distance: ${route.trip.summary.length} km`);
console.log(`Duration: ${route.trip.summary.time} seconds`);

API Reference

Routing

// Standard route
const route = await geo.route({
  locations: [{ lat: 52.52, lon: 13.40 }, { lat: 48.85, lon: 2.35 }],
  costing: 'auto', // 'auto' | 'bicycle' | 'pedestrian' | 'truck'
});

// Optimized route (TSP — visits all locations in optimal order)
const optimized = await geo.optimizedRoute({
  locations: [
    { lat: 52.52, lon: 13.40 },
    { lat: 48.85, lon: 2.35 },
    { lat: 51.50, lon: -0.12 },
  ],
  costing: 'auto',
});

// Distance/time matrix
const matrix = await geo.matrix({
  sources: [{ lat: 52.52, lon: 13.40 }],
  targets: [
    { lat: 48.85, lon: 2.35 },
    { lat: 51.50, lon: -0.12 },
  ],
  costing: 'auto',
});

// Isochrone (reachability polygon)
const iso = await geo.isochrone({
  locations: [{ lat: 52.52, lon: 13.40 }],
  costing: 'auto',
  contours: [{ time: 15 }, { time: 30 }], // 15 and 30 minute contours
  polygons: true,
});

Geocoding

// Forward geocode
const results = await geo.geocode({ text: 'Brandenburg Gate, Berlin' });

// Reverse geocode
const place = await geo.reverse({ 'point.lat': 52.5163, 'point.lon': 13.3777 });

// Autocomplete (for search-as-you-type)
const suggestions = await geo.autocomplete({
  text: 'Bran',
  'focus.point.lat': 52.52,
  'focus.point.lon': 13.40,
});

Error Handling

import { Georavity, GeoravityError } from '@georavity/sdk';

try {
  const route = await geo.route({ ... });
} catch (err) {
  if (err instanceof GeoravityError) {
    console.error(`API Error [${err.code}]: ${err.message}`);
    console.error(`HTTP Status: ${err.status}`);
  }
}

Configuration

const geo = new Georavity('gr_your_api_key', {
  baseUrl: 'https://api.georavity.com', // default
  timeout: 30000, // 30 seconds (default)
});

Costing Models

| Model | Description | |---|---| | auto | Car routing | | bicycle | Bicycle routing | | pedestrian | Walking directions | | truck | Commercial vehicle routing | | bus | Bus routing | | motor_scooter | Scooter routing |

License

MIT — georavity.com