# Calculate a route

This POST endpoint accepts routing requests as JSON and returns the computed route as JSON. It offers a high degree of customization through the custom model to account for 
vehicle constraints such as height or weight, avoidance or exclusion of specific areas. It also provids rich route information including elevation data, turn-by-turn instructions,
toll information, and other detailed path details.

Endpoint: POST /route
Version: 1.0.0
Security: 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 query points used to calculate the route, requiring at least a start and a destination point, with optional via-points in between.
    Example: [[11.539421,48.118477],[11.559023,48.12228]]

  - `point_hints` (array)
    Optional parameter. Specifies a hint for each point in the points 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 points array. The snap_preventions array allows you to prevent snapping to specific types of roads. For example, if the array includes bridge, 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 custom_model.
    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. pt_PT for Portuguese or de for German.

  - `elevation` (boolean)
    If true, a third coordinate, the altitude, is included with all positions in the response.
This changes the format of the points and snapped_waypoints fields of the response, in both their
encodings. Unless you switch off the points_encoded 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: 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. 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 "true" 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 true, 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 false to switch the encoding to simple coordinate pairs like [lon,lat], or [lon,lat,elevation].
See the description of the response format for more information.

  - `ch.disable` (boolean)
    Use true to enable the flexible mode to use the custom_model or any of the following options 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 "ch.disable": true parameter which is required to make use of custom_model.

json
{
  "points": [
    [
      13.31543,
      52.509535
    ],
    [
      13.29779,
      52.512434
    ]
  ],
  "profile": "car",
  "ch.disable": true,
  "custom_model": {
    "speed": [
      {
        "if": "true",
        "limit_to": "100"
      }
    ],
    "priority": [
      {
        "if": "road_class == MOTORWAY",
        "multiply_by": "0"
      }
    ],
    "distance_influence": 100
  }
}

  - `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 headings parameter also influences the tour generated with algorithm=round_trip and forces the initial direction.  Requires ch.disable=true.

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

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

  - `algorithm` (string)
    Rather than looking for the shortest or fastest path, this parameter lets you solve two different problems related to routing:
With alternative_route, we give you not one but several routes that are close to optimal, but
not too similar to each other. 
With round_trip, 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.
You can control both of these features with additional parameters, see below.
    Enum: "round_trip", "alternative_route"

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

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

  - `alternative_route.max_paths` (integer)
    If algorithm=alternative_route, 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 algorithm=alternative_route, 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 algorithm=alternative_route, 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 points_encoded.

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

  - `paths.points_encoded` (boolean)
    Whether the points and snapped_waypoints 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: [minLon, minLat, maxLon, maxLat].

  - `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.heading` (number)
    The optional heading for this roundabout instruction.

  - `paths.instructions.last_heading` (number)
    The optional last heading for this roundabout instruction.

  - `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 points, 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| not yet used: 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 |
|  *| For future compatibility 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 0 < r < 2*PI for clockwise and
-2*PI < r < 0 for counterclockwise turns.

  - `paths.details` (object)
    Details, as requested with the details parameter. Consider the value {"street_name": [[0,2,"Frankfurter Straße"],[2,6,"Zollweg"]]}.
In this example, the route uses two streets: The first, Frankfurter Straße, is
used between points[0] and points[2], and the second, Zollweg, between points[2] and points[6].
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 optimize 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.