# openrouteservice runs GraphHopper on OpenStreetMap, and health checks only exist if you self host > openrouteservice is a GPL-3.0 Java routing service that forks GraphHopper 4.0 and exposes directions, isochrones, matrix, snapping and export over an HTTP API, with data taken straight from OpenStreetMap. Two of its seven endpoints are deliberately absent from the hosted API, which tells you exactly what self hosting buys you. **GIScience/openrouteservice** — 🌍 The open source route planner api with plenty of features. - Repository: https://github.com/GIScience/openrouteservice - Website: https://openrouteservice.org - Stars: 1,986 · Forks: 487 - Language: Java - License: GPL-3.0 - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/giscience-openrouteservice ## A forked GraphHopper is the reason upgrades need reading openrouteservice is a Java routing service that uses a forked and edited version of GraphHopper 4.0, with the fork maintained by the same organisation rather than taken from the upstream project. That choice has consequences worth stating plainly. You get routing behaviour shaped by the project's needs rather than by upstream defaults, and in exchange you cannot simply bump the GraphHopper dependency to pick up upstream fixes. Anyone upgrading openrouteservice across a major version is taking a change in routing output as well as a change in API, and the CHANGELOG at the repository root is the place to look. The data side is equally opinionated. The service consumes free geographic data directly from OpenStreetMap, both user generated and collaboratively collected, and that is the whole input. There is no proprietary data source to license and no import step for tiles, which is what makes a self hosted instance reproducible from the repository and the extract you choose. The project describes itself as highly customizable and performant, with performance left as a claim rather than a published figure. There is a benchmark module in the repository, but the README publishes no numbers. ## Five services in the software, and four more that live elsewhere The endpoint list separates what this repository is from what the hosted API happens to offer, and that separation is the most useful thing in the README. Inside the software are seven endpoints. The Directions Service returns directions for different modes of transport. The Isochrones Service returns areas of reachability from a location. The Matrix Service returns one-to-many, many-to-one and many-to-many matrices for time and distance. The Snapping Service snaps coordinates to the road network. The Export Service exports the base graph for different modes of transport. The Health Endpoint reports on the running instance, and the Status Endpoint reports its status. Those last two carry a footnote with a warning: they are not available on the public live API. You can only use them on an instance you run yourself. Health and status are what you point a monitoring system at, so if you depend on the hosted API you have no way to ask it how it is doing. Then there is the reverse problem. Several endpoints on the live API are not part of this software: openpoiservice for points of interest around a geometry, openelevationservice for elevation along points or lines, Pelias as a reverse geocoder hosted by HeiGIT, and VROOM for vehicle routing optimisation. If you are scoping a logistics or geocoding product, those are separate deployments. ## Docker Compose is the recommended path, with five directories created first Installation is a container workflow, and the order matters because the container persists into directories you create. The five directories are for configuration, the elevation cache, the graphs, files and logs: ```bash mkdir -p ors-docker/config ors-docker/elevation_cache ors-docker/graphs ors-docker/files ors-docker/logs ``` Then fetch the compose file for the latest release and start it: ```bash wget https://github.com/GIScience/openrouteservice/releases/latest/download/docker-compose.yml docker compose up -d ``` Starting it this way pulls the image for the selected version and comes up with an example setup and a provided test OpenStreetMap file covering Heidelberg and its surroundings, so you get a working instance without preparing an extract first. The README is explicit about the version choice: only use the nightly build from the main branch if you know what you are doing, and run Docker Compose with the latest release version otherwise. Nightly images are published on Docker Hub under heigit/openrouteservice, and there are separate CI statuses for the nightly image and for the tagged release image. Lifecycle is the three commands you would expect. Logs with docker compose logs, shutdown with docker compose down. ## Port 8080 on the host maps to 8082 in the container The endpoint paths carry a version prefix, which matters when you write a client against them. With the compose setup in place, the seven endpoints answer under /ors/v2: ``` http://localhost:8080/ors/v2/directions http://localhost:8080/ors/v2/isochrones http://localhost:8080/ors/v2/matrix http://localhost:8080/ors/v2/snap http://localhost:8080/ors/v2/export http://localhost:8080/ors/v2/health http://localhost:8080/ors/v2/status ``` The port mapping is the detail that catches people. The compose file exposes 8080 on the host against 8082 in the container, with the comment that this exposes the API on port 8080, and it additionally exposes 9001 for monitoring. There is no authentication layer described anywhere in the README, which means the instance you start is a routing service for anyone who can reach it. For exploring the API there is a demonstration server with both a backend and a frontend, and an API Playground on the developer site. For a local instance, the API Reference documents how to use the Swagger UI and the playground against your own server, so the hosted tooling is not limited to the hosted data. ## A multi-module Maven build that also carries a VitePress site The repository is a Maven multi-module build with the Maven wrapper committed, which is why the Dockerfile can copy pom.xml files and run dependency resolution before any source is copied in. The modules are ors-api, ors-engine, ors-report-aggregation, ors-test-scenarios and ors-benchmark. The split between api and engine is the interesting one: the API surface and the routing engine are separate modules, so an embedder can depend on one without the other. The Dockerfile resolves dependencies for ors-api and ors-engine explicitly, which implies the other modules are not on the runtime path. The Dockerfile also shows how seriously the runtime image is treated. The build stage uses a pinned Maven image with a digest, the runtime uses a slim base, and the JDK is cut down with jlink to a named module set rather than shipping a full JDK. There are comments explaining that the slim base ships native libraries but no JVM, and that a temporary directory has to exist because the distroless base ships no temporary directory at all and a copy instruction cannot create one. That is the level of detail that separates a maintained image from one that merely works. Alongside the Java build there is a JavaScript package for documentation. package.json holds vitepress with a Mermaid plugin and a code block folding plugin, plus a versioning plugin, and the version there reads 10.2.0-SNAPSHOT while the latest GitHub release is v10.1.0 from 2026-10-14. The docs scripts are docs:dev, docs:build and docs:preview. ## GPL-3.0 with a lesser companion licence The licence situation needs reading rather than summarising. The repository carries a LICENSE file and, beside it, a LICENSE.LESSER and a NOTICE.md. Whether that applies to your deployment is a question for whoever reads those files, not for this article. The repository is identified as GPL-3.0 and also contains a NOTICE.md file. Release practice is disciplined enough to plan around. Recent releases are v10.0.0 on 2026-09-16, v10.0.1 on 2026-09-24 and v10.1.0 on 2026-10-14. A RELEASE.md at the root and renovate.json for dependency updates sit alongside the CHANGELOG, and openvex.json at the root suggests the project publishes machine readable vulnerability information. ## Conclusion Self hosted openrouteservice suits anyone who needs matrix or isochrone queries at volume, who needs the health and status endpoints for their own monitoring, or who cannot send routing requests to a third party. It is the wrong choice for a project that needs geocoding, elevation or vehicle routing optimisation, since the README places those in separate services that are not part of this repository. Before deploying, create the five persistence directories the container writes to and run it as 1000:1000, because the compose file states that a different user id requires rebuilding the image. ## FAQ ### How do I run openrouteservice with Docker? Create the persistence directories with mkdir -p for config, elevation_cache, graphs, files and logs, download the docker-compose.yml from the latest release page, then run docker compose up -d. It starts with a test OpenStreetMap extract for Heidelberg. ### Are the health and status endpoints available on the hosted API? No. The README notes that the Health and Status endpoints are not available on the public live API and can only be used on an instance you run yourself. ### Which routing engine does openrouteservice use? It uses a forked and edited version of GraphHopper 4.0, maintained by the same organisation, rather than upstream GraphHopper. ### Does openrouteservice include geocoding and elevation lookup? No. The README lists openpoiservice, openelevationservice, Pelias and VROOM as separate services available on the live API but not part of this software or repository. ### What port do the openrouteservice endpoints use? The Docker Compose setup maps port 8080 on the host to 8082 in the container, and the endpoints answer under paths such as /ors/v2/directions and /ors/v2/matrix. ## Sources - [GIScience/openrouteservice on GitHub](https://github.com/GIScience/openrouteservice) - [License: GPL-3.0](https://github.com/GIScience/openrouteservice/blob/main/LICENSE) - [Project website](https://openrouteservice.org) - [README](https://github.com/GIScience/openrouteservice/blob/main/README.md) - [Releases](https://github.com/GIScience/openrouteservice/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/giscience-openrouteservice