The Problem

Clients that need turn‑by‑turn routing, isochrones, distance matrices, or raw OSM‑based graph exports must either rely on commercial SaaS APIs or build a bespoke routing stack. Maintaining a self‑hosted, standards‑compliant service that can be tuned to local data and deployed in containers is non‑trivial.

What This Does

The repository is a portfolio of four Maven projects that together deliver a complete routing platform:

  • ors-engine – the core graph‑hopper‑derived routing engine (≈ 550 files). It builds and queries the road network, exposing Java APIs used by the API layer.
  • ors-api – a Spring‑Boot REST façade (≈ 230 files). Controllers such as ExportAPI.java, MatrixAPI.java and MatchingAPI.java receive HTTP requests, validate parameters, and forward them to the engine.
  • ors-benchmark – a small benchmark harness (≈ 52 files) for measuring request latency under different configurations.
  • ors-test‑scenarios – curated OSM extracts and expected results used by the integration test suite (≈ 21 files).

Documentation lives under docs/ (VitePress site) and Docker build logic under Dockerfile, .rpm‑packaging/Dockerfile, and docker‑compose.yml.

How It Is Wired

Execution starts with the Spring Boot main class packaged in ors-api (the exact class is not listed but is the standard org.heigit.ors.Application). Maven builds the three modules and assembles a runnable JAR.

  1. HTTP entry – org.heigit.ors.api.controllers.* (e.g., ExportAPI.java, MatrixAPI.java). Each controller parses request bodies, applies ApiConfig/OpenAPIConfig settings, and calls the corresponding service in the engine.
  2. Engine call – Controllers invoke methods in ors-engine (e.g., RoutingEngine.calculateRoute). The engine loads the pre‑processed OSM graph from the data directory (referenced in ors-config.json inside .rpm‑packaging).
  3. Result serialization – Engine returns POJOs that the controller converts to JSON using Jackson and writes to the HTTP response.
  4. Auxiliary services – Health and status endpoints (/health, /status) are implemented in the same controller package but are not exposed by the public live API.

The two Maven modules have no import cycles (static analysis reports 0 circular dependencies). The only cross‑module dependency is ors-api → ors-engine; no other internal module imports exist, keeping the call surface small.

How To Use It

# 1. Clone the exact upstream repository
git clone https://github.com/moses-y/openrouteservice.git
cd openrouteservice

# 2. Build all modules with Maven (requires JDK 11+)
mvn clean install -DskipTests   # skipTests optional; CI runs them separately

# 3. Run the service locally (Docker is the recommended production mode)
docker compose up -d            # uses docker-compose.yml, builds the image
# or, run the jar directly
java -jar ors-api/target/ors-api-*.jar

Configuration lives in ors-config.json (packaged under .rpm-packaging/ors-config.json). Adjust graph.location, router.default_profile, and any API keys there before starting the container or jar. No additional environment variables are required by the code itself.

Real‑World Use

A logistics platform can spin up the image from Docker Hub (heigit/openrouteservice) or build locally, point ors-config.json at a country‑level OSM extract, and issue HTTP POSTs to /v2/directions/foot-walking for real‑time routing. The same instance can serve /v2/isochrones to compute delivery zones, while the benchmark module can be used to size the deployment for expected query volume.

Code Health & Issues

Measured findings (static analysis)

  • High – Deep nesting in several API controllers (e.g., ExportAPI.java, MatchingAPI.java, MatrixAPI.java). Indentation depth 10 makes the flow hard to follow.
  • High – Duplicated code blocks across APIEnums.java, ApiConfig.java, OpenAPIConfig.java, and several controllers (≈ 1 846 repeated 6‑line snippets).
  • High – Oversized test files (ParamsTest.java, ResultTest.java) each > 1 600 lines, risking brittle changes.

Code‑health audit

  • HIGH – CI never runs the test suite (see .github/workflows/*.yml). Add a mvn test step.
  • MEDIUM – Workflows lack least‑privilege GITHUB_TOKEN permissions; add permissions: contents: read.
  • MEDIUM – No Dependabot/Renovate configured; add .github/dependabot.yml.
  • MEDIUM – Base image tomcat:9.0.75 is unpinned; use a digest.
  • MEDIUM – No dependency‑vulnerability scan in CI; add dependency-review-action or osv-scanner.
  • MEDIUM – Large binary (srtm_38_03.gh, 69 MB) stored in Git; move to Git LFS or external storage.
  • MEDIUM – Dockerfile runs as root; create a non‑root USER.
  • LOW – Workflow jobs lack timeout-minutes; set explicit limits.

No critical or license issues were detected; the repository includes a LICENSE, CI, Dockerfiles, and tests.

The Bottom Line

The repo delivers a mature, self‑hostable routing service with a clear separation between engine and API layers, but the codebase suffers from deep nesting, duplicated snippets, and an under‑utilized CI pipeline. It is suitable for teams that need full control over routing data and are prepared to address the highlighted maintainability and security gaps.