Route Match Extension API Developer's Guide

Match Route Response

Response Structure JSON


{
  "RouteLinks" : [
    {
      "linkId" : ...,
      "functionalClass" : ...,
      "shape" : "latitude1 longitude1 latitude2 longitude2 ...",
      "linkLength" : ...
    },
    ...
  ],
  "TracePoints" : [
    {
      "lat" : ...,
      "lon" : ...,
      "elevation" : ...,
      "speedMps" : ...,
      "headingDegreeNorthClockwise" : ...,
      "latMatched" : ...,
      "lonMatched" : ...,
      "linkIdMatched" : ...,
      "confidenceValue" : ...,
      "matchDistance" : ...,
      "routeLinkSeqNrMatched" : ...,
      "timestamp" : ...,
      "headingMatched" : ...,
      "minError" : ...

    },
    ...
  ],
  "Warnings" : [
    {
      "category" : ...,
      "routelinkSeqnum" : ...,
      "waypointseqnum" : ...,
      "text" : "..."
    },
    ...
  ],
  "MapVersion" : "..."
}

Response Structure JSON with PDE Attributes


{
  "RouteLinks" : [
    {
      "linkId" : ...,
      "functionalClass" : ...,
      "shape" : "latitude1 longitude1 latitude2 longitude2 ...",
      "linkLength" : ...
      "mSecToReachLinkFromStart": ...,
      "confidence" : ...
      attributes: {
        ADAS_ATTRIB_FCN: [
          {
            SLOPES: ...
          }
        ],
        SPEED_LIMITS_FCN: [
          {
            FROM_REF_SPEED_LIMIT: ...,
            TO_REF_SPEED_LIMIT: ...,
            ...
          }
        ],
        ...
      }
    },
    ...
  ],
  "TracePoints" : [
    {
      "lat" : ...,
      "lon" : ...,
      "elevation" : ...,
      "speedMps" : ...,
      "headingDegreeNorthClockwise" : ...,
      "latMatched" : ...,
      "lonMatched" : ...,
      "linkIdMatched" : ...,
      "confidenceValue" : ...,
      "matchDistance" : ...,
      "routeLinkSeqNrMatched" : ...,
      "timestamp" : ...,
      "headingMatched" : ...,
      "minError" : ...

    },
    ...
  ],
  "Warnings" : [
    {
      "category" : ...,
      "routelinkSeqnum" : ...,
      "waypointseqnum" : ...,
      "text" : "..."
    },
    ...
  ],
  "MapVersion" : "..."
}

Response Structure TXT


RouteLinks: <number of route link lines to follow>
linkId,functionalClass,linkLength,shape
<linkId>,<functionalClass>,<linkLength>,<latitude 1> <longitude 1> <latitude 2> <longitude 2> ...
...
TracePoints: <number of trace point lines to follow>
lat,lon,elevation,speedMps,heading,latMatched,lonMatched,linkIdMatched,routeSeqNrMatched,
timestamp,matchDist,headingMatched,minError,confidenceValue
<lat>,<lon>,<elevation>,<speedMps>,<heading>,<latMatched>,<lonMatched>,<linkIdMatched>,<routeSeqNrMatched>,
<timestamp>,<matchDist>,<headingMatched>,<minError>,<confidenceValue>
...
Warnings: <number of warning lines to follow (column name rows not counted)>
category,routelinkSeqnum,waypointseqnum,text
<category>,<routelinkSeqnum>,<waypointseqnum>,<text>
...
MapVersion: <map version>

Response Elements / Attributes

Parameter Type Mandatory Description
RouteLinks List of elements with following attributes Y Represents the matched route as a connected sequence of road links.
RouteLinks . linkId int Y Permanent Link ID. Negative, if the link was driven in negative direction (from non-reference node to reference node).
RouteLinks . functionalClass int 1 ... 5 Y Road functional class. Required to efficiently lookup further link attributes from the PDE Web service.
RouteLinks . shape Blank separated list of floats Y String that contains a blank separated list of latitude/longitude coordinates in WGS84 degree. The order of the coordinates is in route driving direction. One of the coordinates is required to efficiently lookup further link attributes from the PDE Web service.
RouteLinks . linkLength float Y Length of the link in meters. This is provided for convenience to compute statistics. Link length is computed upon linear straight connections between the shape points (not spherical).
RouteLinks . confidence float 0.0 ... 1.0 Y Confidence value for this link (probability that this link was actually driven). Value between 0.0 (high risk that link was not driven but is an artefact from big GPS deviations or missing road geometry) and 1.0 (very likely the link was driven). Currently the confidence value is derived from the confidence of the matched way points on the link or the confidence of the neighbour links, but this might be refined in future releases.
RouteLinks . mSecToReachLinkFromStart int Y Estimated relative drive time in milli seconds needed from the route start point to the start of this link. Note that this time is currently not aligned with time stamp values provided in the trace.
Parameter Type Mandatory Description
TracePoints List of elements with following attributes Y Lists the provided trace points, each with the matched link ID and coordinate.
TracePoints . lat float Y Original GPS trace point latitude in WGS84 degree. This value is taken from the request, and provided in the response for convenience.
TracePoints . lon float Y Original GPS trace point longitude in WGS84 degree. This value is taken from the request, and provided in the response for convenience.
TracePoints . elevation float Y Original GPS trace point elevation in meter height above the WGS84 reference ellipsoid. This value is taken from the request, and provided in the response for convenience.
TracePoints . speedMps float Y Original GPS trace point speed value, in meter per second (independent of the originally provided unit). This value is taken from the request, and provided in the response for convenience.
TracePoints . headingDegreeNorthClockwise float Y Original GPS trace point heading (aka bearing or direction), in degree against North, clockwise. This value is taken from the request, and provided in the response for convenience. 10000 if not provided in the trace.
TracePoints . latMatched float Y Matched GPS trace point latitude in WGS84 degree. The coordinate is guaranteed to fit (with a 0.00001 degree tolerance) onto the map road network, where the map shape points are connected by straight lines.
TracePoints . lonMatched float Y Matched GPS trace point longitude in WGS84 degree. The coordinate is guaranteed to fit (with a 0.00001 degree tolerance) onto the map road network, where the map shape points are connected by straight lines.
TracePoints . linkIdMatched int Y Matched Permanent Link ID for this trace point. Negative, if the link was driven in negative direction (from non-reference node to reference node).
TracePoints . routeSeqNrMatched int Y Sequence number of the matched link within the route path. Starting at zero.
TracePoints . timestamp int Y Milli seconds since 1/1/1970 UTC, unmodified from original trace, zero if trace contained no timestamps.
TracePoints . matchDist float Y Distance between the original trace point and the matched coordinate, in meter.
TracePoints . headingMatched float Y Heading of the road section at the matched position. Degree against North, clockwise.
TracePoints . minError float N Meter distance to the nearest road. This is a lower bound for the combined inaccuracy of GPS signal and map. 1000000.0 if it was not computed for this point.
TracePoints . confidenceValue float 0.0 ... 1.0 Y Confidence value for this point match (probability of match correctness). Value between 0.0 (high risk of matching to a wrong link) and 1.0 (very likely the matched link is the correct one). Currently the confidence value is simply derived from the distance between the original and the matched coordinate, but this will be refined in future releases.
TracePoints . matchOffsetOnLink float 0.0 ... 1.0 Y Relative offset along the link to the matched coordinate, when driving from reference node towards non-reference node.
Parameter Type Mandatory Description
Warnings List of elements with following attributes Y Lists warnings encountered during trace matching.
Warnings . category int Y Warning Category. Possible values:

2 = Suspicious u-turn. The u-turn might come from a poor point quality and might not be actually driven.

3 = Forbidden driving direction. Vehicle entered a one way street into the forbidden direction.

4 = Forbidden access. Vehicle entered a street which is not allowed for the vehicle type.

5 = Leaving no-through-traffic zone. Vehicle entered and left such a zone, which is not allowed.

6 = Illegal u-turn. Vehicle made a u-turn where it is not allowed.

7 = Gate traversal. Vehicle passed a gate. This might be illegal or impossible without a key.

8 = Illegal turn. Vehicle made a forbidden turn.

1001 = Deprecated CSV column. The input file contains a column, which should no longer be used.

1002 = Unknown CSV columns. The listed columns of the input file are being ignored.

1003 = Unconnected route links. Within the route, there is a gap between two subsequent links.

1004 = Ignored bad trace point. The quality of the trace point was considered so bad, that the point was ignored for the matching.

1005 = Trace point long match distance. The trace point was matched onto a road link quite far away.

1006 = Trace point matched out of sequence on route. A trace point got matched onto the route at a later spot then the subsequent trace point got matched.

1008 = Trace point couldn't be matched. The trace point is far away from any road and no neighbouring trace points could be used to match it in between them.

1009 = For subsequent trace points, the route distance is much bigger than the airline distance between the points.

Warnings . routeLinkSeqNum int Y Sequence number of the link in the route to which the warning refers. -1 if not applicable.
Warnings . tracePointSeqNum int Y Sequence number of the trace point to which the warning refers. -1 if not applicable.
Warnings . text List of strings Y Describes a potential issue in the input trace or with the matching process. Warnings can be hints that impact the quality/reliability of the match result, but always a technically valid result is returned. If there are issues that prevent a technically valid result, then an HTTP level error 4xx or 5xx is returned.
Parameter Type Mandatory Description
MapVersion string Y The map release quarter, for which the returned Link IDs and matched coordinates are valid. The current format is YYYY'Q'Q, e.g. 2015Q1 and denotes the quarterly map release. Reship revisions of a map release are currently not declared.
Note: This format may change, for example in case of use of bi-weekly map releases.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.