# (11) - HERE Route Matching - GPS Trace Analysis

Generally, when we discuss logistics services (such as home delivery) or passenger services (taxi), there are several aspects that need to be considered. These can also be regarded as a puzzle of a complete logistics service. If this puzzle is completed, the logistics service is reliable. Sex will also improve.


Before the service starts:

* Fleet cost calculation - HERE Tour Planning
* Logistics route planning - HERE Tour Planning / HERE Waypoints Sequence
* Geographic data storage - HERE Data Hub / HERE Custom Location

User side:

* Query address or location - HERE Geocoder API / HERE Places API.
* Calculate logistics costs by time or distance - HERE Routing API.
* Real-time dynamic map - HERE JavaScript API / HERE SDK.

Service in progress:

* Real-time fleet dynamic map and order map in the management center - HERE JavaScript API / HERE Data Hub / HERE Custom Location
* The management center monitors the location of vehicles or goods - HERE Tracking.
* The management center monitors the destination information of the vehicle, and even dynamically updates the arrival time of each destination - HERE Waypoints Sequence.
* Through the function of path calculation to know the time and distance of arrival to the next place, to notify the client and the management center, both parties can know the real-time dynamics and arrival time - HERE Routing API.
* When the logistics vehicle approaches the customer's location, an event is triggered to inform the client to prepare for pickup or pickup - HERE Geofencing.
* The management center monitors whether the vehicle has abnormally deviated from the route, especially when the vehicle is carrying high-value goods - HERE Geofencing.
* For temporary urgent items, dispatch the closest vehicle to the service - HERE Matrix Routing.
* Avoidance on specific roads, or route planning in the customer's private field - HERE Custom Routes.
* Voice navigation on the driver's side, speed camera warning, and dispatch function of the management center - HERE SDK.

After the service ends:

* Analyze the driving behavior of the driver and take necessary measures to reduce the risk - HERE Route Matching.

Some of the products mentioned above have not been officially introduced yet, but I think one of the most interesting is HERE Route Matching, because this is a very fun product. In fact, this product only does one thing, which is to receive users. Upload the GPS track file, analyze it, and return the result.


However, you may ask, what do I do to analyze GPS trajectories? It’s actually quite interesting. GPS can tell us many things because of the latitude, longitude and time on it:

1. Whether the driver has any traffic violations, such as reverse driving, speeding, etc.
2. Which roads and types of roads to pass, such as provincial highways, highways, etc.
3. Which special road sections to pass, such as rockfall sections, continuous bends, etc.
4. The 3D spatial attributes of the passing road, such as slope.

In the common logistics industry or car rental industry, you can use this function to analyze the driver’s driving trace and know whether the driver has speeded or violated regulations. These behaviors may cause the driver to be fined. If there are many violations, the driver’s license may even be suspended. The company is also losing a lot, so finding out these potential risk factors is also part of cost control.

In the case of an insurance company, it can analyze whether the road section that the driver passes is a high-risk section, such as a section with frequent rockfalls, a continuous curve or a section prone to accidents, as the basis for calculating the risk factor, and actuarially calculate a better insurance premium.


Sounds interesting? so let's try it first.

### HERE Route Matching first experience

※ HERE Route Matching official website: https://developer.here.com/documentation/route-match/

First of all, to experience the HERE Route Matching function, please download and install Postman, which is a very useful software for testing network APIs. The APIs used in the previous courses are all GET requests, so it can be done with a browser, but what we need to do now is a POST request, which uploads our GPS track to the HERE Route Matching API.

Postman is free and cross-platform, so it can be used on Windows, Mac OS or even Linux, and now there is even a web version, you can research by yourself.

Download Postman: https://www.postman.com/downloads/

After opening the webpage, please select "Download the App" and the download will start. After downloading, please install it in accordance with the general normal process.


After installing and opening Postman, you will see this screen. Personally, I prefer dark colors, so I will switch to dark mode, and then press "Create a request" to add a request.


Then, please follow the picture below:

1. Change the beginning of GET to POST.
2. Fill in the URL of HERE Route Matching in "Enter request URL":

`https://m.fleet.ls.hereapi.com/2/matchroute.json?`

3. In the "Params" below, add an attribute, enter "apikey" for "key" and enter your own HERE APIKEY for "value". This attribute will also be automatically added to the address bar.


After the input is complete, you can start uploading GPS tracks...Wait, what if I don't have a GPS track?

The HERE Route Matching API accepts four GPS track formats:

* GPX, Garmin navigator or sports camera commonly used, is the industry standard format
* CSV, must have `latitude` (latitude) and `longitude` (longitude) and other non-essential attributes such as `timestamp` (timestamp), `speed_mps` (meters per second), `speed_mph` (miles/ Hour), `speed_kmh` (km/h), `heading` (azimuth).
* NMEA, the format commonly used by general driving recorders or GPS track recorders, is an industry standard format.
* KML, a format defined by Google, must have <Points> or <Placemarks>. .

If your driving recorder has a GPS recording function, there should be a good chance that it will use the NMEA format. For example:


If you are using Garmin’s driving recorder or Garmin’s sports camera, it should be in the GPX format, for example:


These two formats are the least problematic, so you can use them with confidence. As for CSV and KML, please confirm whether the format complies with the regulations before using it.

※ For the specification requirements of the trace format, please refer to: https://developer.here.com/documentation/route-match/dev_guide/topics/file-formats.html

You can use your own trace file, if not, I will provide a ready-made one here: https://bit.ly/3cw3bKU

After opening the above link, you will see a lot of records in English and numbers, recording the GPS signal status, positioning accuracy, etc. at that time. The only record we will use here is "$GPRMC".


If you are interested, you can study the content of the NMEA format. If you are not interested, it does not matter, just by the way.

$GPRMC,004710.000,A,2501.9727,N,12132.2850,E,6.46,359.83,280519,,,A*6A

Among them, `2501.9727,N` and `12132.2850,E` represent latitude and longitude, and there are also records of date, time, azimuth and speed, etc., so I won't mention them first.

Then we copy all the contents of the above NMEA text file to the clipboard (Ctrl + C). Then go back to Postman, click "Body" under the address bar, then select "raw" below, and then paste the content you just copied into the text box below (Ctrl + V).


Then, press the blue "Send" in the upper right corner, the track file you just pasted will be uploaded to the back end of HERE Route Matching for analysis, and the result will be returned.


The returned result will be displayed below, and because it is in JSON format, Postman also added the typesetting and colors very intimately.


Let's interpret the results now. The excerpts are as follows. You can see that in the structure of this JSON, the main first layer has four keys, namely "RouteLinks", "TracePoints", "Warnings", and "MapVersion":

* RouteLinks: **Information on road segments (called Link) passed by the GPS track**
* "functionalClass": 4, **// In the specification of HERE, roads are divided into five grades, from the highest grade 1 (usually representing high express roads) to the lowest grade 5 (usually representing lanes). **
* "confidence": 0.92, **// The accuracy of GPS and road position, from 0 (may be wrong) to 1 (may be correct), the better the GPS signal, the smaller the error range, the higher the trust; Otherwise, it will decline. **
* "linkId": -786042585, **// The unique number of each road segment (Link) inside HERE. **
* "mSecToReachLinkFromStart": 4841, **// The number of seconds to reach this ** road segment (Link) from the start of the trace
* "linkLength": 73.5, **// The length of this road segment (Link), in meters**.
* "shape": "25.08876 121.52147 25.08874 121.52149 25.08864 121.52158 25.08854 121.52166 25.08843 121.52173 25.0883 121.52181 25.08821 121.52186" **// The shape of this road segment (Link) is arranged by a string of latitude and longitude. If you want to draw the result in It can be used if it is on the map. **

* TracePoints: **GPS track point information**
* "confidenceValue": 0.53, **// The greater the distance between the original point and the road point, the greater the value; otherwise, the smaller. **
* "elevation": 0.0, **// Altitude, taken from the original track file. **
* "headingDegreeNorthClockwise": 140.35, **// The direction of travel (azimuth) of the GPS point. **
* "headingMatched": 141.0, **// corresponds to the direction of travel (azimuth) of the road. **
* "lat": 25.08871, **// GPS original latitude. **
* "latMatched": 25.08866, // **corresponds to the latitude on the road. **
* "linkIdMatched": -786042585, // **corresponding to the road segment (Link). **
* "lon": 121.52163, **// GPS original longitude. **
* "lonMatched": 121.52156, **// corresponds to the longitude of the road. **
* "matchDistance": 9.39, **// The distance from the original position to the road position (in meters). **
* "matchOffsetOnLink": 0.7547452459244315, **// corresponds to the percentage of the position of the road segment. **
* "minError": 9.0, **// How far is the closest road. **
* "routeLinkSeqNrMatched": 0, **// Correspond to which road segment (Link) in "RouteLinks". **
* "speedMps": 10.75, **// Speed, in meters per second. **
* "timestamp": 1479954513000 **// Timestamp in Unix format**

* Warnings: **Warning events**
* "category": 1010, **// Classification of warning events. **
* "text": "Vehicle stopped until trace point 85", **// The text content of the warning event. **
* "routeLinkSeqNum": -1, **// Which road segment (Link) in "RouteLinks" the warning event occurred. **
* "tracePointSeqNum": 41 **// The first trace point in "TracePoints" where the warning event occurred. **
* "toTracePointSeqNum": 85, **// The warning event ends at which track point in "TracePoints". **
* "breakDuration": 46 **// Duration (in seconds). **

* MapVersion: **Map version, here is the default version (LATEST)**

We can use the "linkId" in "RouteLinks" and the "linkIdMatched" in "TracePoints" to connect the data on both sides together, similar to the SQL JOIN command, so that each point corresponds to the relative road attribute, so it also gives The original GPS track points are more informative.

We can use a map to explain, the concept will be clearer.

For the picture below, it shows the starting point of the trace file you just uploaded. The number is 0, and then it goes down to the 10th point in sequence. It can be clearly seen that this is on Chengde Road, Taipei City. For the four trajectories traveling from north to south, the dots on the right are relatively small, showing the original GPS points, while the dots on the left are relatively large, showing the trace corresponding to the road.


In this way, you should be able to know what the role of HERE Route Matching is: this service will receive your GPS track and compare the roads in the HERE map database to "guess" which road you might drive on based on the direction and location Above.

GPS itself will drift. Generally speaking, it may be between a few meters to tens of meters. Under good reception conditions, we will probably estimate a radius of five to ten meters as the error radius. As for dual-frequency GPS or GPS with assisted positioning function (such as AGPS / DGPS) may be within two meters to tens of centimeters; if the reception is not good, for example, there are shelters above, or there are tall buildings around, which may cause the signal to be blocked. Interference, insufficient visible satellites, or signal reflections, etc., will affect the positioning accuracy.


###### Source: https://blog.oplopanax.ca/2012/11/measuring-smartphone-gps-accuracy/

Therefore, it is recommended that when using the Route Matching function, the uploaded GPS track should not be too short (it should be at least tens of seconds), because if the GPS points are too few and the offset is too large, the calculation of the road is correct The rate will also be reduced; therefore, a GPS track of sufficient length can allow Route Matching to have enough data to judge the roads passed by, thereby improving the accuracy.

So what we want to mention is the "Warnings" part. If there is any violation of the GPS track, such as entering a road that should not be entered, violation of the prohibition of turning, etc., it will be returned in this place; not only that , If the GPS track is interrupted or stopped here, it will also appear here. Because there are possible errors in GPS trajectories, these events are only "possible" and do not mean that they are "definitely".

For example, the content of the following event is "Entering link 1063453689 at 25.04467,121.54123 into forbidden driving direction". At first glance, we can interpret it as "reverse driving", but after actually watching the GPS track, we found that the sky here was overpassed by the Civic Avenue viaduct. Blocking, poor GPS signal, leading to serious drift, and this drift just drifted to the reverse turn, thus triggering a reverse driving event.


In practice, we should take the events in "Warnings" as a reference, rather than absolute violations or violations. The actual situation may require more in-depth discussion to get the final judgment.

But you may have asked, the attributes just now are some attributes such as latitude and longitude, ID, azimuth, etc., and it feels like they are only used on the map. How can I get more useful information? After all, I know the length of this LINK, and it feels like it doesn't mean much to me.

### HERE Route Matching detects speeding behavior

The powerful function of HERE Route Matching, in addition to finding the passing roads with GPS points, can also bring out the relevant attributes of these roads.

HERE has another network service called HERE Advanced Data Sets. The principle is to use network API to obtain the detailed attributes of the bottom layer of HERE map, such as road name, number of lanes, speed limit, average speed, turning limit, address, traffic Signs, direction of travel, slope, height, curvature, etc.

But we will not introduce the usage of HERE Advanced Data Sets at present, you can research it yourself.

※ HERE Advanced Data Sets: https://developer.here.com/documentation/platform-data/

The content in HERE Advanced Data Sets is quite rich, even to the point of complexity, HERE Route Matching can use some of the layers inside:

* ADAS_ATTRIB_FCn: High-precision 3D spatial information of roads
* BASIC_HEIGHT_FCn: low precision height of the road
* DISTANCE_MARKERS_FCn: Road milestones
* LANE_FCn: road lane related attributes
* LINK_FCn: Basic attributes of the road
* LINK_ATTRIBUTE_FCn: additional attributes of the road
* LINK_ATTRIBUTE2_FCn: additional attributes of the road
* LINK_TMC_FCn: TMC related attributes of the road
* ROAD_ADMIN_FCn: the administrative district attribute of the road
* ROAD_GEOM_FCn: geometric attributes of road segments
* ROAD_NAME_FCn: Road name attribute
* ROAD_ROUGHNESS_FCn: the smoothness of the road
* ROUNDABOUT_FCn: ring
* SPEED_LIMITS_FCn: road speed limit
* SPEED_LIMITS_COND_FCn: special road speed limit
* SPEED_LIMITS_VAR_FCn: the variable speed limit of the road
* TOLL_BOOTH_FCn: Related attributes of road toll station
* TOLL_LINK_FCn: Related attributes of toll road section
* TRAFFIC_PATTERN_FCn: historical traffic related attributes
* TRAFFIC_SIGN_FCn: Traffic sign related attributes
* TRUCK_SPEED_LIMITS_FCn: Truck speed limit
* TRUCK_RESTR_FCn: truck-related road restrictions
* TURN_RESTR_FCn: road no-turn information

From the above description, you can probably imagine how rich the attributes extracted by HERE Route Matching are, which can satisfy many uses. And what we want to use here is only the "SPEED_LIMITS_FCn" part.

You should also notice that each layer name has a "FCn" suffix after it. This is because the HERE map divides each road into five levels according to its functionality. 1 represents the highest level, usually a high-speed road, and 5 represents the lowest level, usually alleys, and "FC" is an abbreviation for "Functional Class".

This means that you can actually obtain only a specific FC. For example, "SPEED_LIMITS_FC1" means that I only need to take out the road speed limit whose Functional Class is equal to 1. Will post back. If you use "FCn", it means that you can return the Functional Class equal to 1 to 5 and you need to return, basically all roads are included.

So "SPEED_LIMITS_FCn" means "all roads, as long as there are speed limits...I want them all!"

Then we go back to Postman and add a new parameter in "Params":

* Key input "attributes"
* Value input "SPEED_LIMITS_FCn(\*)" (adding "(\*)" means to return all the attributes in the layer.)

Then press "Send", let's observe what happens to the return.


Compared with the previous results, we found that in addition to the existing attributes, there is an additional "attributes", which contains a Key / Value combination. Key is "SPEED_LIMITS_FCN", which is the layer we want to query, and Value is a Dictionary:

{
    "FROM\_REF\_SPEED_LIMIT": "0", // Speed limit on the forward road
    "TO\_REF\_SPEED_LIMIT": "50", // reverse road speed limit
    "SPEED\_LIMIT\_SOURCE": "1", // The data source of the speed limit, 1 represents the speed limit sign
    "SPEED\_LIMIT\_UNIT": "K" // Speed limit unit, K stands for KM (km)
 }

You may be wondering here, what is meant by "forward" and "reverse"? I need to explain here, because the most basic element of the map is the "point", and the point and the point will be connected to form a "line", and the line and the line will form a "plane". For example, the following figure explains how to use X and Y coordinates to present a 2D point, then connect the points to form a line, and then use the line to form a surface.


###### Source: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry


###### A complete digital map will be composed of points (such as addresses, points of interest), lines (such as roads, waterways), and planes (such as buildings, parks, oceans), and use digital geometric information to express geography Various objects in the environment.

In the HERE map, all roads belong to the "line", and a line segment must have two ends. In the definition of HERE, the one between the two points in the south is called the Reference Node, and the other The point is called Non-reference Node.

Once you have a reference point, you can use the reference point to indicate the direction of the road, for example:

* From Reference Node to Non-reference Node, it is called Positive Direction, also called From Ref.
* From Non-reference Node to Reference Node, it is called Negative Direction, also called To Ref.

Taking the road we have just passed, the ID of HERE is "786042585". The intersection on the south side of this road segment (Lane 181, Hougang Street) is the Reference Node; and the intersection on the north side (Danan Road) is the Non- reference Node (non-reference point). It should be noted here that although this road segment just presents a complete road, the road segment can be long or short, ranging from several meters to several kilometers, and a road usually has quite a lot of line segments ( Link).

The partition island in the center of the fourth section of Chengde Road divides the road into two ends, the east side goes north, and the west side goes south. The road with LINK ID 786042585 is the road going south, that is, from Non-reference Node to Reference Node, so it belongs to the reverse direction; if there is a road segment showing a two-way road, it will also have a forward direction ( Positive Direction and Negative Direction are two directions.


But please note that this road segment (Link) is one-way, which does not mean that the road is one-way, because just like the road in the picture (section 4 of Chengde Road), it is a two-way road, but it will still be Because the road digitization rules divide the east and west roads into two different line segments, a complete two-way road is composed of a forward and a reverse road.

※ Digitization: The process of drawing real scenes into points, lines, and areas on a digital map.

Taking the data we just returned, the attribute `"linkIdMatched": -786042585`, you can notice that the ID is a negative number. This tells you that the direction of the trace is negative, so you will also find that because of this The road segment (Link) has only one direction, so the forward road speed limit `FROM_REF_SPEED_LIMIT` is 0, which means the speed limit does not exist; while the reverse road speed limit `TO_REF_SPEED_LIMIT` is 50, which represents a speed limit of 50 kilometers.

We now have the road speed limit, so by comparing the driving speed with the speed limit, we can know whether there is a speeding state. From the "speedMps" value in "TracePoints", the speed value in the unit of "meters per second" can be taken out, and multiplied by 3.6 can be converted into "km/h". Take the 0th track point `“speedMps”: 10.75` as an example, if converted to “km/h”, it is 38.7 km/h, and there is no speed limit higher than 50 km/h, so there is no speeding.

Using the same logic to compare each point in the GPS trace, you can reproduce the driving behavior of the driver at the time, and find the section and time of the speeding. In the following figure, it shows an acceleration -> deceleration -> The process of acceleration -> deceleration.


Of course, because HERE Route Matching returns a text file in JSON format, after getting these text, the logic of processing the data must be written by the user. If you want to discuss this part, it is a bit like teaching how to code, so I won’t go into details here.

The above is the introduction of HERE Route Matching.