# Calculate a route

For the GET request you specify the parameters in the URL and can try it directly in every browser.
However, it has some disadvantages when using many points (URL length limit) and the custom_model Feature cannot be used. 
Therefore, our recommended endpoint is the POST route endpoint.

Endpoint: GET /route
Version: 1.0.0
Security: key

## Query parameters:

  - `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 for more details and valid profile values.

  - `point` (array, required)
    The points for which the route should be calculated. Format: latitude,longitude. Specify at least an origin and a destination. Via points are possible.
The maximum number depends on your plan.
    Example: ["51.131,12.414","48.224,3.867"]

  - `point_hint` (array)
    The point_hint is typically a road name to which the associated point parameter should be snapped to. Specify no point_hint parameter or the same number as you have point parameters.

  - `snap_prevention` (array)
    Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the point parameter. The snap_prevention parameter allows you to prevent snapping to specific types of roads. For example, if snap_prevention is set to bridge, the routing engine will avoid snapping to a bridge, even if it is the closest road for the given point. Current supported values: motorway, trunk, ferry, tunnel, bridge and ford. Multiple values are specified like snap_prevention=ferry&snap_prevention=motorway. 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.

  - `curbside` (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 vehicles 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.

  - `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.

  - `heading` (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 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.