About The Project

Hey! 👋 This is a modern JavaScript/TypeScript client for the OpenRouteService API. I built this because I couldn't find a good client library for ORS and thought others might find it useful too.

Why I made this

I was working on multiple projects that needed routing capabilities and while ORS has an amazing API, I couldn't find a good client library for it. So I decided to make one and share it with everyone who might need it.

What makes this client special:

• Zero runtime dependencies - Seriously, check the package.json. All dependencies are just for building/development
• Works everywhere - CommonJS, ES modules, TypeScript, plain JavaScript
• Full TypeScript support - Complete type safety (no more any everywhere!)
• All ORS services - Everything from routing to geocoding in one package
• Built-in throttling - Automatic rate limiting compliance
• Actually useful error messages - Know exactly what went wrong

What's inside?

This client covers all the main ORS services:

• Directions - Get routes with turn-by-turn navigation
• Matrix - Calculate distances between multiple points
• Isochrones - Find reachable areas from a location
• Geocoding - Search for addresses and places
• POIs - Find points of interest
• Optimization - Solve vehicle routing problems
• Elevation - Get elevation data for coordinates
• Export - Extract routing graph data within bounding boxes

Installation

npm install ors-client
# or if you're using pnpm like me
pnpm add ors-client

Quick example

import { OpenRouteService } from "ors-client";

const ors = new OpenRouteService({
   apiKey: "your-api-key", // get one free at openrouteservice.org
});

// Get a route
const route = await ors.directions.calculateRoute("driving-car", {
   coordinates: [
      [8.681495, 49.41461],
      [8.686507, 49.41943],
   ],
});

console.log(`Distance: ${route.routes[0].summary.distance}m`);

Getting an API key

You'll need an API key from OpenRouteService. It's free and you can get one here: https://openrouteservice.org/sign-up/

The free tier is pretty generous for most projects.

More examples

Check out the examples folder. I've added examples for pretty much everything:

• Basic routing
• Distance matrices
• Finding POIs
• Vehicle routing optimization
• And more...

Each example file is runnable, just add your API key and you're good to go.

For developers

If you want to contribute or just poke around:

# Clone the repo
git clone https://github.com/K4ryuu/ors-client.git
cd ors-client

# Install deps
pnpm install

# Run tests (you'll need a .env file with your API key)
cp .env.example .env
# add your key to .env
pnpm test

# Build it
pnpm run build

A note about tests

All tests should pass with a valid API key. If some tests fail, it might be due to temporary API issues or rate limiting.

TypeScript

Everything is fully typed. Your IDE will thank you. No more guessing what properties exist on the response object!

Built-in Rate Limiting & Throttling

This wrapper automatically handles API rate limiting requirements to keep you compliant:

Geocoding Services (Automatic)

• Autocomplete, Search, Reverse geocoding are automatically throttled to ~3.33 requests/second per endpoint
• Each endpoint has independent throttling (search + autocomplete can run simultaneously)
• This follows OpenRouteService's requirement that "requests must be throttled" for geocoding services

Export Service (Manual)

• Export API has very strict rate limits - use sparingly
• Consider caching export results for reuse
• Export tests are skipped in CI due to rate limit sensitivity

All Other Services

• No built-in throttling (directions, matrix, isochrones, etc.)
• Follow standard API rate limits based on your plan

Dependencies

This package has ZERO runtime dependencies. None. Nada. Check the package.json if you don't believe me.

All the packages in devDependencies are only used for building, testing, and linting. When you install this in your project, it's just pure JavaScript/TypeScript code.

API Coverage

All OpenRouteService endpoints are supported:

• ✅ Directions - Routing with turn-by-turn navigation (GET/POST, JSON/GeoJSON)
• ✅ Matrix - Distance/duration calculations between multiple points
• ✅ Isochrones - Reachability analysis (time/distance polygons)
• ✅ Geocoding - Address search, reverse geocoding, autocomplete (with throttling)
• ✅ POIs - Points of interest search with category filtering
• ✅ Optimization - Vehicle routing problem solving (TSP, VRP)
• ✅ Elevation - Point and line elevation data
• ✅ Snap - Coordinate snapping to road network
• ✅ Export - Routing graph data extraction (with rate limit handling)

Error Handling

The wrapper provides detailed error information through OpenRouteServiceError:

try {
  const route = await ors.directions.calculateRoute('driving-car', {
    coordinates: [[8.681495, 49.41461], [8.686507, 49.41943]]
  });
} catch (error) {
  if (error instanceof OpenRouteServiceError) {
    console.log(`API Error: ${error.message}`);
    console.log(`Status: ${error.statusCode}`);

    // Quick error type checks
    if (error.isRateLimited()) {
      console.log('Rate limited! Try again later.');
      console.log(`Remaining requests: ${error.getRemainingRequests()}`);
    }

    if (error.isBadRequest()) {
      console.log('Invalid request parameters');
    }
  }
}

Important notes

Please consider supporting the OpenRouteService team! If you can, definitely thank the OpenRouteService team for their work: https://openrouteservice.org/donations/

Cache your API responses! If you can, definitely cache your API responses to take some load off their servers and help everyone else by keeping the service running smoothly.

Found a bug?

Open an issue on GitHub or send a PR. I try to keep this maintained but you know how it is with side projects 😅

License

MIT - do whatever you want with it

Credits

Built with ☕ by K4ryuu

Special thanks to the OpenRouteService team for providing an amazing routing API! 🚀