How to match GPS traces to the most probable route

HERE Route Matching API v8 reconstructs the most probable route driven from a GPS trace. It accounts for typical GPS inaccuracies and handles gaps in the trace data. For information about supported input formats and accuracy requirements, see GPS trace file formats and accuracy requirements.

You can enrich the map-matched trace with HERE map attributes, such as speed limits, slope, curvature, motorway/inside-city classification, number of lanes, and traffic or weather conditions. The API includes these attributes directly in the route match response.

You can also use Route Matching API v8 to learn a driver's daily commute paths. Store the resulting route as a set of waypoints, then send that path to HERE Routing API v8 each day to get the driving time under current traffic conditions and any incidents along the route. This lets you alert drivers when they should depart earlier than usual, or confirm that conditions are normal.

Send the request

The following request matches a GPS trace to the most probable route. Replace PATH_TO_GPS_TRACE_FILE with the path to a GPS trace file in GPX format, and API_KEY with your HERE API key.

curl -X POST \
  -H "Content-Type: application/json" \
  --data-binary @PATH_TO_GPS_TRACE_FILE \
  'https://routematching.hereapi.com/v8/match/routelinks?'\
'routeMatch=1&'\
'mode=fastest;car;traffic:disabled&'\
'legal=access,oneway,thrutraf,turn&'\
'attributes=LINK_FCn(REF_NODE_NEIGHBOR_LINKS,NONREF_NODE_NEIGHBOR_LINKS)&'\
'apiKey=API_KEY'

The request uses the following key parameters:

• routeMatch=1: Enables route matching mode. The API treats the request body as a GPS trace and computes the most probable driven path.
• mode=fastest;car;traffic:disabled: Sets the vehicle type to car and disables real-time traffic.
• legal=access,oneway,thrutraf,turn: Restricts the matched route to links that comply with access, one-way, through-traffic, and turn restrictions.
• attributes=LINK_FCn(REF_NODE_NEIGHBOR_LINKS,NONREF_NODE_NEIGHBOR_LINKS): Requests the neighboring links at each end of a matched link.

Use POST requests for large traces. Load balancers impose request-line length limits on GET requests, so use POST instead. Send the trace data in the request body, and keep authentication and configuration parameters, such as routeMatch, mode, and attributes, in the query string.

You can also send the trace as a plain list of coordinates using the application/octet-stream content type. The following example sends a CSV file named routelinks.csv:

curl -X POST \
  -H "Content-Type: application/octet-stream" \
  --data-binary @routelinks.csv \
  'https://routematching.hereapi.com/v8/match/routelinks?'\
'routeMatch=1&'\
'mode=fastest;car;traffic:disabled&'\
'attributes=ROUNDABOUT_FCn(*)&'\
'apiKey=API_KEY'

The routelinks.csv file contains a header row followed by latitude and longitude pairs:

LATITUDE,LONGITUDE
60.1553,24.66346
60.16366,24.73282

Read the response

The response shows the route calculated from the GPS trace, along with a list of warnings for specific route links. An example warning message:

Gate traversal onto link 786918237

For more information about response formats, see GPS trace file formats and accuracy requirements.

Try it

Explore this use case without writing code. See the interactive demo at https://demo.support.here.com/examples/v3/rme_daily_commute.

1. Open the demo link.
2. Provide a list of points and speed limits, upload a trace file in CSV, GPX, or NMEA format, or insert trace data by clicking directly on the map.
3. The demo displays the route calculated by HERE Route Matching API v8 from the trace in green, and the route calculated by HERE Routing API v8 underneath it in red, together with live traffic or guidance information where available.