canonical: https://jentic.com/apis/graphhopper.com/graphhopper-directions-api

# GraphHopper Directions API

Jentic publishes the only available OpenAPI specification for GraphHopper Directions API, keeping it validated and agent-ready. This spec covers the full Directions API surface - Routing, Route Optimization, Isochrone, Map Matching, Matrix, Geocoding, and Cluster - across 16 endpoints, with both synchronous and async job-style calls. Authentication is a single API key passed as a query parameter, and OpenStreetMap is the default data layer with optional TomTom traffic add-ons available for the Route Optimization API.

## For AI agents

Calculate routes, optimize multi-stop tours, build matrices, cluster delivery stops, and geocode addresses through the full GraphHopper Directions surface.

## Scope

Does not host interactive map tiles, provide live traffic on the OSM layer, or manage user accounts - use for routing, optimization, matrices, isochrones, geocoding, map matching, and clustering only.

## Capabilities

- Calculate point-to-point and multi-waypoint routes for car, bike, foot, and other profiles via /route
- Submit a clustering problem to /cluster and poll /cluster/solution/{jobId} for grouped stops
- Compute reachable area polygons from a starting point via /isochrone
- Build many-to-many distance and time matrices via /matrix and /matrix/calculate
- Geocode and reverse geocode addresses against OpenStreetMap data via /geocode
- Optimize a vehicle routing problem with time windows via the Route Optimization endpoints

## Use cases

### Fleet Dispatch with Clustering and Optimization

Logistics operators submit large stop lists to /cluster to group nearby orders, then feed each cluster into the Route Optimization API for per-vehicle sequencing. The two-stage flow shortens optimization time and produces realistic per-driver routes for next-day dispatch.

Example prompt: Submit 200 stops to /cluster/calculate with 5 clusters, then send each cluster to the route optimization endpoints and return the per-vehicle stop order

### Service-Area Mapping for Field Teams

Field-service businesses use /isochrone to draw the area their technicians can reach within a service-level-agreement window from each branch. Combined with /matrix, the same data supports branch-to-branch coverage analysis and SLA verification.

Example prompt: Call /isochrone for each of 10 branch coordinates with time_limit=2700 seconds and return a feature collection of reachable polygons

### Geocoding Pipelines for Address Onboarding

Customer onboarding pipelines use /geocode to normalize free-text addresses to coordinates and return a canonical address string, with reverse geocoding available for cases where a user pins a map point. The endpoint is hosted on the same key as routing, simplifying credential management.

Example prompt: Geocode a list of 500 addresses by calling /geocode with q for each and storing the top result with confidence score

### Agent-Driven Operations Assistant via Jentic

An AI ops assistant uses Jentic to discover the right GraphHopper operation for instructions like 'cluster these stops' or 'find a route'. Jentic injects the api_key from the vault and the agent works with the structured response without writing GraphHopper-specific HTTP code.

Example prompt: Search Jentic for 'cluster delivery stops', load the schema for /cluster/calculate, and execute it with the user's stop list

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /route | Calculate a route between waypoints |
| POST | /cluster/calculate | Submit a clustering problem |
| GET | /cluster/solution/{jobId} | Fetch a clustering solution |
| POST | /matrix/calculate | Submit an async matrix problem |
| GET | /isochrone | Compute reachable area polygons |
| GET | /geocode | Forward and reverse geocode |
| POST | /match | Snap a GPS trace to the road network |

## Key resources

- **Routing API** — Calculate routes via /route for car, bike, foot, and other profiles
- **Route Optimization API** — Solve vehicle routing problems with time windows and capacities
- **Matrix API** — Compute distance and time matrices via /matrix and /matrix/calculate
- **Isochrone API** — Generate reachable area polygons via /isochrone
- **Geocoding API** — Forward and reverse geocode via /geocode
- **Map Matching API** — Snap GPS traces to the road network via /match
- **Cluster API** — Group stops via /cluster and /cluster/calculate, then poll /cluster/solution/{jobId}

## Why Jentic

- **Setup:** Wiring the GraphHopper Directions API by hand means passing its API key on every query string and coordinating the route, matrix, isochrone, geocode, and vehicle-routing endpoints, some of which return a job id you then poll, yourself. Through Jentic you install once, import the GraphHopper Directions API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** GraphHopper carries its API key in the query string and its routing targets in the request, so limit the agent to the operations it needs, such as calculating a route or geocoding an address. Every operation you allow is one you have chosen, and you leave out ones like submitting an optimization job if the agent should not run them.
- **Credential handling:** Your GraphHopper API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get driving directions between two points' or 'build a travel-time matrix', and Jentic returns the matching GraphHopper operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **GraphHopper Directions API (core)** — Same vendor, smaller 9-endpoint spec without the Cluster API
- **TomTom Routing** — Commercial routing with live traffic and TomTom map data
- **HERE Maps** — Enterprise routing, matrix, and geocoding with HERE data
- **LocationIQ** — OSM-based geocoding on a separate quota

## FAQ

### Why is there no official OpenAPI spec for GraphHopper Directions API?

GraphHopper does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call GraphHopper Directions API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the GraphHopper Directions API use?

Every endpoint expects an api_key query parameter. Through Jentic the api_key is held in the encrypted vault and injected on each call so the agent prompt never contains the raw key.

### What is the difference between /matrix and /matrix/calculate?

/matrix is the synchronous endpoint and returns the distance/time table directly for small problems. /matrix/calculate is the asynchronous variant that returns a jobId for larger problems, with the result fetched from the jobs endpoints. Use the async path when sources or targets exceed the synchronous size limit on your subscription.

### What are the rate limits for the GraphHopper Directions API?

Limits depend on the GraphHopper plan. The free tier provides a small daily credit budget and one request per second; paid plans scale credits and concurrency upward. The response carries remaining credits in headers and returns HTTP 429 when exceeded.

### How do I cluster delivery stops through Jentic?

Search Jentic for 'cluster delivery stops', load the operation that maps to POST /cluster/calculate, and execute with your stop list and the desired number of clusters. Poll GET /cluster/solution/{jobId} until the solution status is finished, then read the assigned cluster index for each stop.

### Can I integrate live traffic data?

Live traffic is not included on the OpenStreetMap layer. GraphHopper offers a TomTom add-on for the Route Optimization API that uses TomTom road network and historical traffic; live traffic is not yet considered. Contact GraphHopper to enable the add-on on your account.

### Can I limit what my agent is allowed to do with the GraphHopper Directions API?

Yes. Because you run Jentic One yourself, your own rules decide which GraphHopper operations the agent may call and which stored credentials it may use, so you can allow only what a task needs, such as calculating a route via /route or geocoding an address via /geocode. Every operation you enable is one you have chosen, so you can leave out others like submitting an optimization job to /cluster/calculate or /matrix/calculate if the agent should not run them. The API key sits in the query string and the routing targets travel in the request, and both stay under the operation scope you set.