Getting started

Prepare input data

If you do not have your own data already formatted in GPX, consider downloading a public log from OpenStreetMap . See Supported file formats.

Run the matching process

TrackMatching uses a REST API easily accessible from scripts. The popular command-line tool CURL is recommended for testing. A Node.js sample invocation is also provided below. To process a GPX file named gpslog.gpx, run the following command:

curl -X POST -H 'Content-Type: application/gpx+xml' -H 'Accept: application/json' --data-binary @gpslog.gpx "https://api.traxmatching.io/rest/mapmatch/?app_id=YOUR_APPID&app_key=YOUR_APPKEY" -o output.json

Notes:

• YOUR_APPID and YOUR_APPKEY have to be replaced with your own credentials.
• supported output formats are XML (default) and JSON. The Accept header can be omitted for XML.

Analyze the result

The result file consists of three parts:

1. The main part: a diary describing the complete GPX log. It is split into multiple entries with routes. A route describes a continuous path with link pointers using the corresponding OpenStreetMap IDs for ways and nodes.

   "diary": {
     "entries": [{
       "route": {
         "links": [{
           "err": 15.79, // quality indicator (meter/point)
           "id": 41510276, // OSM way id
           "src": 25332083, // OSM node ID, source
           "dst": 508269077 // OMS node ID, destination
            ...
   

2. The query parameters that were taken into account:

     "options": {
       "output.linkGeometries": true,
       "output.linkMatchingError": true,
       "output.waypointsIds": true,
   	...
   

3. Indicators of performance and global statistics

     "performanceIndicators": {
       "completionMillis": 398,
       "numPoints": 935,
       "meanErr": 30.66058959364511,
      ...
   

Node.js invocation example

var options = 
{ method: 'POST',
  host: 'api.traxmatching.io',
  path: '/rest/mapmatch/?app_id=YOUR_APPID&app_key=YOUR_APPKEY',
  headers: { 'Content-Type':'application/gpx+xml', 'Accept':'application/json' } 
};
var buffer = fs.readFileSync("mygpxtrack.gpx");
var request = http.request(options, callback);
request.write( buffer );
request.end();

Leaflet example

The example below displays matching results on a Leaflet map.
Note that geometries are sent back in latitude/longitude (WGS84) by default and can be projected on the OSM coordinate system (EPSG:3857) with parameter output.osmProjection=true

for( var i=0;i<result.diary.entries.length;i++){
 entry = result.diary.entries[i];
 for( var j=0;j<entry.route.links.length;j++  ){  
  L.geoJson( JSON.parse( entry.route.links[j].geometry ) ).addTo(map);
 }   
}