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

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:

Driver Job Analysis: Monitor driver behavior for delivery drivers, long-haul truckers, construction drivers; identify risks or inefficient routes, and optimize logistics efficiency.
Post Trip Analysis: Efficiency, risk assessment, compliance
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:

CSV: Simple text format with latitude, longitude, and optional timestamps, speeds, headings, and elevations.
GPX: Popular GPS exchange format with coordinates, timestamps, and additional elements like elevation and speed.
NMEA: Standard for marine navigation, uses specific sentences like $GPRMC for position and speed.
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:

Copied

        POST https://routematching.hereapi.com/v8/match/routelinks?routeMatch=1&mode=fastest;car;traffic:disabled&apiKey={{REST_API_KEY}}

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.

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.

Copied

        {
    "response": {
        "route": [
            {
                "mode": {
                    "type": "matched",
                    "transportModes": [
                        "car"
                    ],
                    "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": [
                                    53.37371,
                                    -1.47049,
                                    53.37377,
                                    -1.47025,
                                    53.37385,
                                    -1.46982,
                                    53.37412,
                                    -1.46836
                                ],
                                "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.

Conclusion

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.