Skip to content

OpenAPI Specification

The Valhalla API is described in a machine-readable OpenAPI 3.1 spec at docs/docs/api/openapi.yaml. Use it to explore endpoints interactively, generate client code, or validate requests and responses.

Browse it locally

The quickest way is Docker — no install required:

docker run --rm -p 8080:8080 \
  -e SWAGGER_JSON_URL=https://raw.githubusercontent.com/valhalla/valhalla/master/docs/docs/api/openapi.yaml \
  swaggerapi/swagger-ui

Or mount the local file instead:

docker run --rm -p 8080:8080 \
  -v $(pwd)/docs/docs/api/openapi.yaml:/openapi.yaml \
  -e SWAGGER_JSON=/openapi.yaml \
  swaggerapi/swagger-ui

Open http://localhost:8080.

docker run --rm -p 8080:80 \
  -v $(pwd)/docs/docs/api/openapi.yaml:/usr/share/nginx/html/openapi.yaml \
  -e SPEC_URL=openapi.yaml \
  redocly/redoc

Open http://localhost:8080.

npx @stoplight/elements-dev-portal --spec docs/docs/api/openapi.yaml

Build a standalone HTML page

Redocly can bundle the spec into a single self-contained HTML file — useful for sharing or hosting without a running server:

npx @redocly/cli build-docs docs/docs/api/openapi.yaml \
  -o redoc-static.html \
  --title "Valhalla API" \
  --theme.openapi.typography.fontWeightRegular=bold

Open redoc-static.html directly in a browser. No server needed.

The file is self-contained, so you can open it directly:

xdg-open redoc-static.html   # Linux
open redoc-static.html        # macOS

Or serve it over HTTP (run from the directory containing the file):

python3 -m http.server 8080
# then open http://localhost:8080/redoc-static.html

If you just want to browse interactively without a build step, the Docker options above skip straight to serving.

Validate the spec

# Using the Redocly CLI (no Docker needed)
npx @redocly/cli lint docs/docs/api/openapi.yaml

# Or via Docker
docker run --rm -v $(pwd):/spec redocly/cli lint /spec/docs/docs/api/openapi.yaml

Generate a client

# Python client via openapi-generator
docker run --rm -v $(pwd):/local openapitools/openapi-generator-cli generate \
  -i /local/docs/docs/api/openapi.yaml \
  -g python \
  -o /local/generated/python-client

Any generator supported by openapi-generator works the same way — swap -g python for the target language.

Try requests against a live server

The spec's default server is https://valhalla.openstreetmap.de. To point it at a local instance, either edit the servers block in openapi.yaml or override it in the Swagger UI server dropdown.

# Quick smoke test with curl (local server on port 8002)
curl -s http://localhost:8002/route \
  -H 'Content-Type: application/json' \
  -d '{"locations":[{"lat":47.141,"lon":9.521},{"lat":47.165,"lon":9.510}],"costing":"auto"}' \
  | jq '.trip.summary'

Keeping the spec in sync

The spec lives alongside the docs in docs/docs/api/openapi.yaml. When you add or change an API parameter, update both the relevant Markdown reference (e.g. api/turn-by-turn/api-reference.md) and the corresponding schema in openapi.yaml.