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 "" -o output.json


  • 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.
  • use curl -k ... https ... for basic encryption (experimental).

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: '',
  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 );

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);