POST Route Endpoint

v1.0.0

Please see the for a simpler method on how to get started. If you are familiar with POST requests and JSON then do not hesitate to continue here.

Especially when you use many locations you should get familiar with this POST endpoint as the GET endpoint has an URL length limitation. Additionally the request of this POST endpoint can be compressed and can slightly speed up the request.

To do a request you send JSON data. Both request scenarios GET and POST are identical except that all singular parameter names are named as their plural for a POST request. The effected parameters are: points, point_hints and snap_preventions.

Please note that in opposite to the GET endpoint, points are specified in the order of longitude, latitude.

For example point=10,11&point=20,22 will be converted to the points array (plural):

Note again that also the order changes from [latitude,longitude] to [longitude,latitude] similar to .

Example:

bash

curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/route?key=[YOUR_KEY]" -d '{"elevation":false,"points":[[-0.087891,51.534377],[-0.090637,51.467697]],"vehicle":"car"}'

Input

{
  "type": "object",
  "properties": {
    "algorithm": {
      "type": "string",
      "description": "Rather than looking for the shortest or fastest path, this lets you solve two different problems related to routing:\nWith `round_trip`, the route will get you back to where you started. This is meant for fun (think of\na bike trip), so we will add some randomness. This requires `ch.disable=true`.\nWith `alternative_route`, we give you not one but several routes that are close to optimal, but\nnot too similar to each other. You can control both of these features with additional parameters, see below.\n",
      "enum": [
        "round_trip",
        "alternative_route"
      ]
    },
    "alternative_route.max_paths": {
      "type": "integer",
      "format": "int32",
      "description": "If `algorithm=alternative_route`, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives.\n"
    },
    "alternative_route.max_share_factor": {
      "type": "number",
      "description": "If `algorithm=alternative_route`, this parameter specifies how similar an alternative route can be to the optimal route. Increasing can lead to worse alternatives.\n"
    },
    "alternative_route.max_weight_factor": {
      "type": "number",
      "description": "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.\n"
    },
    "avoid": {
      "type": "string",
      "description": "Specify which road classes and environments you would like to avoid.\nPossible values are `motorway`, `steps`, `track`, `toll`, `ferry`, `tunnel` and `bridge`.\nSeparate several values with `;`. Obviously not all the values make sense for all vehicle profiles e.g. `bike` is already forbidden on a `motorway`. Requires `ch.disable=true`.\n"
    },
    "block_area": {
      "type": "string",
      "description": "Block road access via a point with the format `latitude,longitude`\nor an area defined by a circle `lat,lon,radius` or a rectangle `lat1,lon1,lat2,lon2`.\nSeparate several values with `;`. Requires `ch.disable=true`.\n"
    },
    "calc_points": {
      "type": "boolean",
      "description": "If the points for the route should be calculated at all.\n"
    },
    "ch.disable": {
      "type": "boolean",
      "description": "Use this parameter in combination with one or more parameters from below.\n"
    },
    "curbsides": {
      "type": "array",
      "description": "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.",
      "items": {
        "type": "string",
        "enum": [
          "any",
          "right",
          "left"
        ]
      }
    },
    "debug": {
      "type": "boolean",
      "description": "If `true`, the output will be formatted.\n"
    },
    "details": {
      "type": "array",
      "description": "Optional parameter to retrieve path details. You can request additional details for the route: `street_name`,\n`time`, `distance`, `max_speed`, `toll`, `road_class`, `road_class_link`, `road_access`, `road_environment`, `lanes`, and `surface`. Read more about the usage of path details [here](https://discuss.graphhopper.com/t/2539).\n",
      "items": {
        "type": "string"
      }
    },
    "elevation": {
      "type": "boolean",
      "description": "If `true`, a third coordinate, the altitude, is included with all positions in the response.\nThis changes the format of the `points` and `snapped_waypoints` fields of the response, in both their\nencodings. Unless you switch off the `points_encoded` parameter, you need special code on the\nclient side that can handle three-dimensional coordinates.\nA request can fail if the vehicle profile does not support elevation. See the features object for every vehicle profile.\n"
    },
    "heading_penalty": {
      "type": "integer",
      "format": "int32",
      "description": "Time penalty in seconds for not obeying a specified heading. Requires `ch.disable=true`.\n"
    },
    "headings": {
      "type": "array",
      "description": "Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.\nIn 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.\nThis parameter also influences the tour generated with `algorithm=round_trip` and forces the initial direction.  Requires `ch.disable=true`.\n",
      "items": {
        "type": "integer",
        "format": "int32"
      }
    },
    "instructions": {
      "type": "boolean",
      "description": "If instructions should be calculated and returned\n"
    },
    "locale": {
      "type": "string",
      "description": "The locale of the resulting turn instructions. E.g. `pt_PT` for Portuguese or `de` for German.\n"
    },
    "optimize": {
      "type": "string",
      "description": "Normally, the calculated route will visit the points in the order you specified them.\nIf 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.\nKeep in mind that the limits on the number of locations of the Route Optimization API applies, and the request costs more credits.\n"
    },
    "pass_through": {
      "type": "boolean",
      "description": "If `true`, u-turns are avoided at via-points with regard to the `heading_penalty`. Requires `ch.disable=true`.\n"
    },
    "point_hints": {
      "type": "array",
      "description": "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.",
      "items": {
        "type": "string"
      }
    },
    "points": {
      "type": "array",
      "description": "The points for the route in an array of `[longitude,latitude]`. For instance, if you want to calculate a route from point A to B to C\nthen you specify `points: [ [A_longitude, A_latitude], [B_longitude, B_latitude], [C_longitude, C_latitude]]\n",
      "items": {
        "type": "array",
        "items": {
          "type": "number",
          "format": "double"
        }
      }
    },
    "points_encoded": {
      "type": "boolean",
      "description": "Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact\nbut requires special client code to unpack. (We provide it in our JavaScript client library!)\nSet this parameter to `false` to switch the encoding to simple coordinate pairs like `[lon,lat]`, or `[lon,lat,elevation]`.\nSee the description of the response format for more information.\n"
    },
    "round_trip.distance": {
      "type": "integer",
      "format": "int32",
      "description": "If `algorithm=round_trip`, this parameter configures approximative length of the resulting round trip. Requires `ch.disable=true`.\n"
    },
    "round_trip.seed": {
      "type": "integer",
      "format": "int64",
      "description": "If `algorithm=round_trip`, this sets the random seed. Change this to get a different tour for each value.\n"
    },
    "snap_preventions": {
      "type": "array",
      "description": "Optional parameter to avoid snapping to a certain road class or road environment. Current supported values `motorway`, `trunk`, `ferry`, `tunnel`, `bridge` and `ford`",
      "items": {
        "type": "string"
      }
    },
    "vehicle": {
      "type": "object"
    },
    "weighting": {
      "type": "string",
      "description": "Determines the way the ''best'' route is calculated. Default is `fastest`. Other options are `shortest` (e.g. for `vehicle=foot` or `bike`) and `short_fastest` which finds a reasonable balance between `shortest` and `fastest`. Requires `ch.disable=true`.\n"
    }
  }
}

Output

{
  "type": "object",
  "properties": {
    "info": {
      "type": "object",
      "description": "Additional information for your request",
      "properties": {
        "copyrights": {
          "type": "array",
          "description": "Attribution according to our documentation is necessary if no white-label option included.",
          "items": {
            "type": "string"
          }
        },
        "took": {
          "type": "number",
          "format": "double"
        }
      }
    },
    "paths": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ascend": {
            "type": "number",
            "format": "double",
            "description": "The total ascent, in meters.\n"
          },
          "bbox": {
            "type": "array",
            "description": "The bounding box of the route geometry. Format: `[minLon, minLat, maxLon, maxLat]`.\n",
            "items": {
              "type": "number",
              "format": "double"
            }
          },
          "descend": {
            "type": "number",
            "format": "double",
            "description": "The total descent, in meters.\n"
          },
          "details": {
            "type": "object",
            "description": "Details, as requested with the `details` parameter. Consider the value `{\"street_name\": [[0,2,\"Frankfurter Straße\"],[2,6,\"Zollweg\"]]}`.\nIn this example, the route uses two streets: The first, Frankfurter Straße, is\nused between `points[0]` and `points[2]`, and the second, Zollweg, between `points[2]` and `points[6]`.\nSee [here](https://discuss.graphhopper.com/t/2539) for discussion.\n"
          },
          "distance": {
            "type": "number",
            "format": "double",
            "description": "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/).\n"
          },
          "instructions": {
            "type": "array",
            "description": "The instructions for this route. This feature is under active development, and our instructions can sometimes be misleading,\nso be mindful when using them for navigation.\n",
            "items": {
              "type": "object",
              "properties": {
                "distance": {
                  "type": "number",
                  "format": "double",
                  "description": "The distance for this instruction, in meters.\n"
                },
                "exit_number": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Only available for roundabout instructions (sign is 6). The count of exits at which the route leaves the roundabout.\n"
                },
                "interval": {
                  "type": "array",
                  "description": "Two indices into `points`, referring to the beginning and the end of the segment of the route\nthis instruction refers to.\n",
                  "items": {
                    "type": "integer",
                    "format": "int32"
                  }
                },
                "sign": {
                  "type": "integer",
                  "format": "int32",
                  "description": "A number which specifies the sign to show:\n\n| sign | description  |\n|---|---|\n|-98| an U-turn without the knowledge if it is a right or left U-turn |\n| -8| a left U-turn |\n| -7| keep left |\n| -6| **not yet used**: leave roundabout |\n| -3| turn sharp left |\n| -2| turn left |\n| -1| turn slight left |\n|  0| continue on street |\n|  1| turn slight right |\n|  2| turn right |\n|  3| turn sharp right |\n|  4| the finish instruction before the last point |\n|  5| the instruction before a via point |\n|  6| the instruction before entering a roundabout |\n|  7| keep right |\n|  8| a right U-turn |\n|  *| **For future compatibility** it is important that all clients are able to handle also unknown instruction sign numbers\n"
                },
                "street_name": {
                  "type": "string",
                  "description": "The name of the street to turn onto in order to follow the route.\n"
                },
                "text": {
                  "type": "string",
                  "description": "A description what the user has to do in order to follow the route. The language depends on the locale parameter.\n"
                },
                "time": {
                  "type": "integer",
                  "format": "int32",
                  "description": "The duration for this instruction, in milliseconds.\n"
                },
                "turn_angle": {
                  "type": "number",
                  "format": "double",
                  "description": "Only available for roundabout instructions (sign is 6). The radian of the route within the roundabout `0 < r < 2*PI` for clockwise and\n`-2*PI < r < 0` for counterclockwise turns.\n"
                }
              }
            }
          },
          "points": {
            "type": "object"
          },
          "points_encoded": {
            "type": "boolean",
            "description": "Whether the `points` and `snapped_waypoints` fields are polyline-encoded strings rather than JSON arrays\nof coordinates. See the field description for more information on the two formats.\n"
          },
          "points_order": {
            "type": "array",
            "description": "An array of indices (zero-based), specifiying the order in which the input points are visited.\nOnly present if the `optimize` parameter was used.\n",
            "items": {
              "type": "integer"
            }
          },
          "snapped_waypoints": {
            "type": "object"
          },
          "time": {
            "type": "integer",
            "format": "int64",
            "description": "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/).\n"
          }
        }
      }
    }
  }
}