Map-match a GPX file

v1.0.0

Example

You get an example response for a GPX via:

A minimal working GPX file looks like

Introduction

The Map Matching API is part of the GraphHopper Directions API and with this API you can snap measured GPS points typically as GPX files to a digital road network to e.g. clean data or attach certain data like elevation or turn instructions to it. Read more at Wikipedia.

In the example screenshot above and demo you see the Map Matching API in action where the black line is the GPS track and the green one is matched result.

Most of the times, you can simply POST a GPX file, but some of the request parameters of the apply here, too.

API Clients and Examples

See the section in the main documentation, and .

Limits and Counts

The cost for one request depends on the number of GPS location and is documented .

One request should not exceed the Map Matching API location limit depending on the package, see the pricing in our dashboard.

Input

{
  "type": "object",
  "properties": {
    "gps_accuracy": {
      "type": "integer"
    },
    "vehicle": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

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"
          }
        }
      }
    }
  }
}