Skip to main content
APIs 4 min read

How the HERE Route Matching API Turns GPS Traces into Meaningful Routes

HERE Route Matching API Hero Image

The HERE Route Matching API v8 enables developers to precisely match GPS traces to real-world road networks, opening possibilities for risk analysis, driving analytics, and reporting. It takes a series of GPS points (trace) and identifies the most likely road route on HERE's global maps. It determines which road link is associated with each point, its position in relation to the map link geometry and the direction of travel along this link. Once this information is available, applications can determine if a driver stayed on the expected route, or if they were obeying the speed limit, one-ways, truck restrictions, illegal access, turns, vehicle weight violations and other traffic rules. It supports post-analysis and near real-time usage. 

Key use cases

Let’s dig into the primary HERE Route Matching API use cases:

  1. Driver Job Analysis: Monitor driver behavior for delivery drivers, long-haul truckers, construction drivers; identify risks or inefficient routes, and optimize logistics efficiency.
  2. Post Trip Analysis: Efficiency, risk assessment, compliance
  3. Usage-Based Insurance: Accurately assess driving risks and tailor insurance premiums based on route-specific insights.

Supported GPS Formats

The HERE Route Matching API supports various trace file formats to upload GPS data:

  1. CSV: Simple text format with latitude, longitude, and optional timestamps, speeds, headings, and elevations.
  2. GPX: Popular GPS exchange format with coordinates, timestamps, and additional elements like elevation and speed.
  3. NMEA: Standard for marine navigation, uses specific sentences like $GPRMC for position and speed.
  4. KML: Google's format for geospatial data, supports points and linestrings for trace representations.

Understanding the API Request

The basic HERE Routing Matching API request is: 


In Postman, the GPS trace is added in the Body section of the request. In this example, I have used contents of a CSV format GPS trace.

Route matching api request postman

More parameters can be explored in the API reference

Understanding the API Response

The response from HERE Route Matching API is in JSON format and has three keys – route, warnings, and language. The first route alternative is the one with minimum cost. Warnings are globally for the request or apply for the first route alternative. 

For each trace point, the most probable map matched position is returned along with a confidence value. A fully drivable route path is returned without any gaps, including link ids, driving direction and confidence value. Depending on the confidence value, the matched road link can be skipped or ignored for different use cases. 

    "response": {
        "route": [
                "mode": {
                    "type": "matched",
                    "transportModes": [
                    "trafficMode": "disabled"
                "waypoint": [
                        "linkId": "+565942252",
                        "mappedPosition": {
                            "latitude": 53.37371,
                            "longitude": -1.47049
                        "originalPosition": {
                            "latitude": 53.3737131,
                            "longitude": -1.4704939
                        "spot": 0.15965,
                        "confidenceValue": 1.0,
                        "elevation": 0.0,
                        "headingDegreeNorthClockwise": 10000.0,
                        "headingMatched": 69.0,
                        "matchDistance": 0.03,
                        "minError": 0.0,
                        "routeLinkSeqNrMatched": 0,
                        "speedMps": 0.0,
                        "timestamp": 0
                    ... // MORE WAYPOINTS
                "boatFerry": false,
                "railFerry": false,
                "leg": [   // one leg traverses between two mandatory stopover waypoints
                        "length": 19664,
                        "travelTime": 1662,
                        "link": [
                                "linkId": "565942252",
                                "length": 149.11,
                                "remainDistance": 19664,
                                "remainTime": 1662,
                                "shape": [
                                "functionalClass": 5,
                                "confidence": 1.0,
                                "segmentRef": "$0:20805375:$1:163827327#-0.19411..1"
                            ... // MORE LINKS
                        "trafficTime": 1662,
                        "baseTime": 1662,
                        "refReplacements": {
                            "0": ":1705790704033:",
                            "1": "here:cm:segment"
                "summary": {
                    "travelTime": 1662,
                    "distance": 19664,
                    "baseTime": 1662,
                    "trafficTime": 1662,
                    "flags": []
        "warnings": [
                "message": "Ignoring way point #50 53.38298303/-1.461404355 because it appears to be out of sequence",
                "code": 1006, // Classification of warning events
                "routeLinkSeqNum": -1, // the road segment (Link) in "RouteLinks" where the warning event occurred
                "tracePointSeqNum": 50 // the first trace point in "TracePoints" where the warning event occurred. 
            ... // MORE WARNINGS
        "language": "en-us"

See the RESPONSE SCHEMA section in the API reference for detailed explanation. 


When you need to extract valuable insights from GPS traces, the HERE Route Matching API v8 is your powerful solution. No matter what transport type is being used: cars, trucks or even pedestrians, the HERE Route Matching API is flexible enough to support a variety of input and output formats and deliver detailed, meaningful response. Explore the full sample for HERE Route Matching (HERE platform login required) to try out different input formats and attributes.

Mohini Todkari

Mohini Todkari

Sr. Developer Evangelist

Have your say

Sign up for our newsletter

Why sign up:

  • Latest offers and discounts
  • Tailored content delivered weekly
  • Exclusive events
  • One click to unsubscribe