The most recent fea­ture of our Cyface Ser­vice is the inte­gra­tion of map-match­ing. Now road con­di­tion data is not only avail­able as raw gps posi­tions, but also matched to the road sec­tions most like­ly caus­ing the mon­i­tored vehi­cle vibra­tions. To achieve this we employed the Open Source Rout­ing Machine (OSRM). The fol­low­ing sec­tions describe how to use the OSRM map-match­ing ser­vice.

VISUALIZE OSRM map-matching results

The default source for under­stand­ing OSRM is the OSRM Wiki and doc­u­men­ta­tion. If you can’t find detailed info on how the algo­rithms work you can ether crawl through the open source code or look clos­er at the match­ing results. The use of an online json for­mat­ter makes it much more fun to read the respons­es and inter­pret the behav­iour.

In order to visu­al­ize the match­ing results you can decode the match­ing geom­e­try with Google’s Online Decoder. By adjust­ing the request’s overview para­me­ter you can tell OSRM how detailed the geom­e­try overview should be.

For debug­ging, you prob­a­bly need detailed infor­ma­tion on result­ing OSM node IDs (using annotation=true). helps you with this — their map ser­vice pro­vides not only attrib­ut­es of nodes but also list you the ways those nodes are part of.

For advanced analy­sis of the map match­ing in order to fine-tune the process, we found this tool which we’ll test soon.

How to PROCESS the OSRM response

After suc­cess­ful­ly set­ting up the OSRM ser­vice you can send match­ing requests to its API and receive zero, one or mul­ti­ple match­ing respons­es of the fol­low­ing for­mat:

  • match­ings (i.e. (sub)traces “route objects” of one or mul­ti­ple match­ing alter­na­tives)
    • each sub­trace con­tains “route legs” which rep­re­sent the path between the OSM nodes lying on this trace.
  • tra­ce­points (each gps point is mapped to a “way­point” or “null” (for sin­gle out­liers). This is the case for each match­ing alter­na­tive found by the ser­vice. These points are still in the same order as the gps point of your request.)

Unfor­tu­nate­ly the offi­cial doc­u­men­ta­tion does not men­tion too much about how these result points are ordered and struc­tured. The fol­low­ing insights might save you some debug­ging time:

  1. OSRM map match­ings with dif­fer­ent num­ber of trace points then gps points entered?”
    A request can not only return mul­ti­ple match­ing alter­na­tives but each of them can be sliced into mul­ti­ple sub-traces (see OSRM Wiki: Response).
  2. How to map a ’null’ tra­ce­point of a OSRM match­ing response to a sin­gle ‘match­ing’?”
    For­tu­nate­ly, the trace points are ordered just like the match­ing alter­na­tives and the orig­i­nal gps points. For exam­ple: If the response is

    [matching_index, waypoint_index]: [0,0], [0,1], null, null, [0,2], [1_0], …

    those two unmatched tra­ce­points (’null’) are part of match­ing alter­na­tive with id 0.

Check out our demo to see the match­ing in action! We hope this new fea­ture helps to make your appli­ca­tion even cool­er, using the Cyface road con­di­tion data.

Map-matched cyface map