How to import a route from traces

The Route Import service is a REST API that accepts GPS trace points and sub-set of routing parameters. The resulting response will contain a list of routes, which can then be used to consume additional map attributes on the driven path and other parameters such as ETA, traffic incidents, etc.

Supported use cases

Enables bringing external routes to HERE platform
Exposes illegal driving maneuvers, truck restrictions, energy consumption and provides route information for post trip analysis and cost

Trace frequency

For best results, use 1Hz GPS data or any points that have a spacing of a few meters between them. For traces with less frequent points, the Route Import service will attempt to create an approximate reconstruction. In some situations, when consecutive points are too far apart (more than about 30 kilometers of on-road distance), they could be considered unreachable and one of them could fail to be matched.

Waypoint support

The Route Import service supports waypoints. Imported routes will have user-specified waypoints, which you can use for voice guidance and to specify maneuvers.
Waypoints are defined by an index to a trace point and have no lat/lon coordinates.
If waypoint referring to a trace point isn't matched, then this waypoint is referred to the next matched trace point along with an according notice in the route response.
If the resulting route doesn't match all trace points, then notice that the split route is added in the route response.
The Route Import service doesn't support attributes that influence the route shape but does provide support for stopDuration.

Limitations

Minimum number of GPS trace points accepted in the request is 2 and maximum is 50000.
Post body size limit is 10MiB.
For trace point matching, the Route Import service doesn't consider segments closed for cars.
Route Import service has limited support for U-Turns on two-way streets without dividers. If the traces include a U-Turn by the vehicle, the service will split the route into different sections when the change in direction is identified.
Tolls aren't available directly in route import service. See this tutorial for information on how to retrieve toll cost when using route import.

Sample requests

A Route Import request with a non-drivable link results in split sections.

curl -gX POST 'https://router.hereapi.com/v8/import?'\
'return=polyline,summary&'\
'transportMode=car&'\
'apiKey=YOUR_API_KEY' \
  -H 'Content-Type: application/json' -d '
{
  "trace": [
    {
      "lat": 52.541121,
      "lng": 13.278989
    },
    {
      "lat": 52.541338,
      "lng": 13.276435
    },
    {
      "lat": 52.544976,
      "lng": 13.276273
    },
    {
      "lat": 52.546982,
      "lng": 13.275723
    },
    {
      "lat": 52.548535,
      "lng": 13.276305
    },
    {
      "lat": 52.548535,
      "lng": 13.27873
    }
  ]
}
'

The resulting response splits the route into multiple sections:

{
  "notices": [
    {
      "title": "Import: Provided trace could not be matched into a continuous route.\nSome trace points were unmatched.",
      "code": "importSplitRoute",
      "severity": "info"
    }
  ],
  "routes": [
    {
      "id": "5129a87e-fe4c-4a0f-bcc6-a17b4d7a3229",
      "sections": [
        {
          ...,
          "summary": {
            "duration": 14,
            "length": 175,
            "baseDuration": 12
          },
          "polyline": "BGir7mkDywvqZ-FhlC8BvR8BjSsEvlBkCzQ",
          "language": "en-us",
          "transport": {
            "mode": "car"
          }
        },
        {
          ...,
          "summary": {
            "duration": 12,
            "length": 165,
            "baseDuration": 12
          },
          "polyline": "BG87pnkDipqqZ_Bq1ClBkiC",
          "language": "en-us",
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}

This is a Route Import request with an invalid transport mode.

curl -gX POST 'https://router.hereapi.com/v8/import?'\
'return=polyline,summary&'\
'transportMode=pedestrian&'\
'apiKey=YOUR_API_KEY' \
  -H 'Content-Type: application/json' -d '
{
  "trace": [
    {
      "lat": 19.040871,
      "lng": 72.81978
    },
    {
      "lat": 19.041056,
      "lng": 72.820037
    },
    {
      "lat": 19.041229,
      "lng": 72.820354
    },
    {
      "lat": 19.041366,
      "lng": 72.82063
    },
    {
      "lat": 19.041548,
      "lng": 72.821042
    }
  ]
}
'

The resulting response will return an error since the specified transport mode isn't valid for the given traces.

{
  "notices": [
    {
      "title": "Route handle decoding failed due to forbidden segments for the specified transport mode.",
      "code": "violatedTransportModeInRouteHandleDecoding",
      "severity": "critical"
    }
  ],
  "routes": []
}

This request demonstrates handling of restrictions for motorized vehicles (car, truck, scooter, bus, taxi).

Route Import service allows "soft handling of restrictions" when requested for motorized vehicles.

curl -gX POST 'https://router.hereapi.com/v8/import?'\
'return=polyline,summary&'\
'transportMode=truck&'\
'apiKey=YOUR_API_KEY' \
  -H 'Content-Type: application/json' -d '
{
  "trace": [
    {
      "lat": 52.503323,
      "lng": 13.211876
    },
    {
      "lat": 52.501416,
      "lng": 13.210769
    },
    {
      "lat": 52.500363,
      "lng": 13.2089
    },
    {
      "lat": 52.499144,
      "lng": 13.206339
    },
    {
      "lat": 52.497466,
      "lng": 13.203929
    },
    {
      "lat": 52.496107,
      "lng": 13.200937
    },
    {
      "lat": 52.495536,
      "lng": 13.200078
    },
    {
      "lat": 52.494839,
      "lng": 13.199987
    }
  ]
}
'

The response will return a route and a critical notice at a section level mentioning the violation.

{
  "routes": [
    {
      "id": "396a7129-4edc-4a85-91a1-abe62ae7092c",
      "sections": [
        {
          ...,
          "summary": {
            "duration": 363,
            "length": 1303,
            "baseDuration": 363
          },
          "polyline": "BG0xxkkD2ssmZjZ2DrJUrJnBjN3D3NvHrOjNjNjSjwBvyCzKvRvRnf_YrxBrnBv3CzFnLnGzK_iB_2BjDrEnG3I7GjInavgB_JvM_J3N3IrOjInQz8BnoE7G_O7GrOvMvW7aztB3DrErErE7LjI_E7BjNT5MqI",
          "notices": [
            {
              "title": "Violated vehicle restriction.",
              "code": "violatedVehicleRestriction",
              "severity": "critical"
            }
          ],
          "language": "en-us",
          "transport": {
            "mode": "truck"
          }
        }
      ]
    }
  ]
}

This request demonstrates handling of restrictions for pedestrian and bicycle mode.

In pedestrian and bicycle mode, when route import is requested and some segments aren't allowed for this mode,then the calculation ignores route shape and returns an error message that explains the transport mode violation.

curl -gX POST 'https://router.hereapi.com/v8/import?'\
'return=polyline,summary&'\
'transportMode=pedestrian&'\
'apiKey=YOUR_API_KEY' \
  -H 'Content-Type: application/json' -d '
{
  "trace": [
    {
      "lat": 19.05962,
      "lng": 72.846409
    },
    {
      "lat": 19.059171,
      "lng": 72.846397
    },
    {
      "lat": 19.058749,
      "lng": 72.846392
    },
    {
      "lat": 19.058333,
      "lng": 72.846392
    }
  ]
}
'

{
  "notices": [
    {
      "title": "Route handle decoding failed due to forbidden segments for the specified transport mode.",
      "code": "violatedTransportModeInRouteHandleDecoding",
      "severity": "critical"
    }
  ],
  "routes": []
}

This request demonstrates the support of waypoints

Define a waypoint by setting an index in the tracepoint. The resulting response splits the route into multiple sections.

curl -gX POST 'https://router.hereapi.com/v8/import?'\
'return=polyline,summary&'\
'transportMode=car&'\
'apiKey=YOUR_API_KEY' \
  -H 'Content-Type: application/json' -d '
{
  "trace": [
    {
      "lat": 52.533318,
      "lng": 13.352151
    },
    {
      "lat": 52.533903,
      "lng": 13.353281
    },
    {
      "lat": 52.534498,
      "lng": 13.354426
    }
  ],
  "via": [
    {
      "index": 1,
      "stopDuration": 3600
    }
  ]
}
'

The resulting response splits the route into multiple sections.

{
  "routes": [
    {
      "id": "3ff638c7-dd97-46d0-8efa-ae482b3d64ea",
      "sections": [
        {
          ...,
          "postActions": [
            {
              "action": "wait",
              "duration": 3600
            }
          ],
          ...,
          "summary": {
            "duration": 3614,
            "length": 101,
            "baseDuration": 8
          },
          "polyline": "BG4jsmkDou-uZwTwmBwQ-gB",
          "language": "en-us",
          "transport": {
            "mode": "car"
          }
        },
        {
          ...,
          "summary": {
            "duration": 13,
            "length": 102,
            "baseDuration": 9
          },
          "polyline": "BG4ntmkD21gvZ0aq1B2JsT",
          "language": "en-us",
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}