The Problem
Routing is hard. Doing it at scale, with multiple modes of transport, customizable preferences, and real-time data? Even harder. If you're building an app that needs routing, snapping, isochrones, or travel matrix calculations, you're either stuck using expensive SaaS solutions or cobbling together poorly maintained, limited libraries. Enter openrouteservice, a self-hosted, open-source routing API that gives you the flexibility and firepower of big-name services without the price tag or vendor lock-in.
What This Does
At its core, openrouteservice is a routing engine powered by a forked version of GraphHopper. It's written in Java, with Docker support (Dockerfile, docker-compose.yml) for easy deployment. The API provides endpoints like directions, isochrones, matrix, and even some niche ones like snapping and export. These are documented in the extensive docs/api-reference directory, which has per-endpoint breakdowns like directions/custom-models.md.
The repo’s structure is a mixed bag, though. A whopping 151 files live in the docs/ folder, which is great for documentation but makes finding anything else kind of like a digital scavenger hunt. The .github/ folder is stacked with CI/CD workflows using GitHub Actions (e.g., reusablebuilddockerimages.yml, docker-build-and-test.yml), and there’s even some ymlconfigvalidation.sh scripts for converting and validating configs. Deployment and configuration are handled via the .rpm-packaging/ folder, with multiple Dockerfile variants for different setups.
The main entry point for the docs appears to be docs/.vitepress/theme/index.ts, likely for generating the (quite polished) documentation site. From the looks of it, the project has thought of pretty much everything—except maybe a way to make this repo less overwhelming at first glance.
Real-World Use
Say you’re building a ride-sharing app where you need to calculate optimized routes for drivers, estimate ETAs, and provide navigation instructions. With openrouteservice, you could spin up your own instance using the provided docker-compose.yml. Configure the API in docs/run-instance/configuration/ to fine-tune routing profiles (bike, walking, etc.) and preferences like avoiding tolls or ferries. Once running, you can hit the /directions endpoint with a simple POST request and get back JSON with step-by-step directions.
Voilà ! A route, turn-by-turn instructions, and more—no SaaS bill at the end of the month.
The Bottom Line
openrouteservice is a fantastic tool if you need a powerful, self-hosted routing engine and have the time to navigate its labyrinthine structure. It’s overkill for small projects, but if you’re working on something substantial (or want to escape the clutches of commercial APIs), this is a solid option. Just be prepared to spend some time wading through the docs. Bring coffee.