Route Import

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 is not 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 does not support attributes that influence the route shape but does provide support for stopDuration.

Limitations

  1. Minimum number of GPS trace points accepted in the request is 2 and maximum is 50000.
  2. Post body size limit is 10MiB.
  3. For trace point matching, the Route Import service does not consider segments closed for cars.
  4. Route Import service is not supported for pedestrian, bicycle and scooter transport modes.

Sample Requests :

  1. A Route Import request with a non-drivable link results in split sections.
curl -X POST \
  'https://router.hereapi.com/v8/import?apikey={YOUR_API_KEY}&return=polyline,summary,actions,instructions,routeHandle&transportMode=car'
  {
  "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": [{
            "id": "9b234180-79e7-4fc3-8b18-7b64ec8cf311",
            "type": "vehicle",
            "actions": [{
                "action": "depart",
                "duration": 14,
                "length": 175,
                "instruction": "Head west on Heckerdamm. Go for 175 m.",
                "offset": 0
            }, {
                "action": "arrive",
                "duration": 0,
                "length": 0,
                "instruction": "Arrive at Heckerdamm.",
                "offset": 5
            }],
            "departure": {
                "time": "2022-01-11T15:33:26+01:00",
                "place": {
                    "type": "place",
                    "location": {
                        "lat": 52.5411052,
                        "lng": 13.2789851
                    },
                    "originalLocation": {
                        "lat": 52.5411052,
                        "lng": 13.2789853
                    }
                }
            },
            "arrival": {
                "time": "2022-01-11T15:33:40+01:00",
                "place": {
                    "type": "place",
                    "location": {
                        "lat": 52.5413639,
                        "lng": 13.2764439
                    },
                    "originalLocation": {
                        "lat": 52.5413639,
                        "lng": 13.2764439
                    },
                    "waypoint": 0
                }
            },
            "summary": {
                "duration": 14,
                "length": 175,
                "baseDuration": 12
            },
            "polyline": "BGir7mkDywvqZ-FhlC8BvR8BjSsEvlBkCzQ",
            "language": "en-us",
            "transport": {
                "mode": "car"
            }
        }, {
            "id": "3d706e13-7e3a-46f8-ac7b-0398e6921911",
            "type": "vehicle",
            "actions": [{
                "action": "depart",
                "duration": 12,
                "length": 165,
                "instruction": "Head east on Saatwinkler Damm. Go for 165 m.",
                "offset": 0
            }, {
                "action": "arrive",
                "duration": 0,
                "length": 0,
                "instruction": "Arrive at Saatwinkler Damm.",
                "offset": 2
            }],
            "departure": {
                "time": "2022-01-11T15:33:40+01:00",
                "place": {
                    "type": "place",
                    "location": {
                        "lat": 52.5485417,
                        "lng": 13.2763053
                    },
                    "originalLocation": {
                        "lat": 52.5413639,
                        "lng": 13.2764439
                    },
                    "waypoint": 0
                }
            },
            "arrival": {
                "time": "2022-01-11T15:33:52+01:00",
                "place": {
                    "type": "place",
                    "location": {
                        "lat": 52.5484908,
                        "lng": 13.2787278
                    },
                    "originalLocation": {
                        "lat": 52.5484909,
                        "lng": 13.2787278
                    }
                }
            },
            "summary": {
                "duration": 12,
                "length": 165,
                "baseDuration": 12
            },
            "polyline": "BG87pnkDipqqZ_Bq1ClBkiC",
            "language": "en-us",
            "transport": {
                "mode": "car"
            }
        }],
        "routeHandle": "AJYA5gcAAAcAAAAOAAAADAAAANwAAAB42mO4w8DAyMzAwMCekVqUapWce-DJVw4gl8Fdkqefa1JsYeevCzGp_UD6J5BmwAJgGndd2aMH4u87wJfOtPZBQWeXdlyq4vOCTo67-DWyc8wD28h1M0GPa2JgYaeOZlwqiNYG0sRofDtfJnsN1EJGsIqp55iWMIEYAMWzNTl1MN7O"
    }]
}
  1. This is a Route Import request with an invalid transport mode.
curl -X POST \
'https://router.hereapi.com/v8/import?apikey={YOUR_API_KEY}&return=polyline,summary,actions,instructions&transportMode=pedestrian'
{
  "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 is not 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": []
}
  1. 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 -X POST \
'https://router.hereapi.com/v8/import?apikey={YOUR_API_KEY}&return=polyline,summary,actions,instructions&transportMode=truck'
{"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": [
                {
                    "id": "fd82ca53-9dca-4948-83bc-d33e808bb0b8",
                    "type": "vehicle",
                    "actions": [
                        {
                            "action": "depart",
                            "duration": 363,
                            "length": 1303,
                            "instruction": "Head toward Am Postfenn on Havelchaussee. Go for 1.3 km.",
                            "offset": 0
                        },
                        {
                            "action": "arrive",
                            "duration": 0,
                            "length": 0,
                            "instruction": "Arrive at Havelchaussee.",
                            "offset": 34
                        }
                    ],
                    "departure": {
                        "time": "2022-01-21T15:09:15+01:00",
                        "place": {
                            "type": "place",
                            "location": {
                                "lat": 52.5033216,
                                "lng": 13.2118512
                            },
                            "originalLocation": {
                                "lat": 52.5033216,
                                "lng": 13.2118512
                            }
                        }
                    },
                    "arrival": {
                        "time": "2022-01-21T15:15:18+01:00",
                        "place": {
                            "type": "place",
                            "location": {
                                "lat": 52.4948452,
                                "lng": 13.2000128
                            },
                            "originalLocation": {
                                "lat": 52.4948452,
                                "lng": 13.2000128
                            }
                        }
                    },
                    "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"
                    }
                }
            ]
        }
    ]
}
  1. This request demonstrates handling of restrictions for pedestrian and bicycle mode.

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

curl -X POST \
'https://router.hereapi.com/v8/import?apikey={YOUR_API_KEY}&return=polyline,summary,actions,instructions&transportMode=pedestrian'
{
  "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": []
}
  1. 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 -X POST \
  'https://router.hereapi.com/v8/import?apikey={YOUR_API_KEY}&return=polyline,summary,actions,instructions&transportMode=car'
  {
    "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": [{
            "id": "0efce733-a4aa-4694-8a08-ae72c1e179b7",
            "type": "vehicle",
            "actions": [{
                "action": "depart",
                "duration": 14,
                "length": 101,
                "instruction": "Head northeast on Perleberger Straße. Go for 101 m.",
                "offset": 0
            }, {
                "action": "arrive",
                "duration": 0,
                "length": 0,
                "instruction": "Arrive at Perleberger Straße.",
                "offset": 2
            }],
            "postActions": [{
                "action": "wait",
                "duration": 3600
            }],
            "departure": {
                "time": "2022-01-11T15:13:32+01:00",
                "place": {
                    "type": "place",
                    "location": {
                        "lat": 52.5333084,
                        "lng": 13.352164
                    },
                    "originalLocation": {
                        "lat": 52.5333084,
                        "lng": 13.352164
                    }
                }
            },
            "arrival": {
                "time": "2022-01-11T15:13:46+01:00",
                "place": {
                    "type": "place",
                    "location": {
                        "lat": 52.5338836,
                        "lng": 13.3533071
                    },
                    "originalLocation": {
                        "lat": 52.5338836,
                        "lng": 13.3533072
                    },
                    "waypoint": 0
                }
            },
            "summary": {
                "duration": 3614,
                "length": 101,
                "baseDuration": 8
            },
            "polyline": "BG4jsmkDou-uZwTwmBwQ-gB",
            "language": "en-us",
            "transport": {
                "mode": "car"
            }
        }, {
            "id": "5a1206a2-c811-49bf-ac4e-0fe4227932d3",
            "type": "vehicle",
            "actions": [{
                "action": "depart",
                "duration": 13,
                "length": 102,
                "instruction": "Head northeast on Perleberger Straße. Go for 102 m.",
                "offset": 0
            }, {
                "action": "arrive",
                "duration": 0,
                "length": 0,
                "instruction": "Arrive at Perleberger Straße.",
                "offset": 2
            }],
            "departure": {
                "time": "2022-01-11T16:13:46+01:00",
                "place": {
                    "type": "place",
                    "location": {
                        "lat": 52.5338836,
                        "lng": 13.3533071
                    },
                    "originalLocation": {
                        "lat": 52.5338836,
                        "lng": 13.3533072
                    },
                    "waypoint": 0
                }
            },
            "arrival": {
                "time": "2022-01-11T16:13:59+01:00",
                "place": {
                    "type": "place",
                    "location": {
                        "lat": 52.5344651,
                        "lng": 13.3544702
                    },
                    "originalLocation": {
                        "lat": 52.5344651,
                        "lng": 13.3544703
                    }
                }
            },
            "summary": {
                "duration": 13,
                "length": 102,
                "baseDuration": 9
            },
            "polyline": "BG4ntmkD21gvZ0aq1B2JsT",
            "language": "en-us",
            "transport": {
                "mode": "car"
            }
        }]
    }]
}

results matching ""

    No results matching ""