# Graphhopper

GraphHopper Directions API provides enterprise-grade routing services, including route planning, optimization, geocoding, and more, for various vehicle types.

- **Category:** developer tools
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 13
- **Triggers:** 0
- **Slug:** `GRAPHHOPPER`
- **Version:** 20260217_00

## Tools

### Capacity Clustering

**Slug:** `GRAPHHOPPER_CLUSTER_POST`

Solve capacity-constrained clustering problems by assigning customers to clusters while minimizing total travel distance. Useful for delivery zone planning, sales territory optimization, and workload balancing. Supports car, bike, and foot routing profiles. Note: Free tier limited to 5 customers per request.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `clusters` | array | No | Optional pre-defined cluster centers. If omitted, cluster centers are computed automatically. Length must equal num_clusters if provided. |
| `customers` | array | Yes | List of customers to assign to clusters. Free tier limited to 5 customers. |
| `configuration` | object | Yes | Routing profile and clustering constraints configuration. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### GraphHopper Geocoding

**Slug:** `GRAPHHOPPER_GEOCODE_GET`

Tool to perform forward or reverse geocoding. Use when converting between textual addresses and latitude/longitude coordinates.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | Text to geocode (forward geocoding). Required when reverse=false; must be omitted if reverse=true. |
| `key` | string | No | Your GraphHopper API key. If not provided, it will be automatically injected from the connection. |
| `bbox` | string | No | Bounding box 'minLon,minLat,maxLon,maxLat'. Requires reverse=false. Only provider=default. |
| `zoom` | number | No | Map-like zoom level controlling focus radius. Only provider=default. |
| `debug` | boolean | No | Pretty-print the output. Default false. |
| `limit` | integer | No | Maximum number of results. Default 5. |
| `point` | string | No | Coordinate 'lat,lon'. Required when reverse=true; for forward geocoding, acts as location bias. |
| `bounds` | string | No | Bounds 'minLon,minLat,maxLon,maxLat'. For nominatim or opencagedata. |
| `locale` | string ("en" | "de" | "fr") | No | Locale of results. Default 'en'. |
| `radius` | number | No | Search radius. Default: km for provider=default when reverse=true; meters for provider=gisgraphy. |
| `osm_tag` | array | No | OSM tags to filter/include or exclude, e.g., 'tourism:museum' or '!tourism:museum'. Only provider=default. |
| `reverse` | boolean | No | Set to true for reverse geocoding. Default false. |
| `provider` | string ("default" | "nominatim" | "gisgraphy" | "opencagedata") | No | Alternative geocoding provider. |
| `countrycode` | string | No | ISO 3166-1 alpha-2 country filter. For nominatim, gisgraphy, or opencagedata. |
| `autocomplete` | boolean | No | Enable autocomplete (only for provider=gisgraphy and reverse=false). |
| `location_bias_scale` | number | No | Location bias scale between 0.0 and 1.0. Only provider=default. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Cluster Solution

**Slug:** `GRAPHHOPPER_GET_CLUSTER_SOLUTION`

Tool to retrieve the solution of an asynchronous clustering job. Use when you have a job ID from a previous cluster calculation request and need to fetch the results.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | Job ID returned from the cluster calculation endpoint. Use this to retrieve the clustering solution. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Matrix

**Slug:** `GRAPHHOPPER_GET_MATRIX`

Tool to compute a distance and/or time matrix using GET request with query parameters. Use for simpler matrix requests with query parameters instead of POST body.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `point` | array | No | Specify multiple points in 'latitude,longitude' format for which the matrix should be calculated. The starts are identical to the destinations. If there are N points, then NxN entries will be calculated. Specify at least three points. Cannot be used together with from_point or to_point. |
| `profile` | string | No | The routing profile. It determines the network, speed and other physical attributes used when computing the route. Valid values include 'car', 'bike', 'foot', 'hike', 'mtb', 'racingbike', 'scooter', 'truck', and 'small_truck'. |
| `curbside` | array | No | Optional parameter. Specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. Must be 'any', 'left', or 'right'. Specify for either none or all points. |
| `to_point` | array | No | The destination points for the routes in 'latitude,longitude' format. Use together with from_point for asymmetric matrices. |
| `fail_fast` | boolean | No | Specifies whether or not the matrix calculation should return with an error as soon as possible in case some points cannot be found or some points are not connected. If set to false, the matrix will be calculated for all valid points and contain null values for entries that could not be calculated. |
| `out_array` | array | No | Specifies which arrays should be included in the response. Specify one or more of 'weights', 'times', 'distances'. The units of distances are meters, times are seconds, and weights are arbitrary. |
| `from_point` | array | No | The origin points for the routes in 'latitude,longitude' format. Use together with to_point for asymmetric matrices. |
| `point_hint` | array | No | Optional parameter. Specifies a hint for each point parameter to prefer a certain street for the closest location lookup. |
| `to_curbside` | array | No | Curbside setting for the to_point parameter. Must be 'any', 'left', or 'right'. |
| `from_curbside` | array | No | Curbside setting for the from_point parameter. Must be 'any', 'left', or 'right'. |
| `to_point_hint` | array | No | For the to_point parameter. Specifies a hint to prefer a certain street for the closest location lookup. |
| `from_point_hint` | array | No | For the from_point parameter. Specifies a hint to prefer a certain street for the closest location lookup. |
| `snap_prevention` | array | No | Optional parameter to prevent snapping to specific types of roads. Supported values: 'motorway', 'trunk', 'ferry', 'tunnel', 'bridge', 'ford'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Matrix Solution

**Slug:** `GRAPHHOPPER_GET_MATRIX_SOLUTION`

Tool to retrieve the result of an asynchronous matrix computation job. Use when you have a job ID from a previous matrix calculation request and need to check if it's finished and get the results.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | The job ID returned when you submitted the matrix calculation job. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### GET Route

**Slug:** `GRAPHHOPPER_GET_ROUTE`

Tool to calculate the best path connecting two or more points using simple GET request. Use when you need basic routing with query parameters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `debug` | boolean | No | Enable formatted output for debugging. |
| `point` | array | Yes | Route waypoints as 'latitude,longitude' strings. Specify at least origin and destination. Via points are possible. Example: ['51.131,12.414', '48.224,3.867'] |
| `locale` | string | No | Locale for turn instructions. Examples: 'en', 'de', 'fr', 'pt_PT' |
| `details` | array | No | Path detail types to include. Available: 'street_name', 'street_ref', 'street_destination', 'leg_time', 'leg_distance', 'roundabout', 'country', 'time', 'distance', 'max_speed', 'max_weight', 'max_width', 'toll', 'road_class', 'road_class_link', 'road_access', 'road_environment', 'hazmat', 'hazmat_tunnel', 'hazmat_water', 'lanes', 'surface', 'smoothness', 'hike_rating', 'mtb_rating', 'foot_network', 'bike_network' |
| `heading` | array | No | Preferred heading direction for each point in degrees (0-360, north-based clockwise). Specify one for start or one per point. Requires ch.disable=true. |
| `profile` | string | No | The routing profile determining network, speed, and physical attributes. Common values: 'car', 'bike', 'foot', 'motorcycle', 'mtb', 'racingbike', 'hike'. Default: 'car' |
| `curbside` | array | No | Side of the road for leaving/arriving at each point. Specify for all points or none. Only for motor vehicles. |
| `optimize` | string | No | If 'true', reorders points to minimize total travel time. Applies route optimization limits and costs more credits. |
| `algorithm` | string ("round_trip" | "alternative_route") | No | Special routing algorithm. 'round_trip': returns to start with randomness. 'alternative_route': provides multiple route options. |
| `elevation` | boolean | No | Include altitude as third coordinate in response. Changes format of points and snapped_waypoints fields. |
| `ch.disable` | boolean | No | Enable flexible mode to use custom_model or advanced options below. Set to true for heading, algorithm, etc. |
| `point_hint` | array | No | Optional road name hints for snapping each point. Specify none or the same number as points. |
| `calc_points` | boolean | No | Whether to calculate route geometry points. |
| `instructions` | boolean | No | Whether to calculate and return turn-by-turn instructions. |
| `pass_through` | boolean | No | Avoid u-turns at via-points with regard to heading_penalty. Requires ch.disable=true. |
| `points_encoded` | boolean | No | Use polyline encoding for geometry (true) or simple coordinate pairs (false). |
| `heading_penalty` | integer | No | Time penalty in seconds for not obeying specified heading. Requires ch.disable=true. |
| `round_trip.seed` | integer | No | Random seed for deterministic round trip results. Requires algorithm='round_trip'. |
| `snap_prevention` | array | No | Prevent snapping to specific road types. Values: 'motorway', 'trunk', 'ferry', 'tunnel', 'bridge', 'ford' |
| `round_trip.distance` | integer | No | Approximate round trip length in meters. Requires algorithm='round_trip'. |
| `alternative_route.max_paths` | integer | No | Maximum number of alternative paths. Requires algorithm='alternative_route'. |
| `alternative_route.max_share_factor` | number | No | Maximum similarity factor between alternative and optimal route. Requires algorithm='alternative_route'. |
| `alternative_route.max_weight_factor` | number | No | Maximum factor by which alternatives can be longer than optimal route. Requires algorithm='alternative_route'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Isochrone

**Slug:** `GRAPHHOPPER_ISOCHRONE_GET`

Tool to compute isochrone polygons for a given point. Use when you need to determine areas reachable within time or distance constraints.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `point` | string | Yes | Start location as 'latitude,longitude', e.g., '52.529407,13.397634'. Must be a valid coordinate string. |
| `buckets` | integer | No | Number of isochrone rings/buckets to return. Divides time_limit/distance_limit into intervals to create nested isochrones. Default is 1. |
| `profile` | string | Yes | Routing profile to use for calculation. Valid options: 'car', 'bike', 'foot', 'pt' (public transit). Required. |
| `time_limit` | integer | No | Maximum travel time in seconds from the start point. Either time_limit or distance_limit must be provided. Default is 600 seconds if neither is specified by the API. |
| `reverse_flow` | boolean | No | Direction of reachability calculation. False (default): areas reachable FROM the point. True: areas FROM which the point can be reached. |
| `distance_limit` | integer | No | Maximum travel distance in meters from the start point. Either time_limit or distance_limit must be provided. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Calculate Matrix

**Slug:** `GRAPHHOPPER_MATRIX_POST`

Tool to calculate distance, time, or weight matrices via POST. Use when you have multiple origins/destinations or a symmetric point set and need a single batch request.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `points` | array | No | Coordinates for symmetric matrix as [longitude, latitude]. |
| `profile` | string | Yes | Routing profile ID (e.g. 'car', 'bike', 'foot'). |
| `curbsides` | array | No | Curbside per point ('any','left','right') for symmetrical. |
| `fail_fast` | boolean | No | If false, return null for unreachable entries and include hints. |
| `to_points` | array | No | Destination coordinates as [longitude, latitude]. Provide with from_points. |
| `out_arrays` | array | Yes | Which matrices to include. |
| `from_points` | array | No | Origin coordinates as [longitude, latitude]. Provide with to_points. |
| `point_hints` | array | No | Hint per point for snapping preference (symmetrical). |
| `to_curbsides` | array | No | Curbside per destination ('any','left','right'). |
| `from_curbsides` | array | No | Curbside per origin ('any','left','right'). |
| `to_point_hints` | array | No | Hint per destination for snapping preference. |
| `from_point_hints` | array | No | Hint per origin for snapping preference. |
| `snap_preventions` | array | No | Feature types to avoid for snapping (e.g. 'toll', 'ferry'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Custom Profiles

**Slug:** `GRAPHHOPPER_PROFILES_GET`

Retrieve all custom routing profiles for your GraphHopper account. Custom profiles allow you to customize routing behavior (e.g., avoid certain roads, limit speeds, prefer certain road types). Use this tool to list available custom profiles that can be used with the Routing, Matrix, and Route Optimization APIs. Note: Custom profiles feature requires a premium GraphHopper package. If not enabled on your account, this returns an empty list.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### POST Route

**Slug:** `GRAPHHOPPER_ROUTE_POST`

Tool to calculate complex routes via POST /route. Use when you need advanced route planning with custom parameters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `debug` | boolean | No | Enable formatted debug output |
| `locale` | string | No | Locale for turn instructions |
| `points` | array | Yes | Ordered list of [lon, lat] pairs for route waypoints; at least two points required |
| `details` | array | No | List of path detail keys (e.g., 'street_name','surface','max_speed') |
| `profile` | string | Yes | Vehicle profile (e.g., 'car', 'bike', 'foot') |
| `headings` | array | No | Preferred headings in degrees; requires ch.disable=true |
| `optimize` | boolean | No | Reorder points to minimize travel time |
| `algorithm` | string ("round_trip" | "alternative_route") | No | Special routing mode; requires ch.disable=true |
| `curbsides` | array | No | Curbside to approach/leave each point |
| `elevation` | boolean | No | Include altitude in geometry |
| `ch.disable` | boolean | No | Enable flexible mode for custom_model and advanced options |
| `round_trip` | object | No | Parameters for round trip; requires algorithm='round_trip' |
| `calc_points` | boolean | No | Include full route geometry |
| `point_hints` | array | No | Optional street hints; one per point |
| `custom_model` | object | No | Custom routing rules; requires ch.disable=true |
| `instructions` | boolean | No | Include turn-by-turn instructions |
| `pass_through` | boolean | No | Avoid u-turns at via points; requires ch.disable=true |
| `points_encoded` | boolean | No | Use polyline encoding for geometry |
| `heading_penalty` | integer | No | Penalty (s) for deviating from heading; requires ch.disable=true |
| `snap_preventions` | array | No | Road types to avoid during snapping |
| `alternative_route` | object | No | Parameters for alternative routes; requires algorithm='alternative_route' |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Submit Matrix Job

**Slug:** `GRAPHHOPPER_SUBMIT_MATRIX_JOB`

Tool to submit a matrix computation job for asynchronous processing. Use for large matrices that exceed synchronous limits. Returns a job ID to retrieve results later.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `points` | array | No | Coordinates for symmetric matrix as [longitude, latitude]. |
| `profile` | string | Yes | Routing profile ID (e.g. 'car', 'bike', 'foot'). |
| `curbsides` | array | No | Curbside per point ('any','left','right') for symmetrical. |
| `fail_fast` | boolean | No | If false, return null for unreachable entries and include hints. |
| `to_points` | array | No | Destination coordinates as [longitude, latitude]. Provide with from_points. |
| `out_arrays` | array | Yes | Which matrices to include in the result. |
| `from_points` | array | No | Origin coordinates as [longitude, latitude]. Provide with to_points. |
| `point_hints` | array | No | Hint per point for snapping preference (symmetrical). |
| `to_curbsides` | array | No | Curbside per destination ('any','left','right'). |
| `from_curbsides` | array | No | Curbside per origin ('any','left','right'). |
| `to_point_hints` | array | No | Hint per destination for snapping preference. |
| `from_point_hints` | array | No | Hint per origin for snapping preference. |
| `snap_preventions` | array | No | Feature types to avoid for snapping (e.g. 'toll', 'ferry'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Map Match GPX Track

**Slug:** `GRAPHHOPPER_UPLOAD_GPX_FILE`

Map-match a GPX track using GraphHopper's Map Matching API. This tool takes GPS track points in GPX format and snaps them to the digital road network. It's useful for: - Cleaning noisy GPS data by aligning points to actual roads - Getting accurate route distances and travel times from recorded GPS tracks - Attaching road information (street names, surfaces) to GPS traces - Generating turn-by-turn instructions for recorded trips The API uses the Viterbi algorithm to find the most likely sequence of road segments that match the input GPS points, accounting for GPS measurement noise.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `locale` | string | No | Locale for turn instructions. Examples: 'en' (English), 'de' (German), 'pt_PT' (Portuguese), 'fr' (French). |
| `profile` | string | No | Routing profile for map matching. Determines which road network and speed attributes are used. Common values: 'car' (default), 'foot', 'bike', 'motorcycle'. |
| `elevation` | boolean | No | If true, include altitude (elevation) as a third coordinate in the response geometry. |
| `gpx_content` | string | Yes | GPX XML content containing GPS track points. Must be valid GPX format with at least one track segment (<trkseg>) containing track points (<trkpt> with lat/lon attributes). |
| `points_encoded` | boolean | No | If true (default), coordinates are encoded using Google's polyline algorithm. Set to false for plain GeoJSON-style coordinates. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### GraphHopper VRP POST

**Slug:** `GRAPHHOPPER_VRP_POST`

Tool to initiate VRP optimization. Use when you need to solve vehicle routing problems synchronously.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `services` | array | No | One-location service orders (pickup/delivery stops) |
| `vehicles` | array | Yes | List of at least one vehicle definition |
| `algorithm` | object | No | Deprecated – use `objectives` instead (legacy algorithms) |
| `relations` | array | No | Custom relationships (e.g., same-route grouping) |
| `shipments` | array | No | Two-location shipments with pickup and delivery |
| `objectives` | array | No | Objective functions to minimize |
| `configuration` | object | No | Routing and optimization configuration |
| `cost_matrices` | array | No | Custom time/distance matrices |
| `vehicle_types` | array | No | Definitions of vehicle types assignable via type_id |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |