# Calculate a route

To do a request you send JSON data. 

See the GET endpoint for an alternative query method which is slightly simpler to get started but has some disadvantages.

 and some parameter names use the plural.
For example the string  will be converted to the  array (plural):

So this  array uses a format similar to GeoJson.

Example:



Endpoint: POST /route
Version: 1.0.0
Security: api_key

## Request fields (application/json):

  - `profile` (string)
    The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about [routing profiles](#tag/Map-Data-and-Routing-Profiles) for more details and valid profile values.
    Example: "bike"

  - `points` (array)
    The points for the route in an array of . For instance, if you want to calculate a route from point A to B to C
then you specify `points: [ [A_longitude, A_latitude], [B_longitude, B_latitude], [C_longitude, C_latitude]]
    Example: [[11.539421,48.118477],[11.559023,48.12228]]

  - `point_hints` (array)
    Optional parameter. Specifies a hint for each point in the  array to prefer a certain street for the closest location lookup. E.g. if there is an address or house with two or more neighboring streets you can control for which street the closest location is looked up. Make sure you do not include the house number of city name and only the street name to improve the quality of the matching.
    Example: ["Lindenschmitstraße","Thalkirchener Str."]

  - `snap_preventions` (array)
    Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the  array. The  array allows you to prevent snapping to specific types of roads. For example, if the array includes , then the routing engine will avoid snapping to a bridge, even if it is the closest road for the given point. Note that once snapped the routing algorithm can still route over bridges (or the other values). To avoid this you need to use the .
    Enum: "motorway", "trunk", "bridge", "ford", "tunnel", "ferry"

  - `curbsides` (array)
    Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicle profiles and OpenStreetMap.
    Enum: "any", "right", "left"

  - `locale` (string)
    The locale of the resulting turn instructions. E.g.  for Portuguese or  for German.

  - `elevation` (boolean)
    If , a third coordinate, the altitude, is included with all positions in the response.
This changes the format of the  and  fields of the response, in both their
encodings. Unless you switch off the  parameter, you need special code on the
client side that can handle three-dimensional coordinates.

  - `details` (array)
    Optional parameter. The following path details are available: , , , , , , , , , ,
, , , , , , , , , , 
, , , , , , . Read more about the usage of path details [here](https://discuss.graphhopper.com/t/2539).
    Example: ["road_class","surface"]

  - `optimize` (string)
    Normally, the calculated route will visit the points in the order you specified them.
If you have more than two points, you can set this parameter to  and the points may be re-ordered to minimize the total travel time.
Keep in mind that the limits on the number of locations of the Route Optimization API applies, and the request costs more credits.

  - `instructions` (boolean)
    If instructions should be calculated and returned

  - `calc_points` (boolean)
    If the points for the route should be calculated at all.

  - `debug` (boolean)
    If , the output will be formatted.

  - `points_encoded` (boolean)
    Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact
but requires special client code to unpack. (We provide it in our JavaScript client library!)
Set this parameter to  to switch the encoding to simple coordinate pairs like , or .
See the description of the response format for more information.

  - `ch.disable` (boolean)
    Use this parameter in combination with one or more parameters from below.

  - `custom_model` (object)
    The custom_model modifies the routing behaviour of the specified profile. See the [detailed documentation](#tag/Custom-Model). 
Below is a complete request example in Berlin that limits all speeds to 100km/h, excludes motorways and makes shorter routes a bit more likely than the default due to a higher distance_influence. 
Note that it also includes the  parameter which is required to make use of .

  - `custom_model.speed` (array)
    See [speed customization](#tag/Custom-Model/Customizing-speed)

  - `custom_model.priority` (array)
    See [priority customization](#tag/Custom-Model/Customizing-priority)

  - `custom_model.distance_influence` (number)
    Use higher values to prefer shorter routes. See [here](#tag/Custom-Model/Customizing-distance_influence) for more details.

  - `custom_model.areas` (object)
    Areas are given in a GeoJson format as FeatureCollection. See more details and an example [here](#tag/Custom-Model/Define-areas).

  - `custom_model.areas.type` (string)
    Enum: "FeatureCollection"

  - `custom_model.areas.features` (array)
    A FeatureCollection is an array of type "Feature" from GeoJSON

  - `custom_model.areas.features.geometry` (object)

  - `custom_model.areas.features.geometry.coordinates` (array)

  - `headings` (array)
    Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.
In this case headings are associated by their order to the specific points. Headings are given as north based clockwise angle between 0 and 360 degree.
This parameter also influences the tour generated with  and forces the initial direction.  Requires .

  - `heading_penalty` (integer)
    Time penalty in seconds for not obeying a specified heading. Requires .

  - `pass_through` (boolean)
    If , u-turns are avoided at via-points with regard to the . Requires .

  - `algorithm` (string)
    Rather than looking for the shortest or fastest path, this parameter lets you solve two different problems related to routing:
With , we give you not one but several routes that are close to optimal, but
not too similar to each other. 
With , the route will get you back to where you started. This is meant for fun (think of
a bike trip), so we will add some randomness. The  option requires .
You can control both of these features with additional parameters, see below.
    Enum: "round_trip", "alternative_route"

  - `round_trip.distance` (integer)
    If , this parameter configures approximative length of the resulting round trip. Requires .

  - `round_trip.seed` (integer)
    If , this sets the random seed. Change this to get a different tour for each value.

  - `alternative_route.max_paths` (integer)
    If , this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives.

  - `alternative_route.max_weight_factor` (number)
    If , this parameter sets the factor by which the alternatives routes can be longer than the optimal route. Increasing can lead to worse alternatives.

  - `alternative_route.max_share_factor` (number)
    If , this parameter specifies how similar an alternative route can be to the optimal route. Increasing can lead to worse alternatives.

## Response 200 fields (application/json):

  - `paths` (array)

  - `paths.distance` (number)
    The total distance, in meters. To get this information for one 'leg' please read [this blog post](https://www.graphhopper.com/blog/2019/11/28/routing-api-using-path-details/).

  - `paths.time` (integer)
    The total travel time, in milliseconds. To get this information for one 'leg' please read [this blog post](https://www.graphhopper.com/blog/2019/11/28/routing-api-using-path-details/).

  - `paths.ascend` (number)
    The total ascent, in meters.

  - `paths.descend` (number)
    The total descent, in meters.

  - `paths.points` (any)
    The geometry of the route. The format depends on the value of .

  - `paths.snapped_waypoints` (any)
    The snapped input points. The format depends on the value of .

  - `paths.points_encoded` (boolean)
    Whether the  and  fields are polyline-encoded strings rather than JSON arrays
of coordinates. See the field description for more information on the two formats.

  - `paths.bbox` (array)
    The bounding box of the route geometry. Format: .

  - `paths.instructions` (array)
    The instructions for this route. This feature is under active development, and our instructions can sometimes be misleading,
so be mindful when using them for navigation.

  - `paths.instructions.text` (string)
    A description what the user has to do in order to follow the route. The language depends on the locale parameter.

  - `paths.instructions.street_name` (string)
    The name of the street to turn onto in order to follow the route.

  - `paths.instructions.distance` (number)
    The distance for this instruction, in meters.

  - `paths.instructions.time` (integer)
    The duration for this instruction, in milliseconds.

  - `paths.instructions.interval` (array)
    Two indices into , referring to the beginning and the end of the segment of the route
this instruction refers to.

  - `paths.instructions.sign` (integer)
    A number which specifies the sign to show:

| sign | description  |
|---|---|
|-98| an U-turn without the knowledge if it is a right or left U-turn |
| -8| a left U-turn |
| -7| keep left |
| -6| : leave roundabout |
| -3| turn sharp left |
| -2| turn left |
| -1| turn slight left |
|  0| continue on street |
|  1| turn slight right |
|  2| turn right |
|  3| turn sharp right |
|  4| the finish instruction before the last point |
|  5| the instruction before a via point |
|  6| the instruction before entering a roundabout |
|  7| keep right |
|  8| a right U-turn |
|  *|  it is important that all clients are able to handle also unknown instruction sign numbers

  - `paths.instructions.exit_number` (integer)
    Only available for roundabout instructions (sign is 6). The count of exits at which the route leaves the roundabout.

  - `paths.instructions.turn_angle` (number)
    Only available for roundabout instructions (sign is 6). The radian of the route within the roundabout  for clockwise and
 for counterclockwise turns.

  - `paths.details` (object)
    Details, as requested with the  parameter. Consider the value .
In this example, the route uses two streets: The first, Frankfurter Straße, is
used between  and , and the second, Zollweg, between  and .
Read more about the usage of path details [here](https://discuss.graphhopper.com/t/2539).

  - `paths.points_order` (array)
    An array of indices (zero-based), specifiying the order in which the input points are visited.
Only present if the  parameter was used.

  - `info` (object)
    Additional information for your request

  - `info.copyrights` (array)
    Attribution according to our documentation is necessary if no white-label option included.

  - `info.took` (number)

## Response 400 fields (application/json):

  - `message` (string)

  - `hints` (array)
    Optional error information.

## Response 401 fields (application/json):

  - `message` (string)

  - `hints` (array)
    Optional error information.

## Response 429 fields (application/json):

  - `message` (string)

  - `hints` (array)
    Optional error information.

## Response 500 fields (application/json):

  - `message` (string)

  - `hints` (array)
    Optional error information.