MultiRoute Webservice API¶

• MultiRoute Webservice API
• Webservice-Request
  • Das Webservice-Request-Objekt
    • HTTP Methode:
    • Format / ContentType
  • Das JSON-POST-Object
    • "tour":
    • "waypoints":
      • address
      • coordinate
      • time
      • time mit Zeitfenster
      • Achtung
      • links
      • Beispiel Waypoints ohne Zeitfenster
      • Beispiel Waypoints mit Zeitfenster
  • Webservice-Response-Objekt
    • Format / ContentType
    • Das JSON-Object
      • Beispiel
  • Beispielaufruf mit curl
• Webservice-Result
  • Der Webservice-Result-Aufruf
  • Das JSON-Object
    • "tour":
      • Beispiel
      • Parameter status
      • Parameter time_window_error
      • Zeitplanung mit Zeitfenster Fehler 1
      • Zeitplanung mit Zeitfenster Fehler 2
    • "waypoints":
      • Achtung:
      • Parameter address (wird nicht verändert)
      • Parameter geocode_address Gefundene Adresse
      • Parameter coordinate
      • Parameter building_coordinate
      • Parameter time
      • Achtung
      • Beispiel
• Webservice-Status
  • Der Webservice-Status-Aufruf
  • Das JSON-Object
    • Parameter status
    • Parameter error_text
    • Parameter time_window_error
      • Zeitplanung mit Zeitfenster Fehler 1:
      • Zeitplanung mit Zeitfenster Fehler 2:
• Webservice-StaticMap
  • Ausgabe-Steuerung
    • zulässige Werte / Beschränkung:
    • Default-Werte:
  • Fehlerfall
  • Erfolgsfall
  • vor Verwendung
  • Beispielaufruf mit Curl
    • Beispiel-Ergebnis
• Webservice-Optimierung
  • Der Webservice-Optimierung-Aufruf
  • GET Parameter
    • Beispiel:
• Postleitzahlen entlang der Tour
  • Webservice-Aufruf
    • Ohne Puffer:
    • Optional zusätzlich mit Puffer:
    • Ergebnis
    • Erweiterung
• Webservice-AdditionalPoints
  • "waypoints":
    • • address
      • coordinate
      • time
      • Achtung
  • Beispiel
  • Curl Beispiel:
• Webservice Download
  • Der Webservice-Download-Aufruf
  • Formate
    • Formate abfragen
    • Spezialformate im Browser für Mobile Navigation
• Weitere Aufrufe
  • Webservice-Delete
    • Rückgabe
  • Dynamische Karte
    • Karte mit einer Tour anzeigen
      • Rückgabe
    • Gleichzeitiges Anzeigen mehrerer Touren und eines Punktes
    • Interaktive Oberfläche (muss freigeschaltet sein)

Webservice-Request¶

Das Webservice-Request-Objekt¶

https://webservice.tourenplaner.biz/startjob

HTTP Methode:¶

POST

Format / ContentType¶

Content-Type: application/json

Das JSON-POST-Object¶

"tour":¶

{
   "optimize": "time",
   "roundtrip": true,
   "tollfree": true,
   "avoid_highway": true,
   "uid": "A123",
   "start": true,
   "show_only" : true,
   "time_window" : false,
   "travel_mode" : "Hgv_75" 
}

"waypoints":¶

1. Der erste Punkt im Array ist der Startpunkt
2. Der letzt Punkt ist der Endpunkt wenn nur Hinweg berechnet werden soll

Es können beliebige key value(String) Paare angegeben werden, diese werden einfach durch gereicht.

address¶

coordinate¶

time¶

time mit Zeitfenster¶

Achtung¶

1. Zeitangaben in ISO 8601 Format
2. duration_of_stay wird nicht für den ersten Punkt ausgewertet.
3. arrival, departure es wir nur ein fixer Termin verwendet.
   1. Es wird beim ersten Datensatz wo es eine arrival oder departure Angabe findet als Fixtermin festgelegt.
   2. Wenn arrival und departure angegeben sind, dann wird arrival als Fixtermin festgelegt.

links¶

Beispiel Waypoints ohne Zeitfenster¶

[
     {
        "uid":"1",
        "coordinate" : {"lat":"48.163415","lon":"11.577531"},
        "address": {"locality": "München", "postcode": "80803", "street": "Pündterplatz 8"},
    "links" : [{"name": "Neu Webseite", "url" : "http://heise.de"}, 
        {"name": "Ajax Aufruf mit Type script", "url" : "/test_alert.js", "remote" : true}, 
        {"name": "Javascript", "function" : "alert(\"Hallo\")"},
        {"name": "Url im neuen Fenster mit Angaben", "window" : ["http://heise.de", "test", "toolbar=no,location=no,directories=no,status=no,menubar=no,scrollbars=yes,resizable=yes"]}
        ]
     },
     {
        "uid":"2",
        "coordinate" : {"lat":"49.454345","lon":"11.073495"},
        "address": {"locality": "Nürnberg", "postcode": "90403", "street": "Weintraubengasse 1"},
        "time": {"duration_of_stay" : 60, "arrival": "2013-02-19T15:00:00+01:00"}
     },
     {
        "uid":"3",
        "coordinate" : {"lat":"48.136415","lon":"11.577531"},
        "address": {"locality": "München", "postcode": "80331", "street": "Tal 1"}
     }
]

Beispiel Waypoints mit Zeitfenster¶

[
     {
        "uid":"1",
        "coordinate" : {"lat":"48.163415","lon":"11.577531"},
        "address": {"locality": "München", "postcode": "80803", "street": "Pündterplatz 8"},
        "time": {"timeframe_end": "2013-02-19T15:00:00+01:00"}
     },
     {
        "uid":"2",
        "coordinate" : {"lat":"49.454345","lon":"11.073495"},
        "address": {"locality": "Nürnberg", "postcode": "90403", "street": "Weintraubengasse 1"},
        "time": {"duration_of_stay" : 60, "timeframe_start": "2013-02-19T15:00:00+01:00", "timeframe_end": "2013-02-19T18:00:00+01:00"}
     },
     {
        "uid":"3",
        "coordinate" : {"lat":"48.136415","lon":"11.577531"},
        "address": {"locality": "München", "postcode": "80331", "street": "Tal 1"}
     }
]

Webservice-Response-Objekt¶

Format / ContentType¶

Content-Type: application/json

Das JSON-Object¶

Beispiel¶

 {
    "return_code": 0,
    "error_description": "",
    "tid": "bGVJKz6wFb-xi1zKmWKpKw",
    "credit_expiration_date": "2014-02-26T14:00:02+01:00" 
  }

Beispielaufruf mit curl¶

curl -u test:test -XPOST -H "Content-Type: application/json" "localhost:3000/startjob" -d '
{
  "tour": {
    "roundtrip": true,
    "tollfree": false,
    "optimize": "time",
    "avoid_highway": false,
    "uid": "123",
    "start": true
  },
  "waypoints": [
     {
        "uid":"34",
        "coordinate" : {"lat":"48.163415","lon":"11.577531"},
        "address": {"locality": "München", "postcode": "80803", "street": "Pündterplatz 8"}
     },
     {
        "uid":"26",
        "coordinate" : {"lat":"49.454345","lon":"11.073495"},
        "address": {"locality": "Nürnberg", "postcode": "90403", "street": "Weintraubengasse 1"},
        "time": {"duration_of_stay" : 60, "arrival": "2013-02-19T15:22:46+01:00"}
     },
     {
        "uid":"56",
        "coordinate" : {"lat":"48.136415","lon":"11.577531"},
        "address": {"locality": "München", "postcode": "80331", "street": "Tal 1"}
     }
]
}'

Webservice-Result¶

Der Webservice-Result-Aufruf¶

https://webservice.tourenplaner.biz/getresult?tid=<transaktions-ID>
oder
https://webservice.tourenplaner.biz/getresult.json?tid=<transaktions-ID>

Optionaler Parameter:
https://webservice.tourenplaner.biz/getresult.json?tid=<transaktions-ID>&geocode_result=true

Das JSON-Object¶

"tour":¶

Beispiel¶

{
   "optimize": "time|distance",
   "roundtrip": true,
   "tollfree": true,
   "avoid_highway": true
   "uid": "A123",
   "distance": 0,
   "travel_time": 0,
   "driving_time": 0,
   "waiting_time": 0,
   "time_window_error": null
}

Parameter status¶

Parameter time_window_error¶

JSON Objekt mit Fehlerstruktur zur Fehlermeldung (Zeitplanung mit Zeitfenster).

Zeitplanung mit Zeitfenster Fehler 1¶

Ein Punkt konnte nicht vom Startpunkt erreicht werden (innerhalb des Zeitfensters).

"time_window_error": {
"type": 1,
"nr": 2,
"name": "Punkt 3",
"start_depo": "2:00 Uhr",
"fahrzeit": "0h:10m",
"ankunft_kunde": "2:10 Uhr",
"timeframe_start": "1:30 Uhr",
"timeframe_end": "1:45 Uhr" 
}

Zeitplanung mit Zeitfenster Fehler 2¶

Zwischen 2 Punkten reicht die Zeit nicht, sie innerhalb einer Tour anzufahren.

"time_window_error": {
"type": 2,
"nr1": 2,
"nr2": 3,
"name1": "Name Punkt1",
"name2": "Name Punkt2",
"timeframe_start1": "3:30 Uhr",
"timeframe_end1": "3:45 Uhr",
"timeframe_start2": "3:30 Uhr",
"timeframe_end2": "3:45 Uhr",
"start_kunde1": "4:30 Uhr",
"stop_kunde2": "6:12 Uhr",
"start_kunde2": "4:30 Uhr",
"stop_kunde1": "6:10 Uhr",
"fahrzeit12": "1h:42m",
"fahrzeit21": "1h:40m",
"aufenthalt_kunde1": "1h:00m",
"aufenthalt_kunde2": "1h:00m" 
}

"waypoints":¶

1. Der erste Punkt im Array ist der Startpunkt
2. Der letzt Punkt ist der Endpunkt wenn nur Hinweg berechnet wurde

Achtung:¶

Wenn der Parameter roundtrip: true (Rundreise) ist, dann beziehen sich die Parameter distance und driving_time auf die Zeit und Strecke, die vom letzten Punkt (letzter Punkt vor dem Ziel) zum Ersten (Start/Ziel) benötigt wird.

Parameter address (wird nicht verändert)¶

Parameter geocode_address Gefundene Adresse¶

Geokodier-Qualität:
gleich 0: Eingabe passt zur Ausgabe
größer 0: Es gibt mindestens einen Unterschied

Unterschiede bei der Postleitzahl werden mit einem Faktor von 10 multipliziert.
Wenn der angegebene Ort vollständig im gefundenen Ort vorhanden ist, dann wird das auch als 0 bewertet.
Eingabe: Neustadt => Neustadt an der Donau

Es wird empfohlen, die gefundene Adresse ("geocode_address") ab einer quality von 4 bis 5 am Frontend auszugeben, um eine manuelle Prüfung zu ermöglichen ("meinten Sie...?").
Dieser Grenzwert hängt allerdings stark von der Güte der übergebenen Adressen ("address") ab.

Parameter coordinate¶

Parameter building_coordinate¶

Parameter time¶

Achtung¶

1. Zeitangaben in ISO 8601 Format
2. timeframe_start,timeframe_end, waiting_time werden nur ausgegeben, wenn auch Zeitfenster angegeben worden sind.

Beispiel¶

curl -u test:test -H "Content-Type: application/json" localhost:3000/getresult?tid=

  {
    "tour": {
      "roundtrip": true,
      "tollfree": false,
      "optimize": "time",
      "avoid_highway": false,
      "uid": "123",
      "status": "scheduled" 
    },
    "waypoints": [
      {
        "uid": "34",
        "address": {
          "locality": "München",
          "postcode": "80803",
          "street": "Pündterplatz 8" 
        },
        "coordinate": {
          "lat": 48.163415,
          "lon": 11.577531
        },
        "times": {
          "arrival": "2013-02-19T19:33:13+01:00",
          "departure": "2013-02-19T15:11:24+01:00" 
        }
      },
      {
        "uid": "56",
        "address": {
          "locality": "München",
          "postcode": "80331",
          "street": "Tal 1" 
        },
        "coordinate": {
          "lat": 48.136415,
          "lon": 11.577531
        },
        "times": {
          "arrival": "2013-02-19T15:22:46+01:00",
          "departure": "2013-02-19T15:22:46+01:00",
          "duration_of_stay": null,
          "timeframe_start": "2013-02-19T15:21:46+01:00",
          "timeframe_end": "2013-02-19T15:23:46+01:00",
          "waiting_time":0
        }
      },
      {
        "uid": "26",
        "address": {
          "locality": "Nürnberg",
          "postcode": "90403",
          "street": "Weintraubengasse 1" 
        },
        "coordinate": {
          "lat": 49.454345,
          "lon": 11.073495
        },
        "times": {
          "arrival": "2013-02-19T17:01:35+01:00",
          "departure": "2013-02-19T18:01:35+01:00",
          "duration_of_stay": 60,
          "timeframe_start": null,
          "timeframe_end": null,
          "waiting_time":0
        }
      }
    ]
  }

Webservice-Status¶

Der Webservice-Status-Aufruf¶

https://webservice.tourenplaner.biz/getstatus?tid=<transaktions-ID> (Achtung Header "Content-Type: application/json" mus mit übergeben werden)
oder
https://webservice.tourenplaner.biz/getstatus.json?tid=<transaktions-ID>

Das JSON-Object¶

Parameter status¶

Parameter error_text¶

Parameter time_window_error¶

JSON Objekt mit Fehlerstruktur zur Fehlermeldung (Zeitplanung mit Zeitfenstern).

Zeitplanung mit Zeitfenster Fehler 1:¶

Ein Punkt konnte nicht vom Startpunkt aus erreicht werden (innerhalb des Zeitfensters).

"time_window_error": {
    "type": 1,
    "nr": 2,
    "name": "Punkt 3",
    "start_depo": "2:00 Uhr",
    "fahrzeit": "0h:10m",
    "ankunft_kunde": "2:10 Uhr",
    "timeframe_start": "1:30 Uhr",
    "timeframe_end": "1:45 Uhr" 
}

Zeitplanung mit Zeitfenster Fehler 2:¶

Zwischen 2 Punkten reicht die Zeit nicht, sie innerhalb einer Tour anzufahren

"time_window_error": {
  "type": 2,
  "nr1": 2,
  "nr2": 3,
  "name1": "Name Punkt1",
  "name2": "Name Punkt2",
  "timeframe_start1": "3:30 Uhr",
  "timeframe_end1": "3:45 Uhr",
  "timeframe_start2": "3:30 Uhr",
  "timeframe_end2": "3:45 Uhr",
  "start_kunde1": "4:30 Uhr",
  "stop_kunde2": "6:12 Uhr",
  "start_kunde2": "4:30 Uhr",
  "stop_kunde1": "6:10 Uhr",
  "fahrzeit12": "1h:42m",
  "fahrzeit21": "1h:40m",
  "aufenthalt_kunde1": "1h:00m",
  "aufenthalt_kunde2": "1h:00m" 
}

Webservice-StaticMap¶

Statische Karte kann mit Route /get_static_map?tid=xxx angefordert werden.

Ausgabe-Steuerung¶

durch JSON-Objekt im POST-Request. Beispiel-JSON:

{
  "static_map": {
    "file_name": "mein_image.jpg",
    "disposition": "attachment",
    "mapsize_width": 800,
    "mapsize_height": 800
  }
}

zulässige Werte / Beschränkung:¶

mapsize_width 80 - 900 (Pixel)
mapsize_height 80 - 834 (Pixel)
disposition "attachement" oder "inline" ("Download/Speichern"-Header oder normaler Header zum Gebrauch auf Website)

Default-Werte:¶

file_name "staticmap.jpg"
disposition "attachement"
mapsize_width 400
mapsize_height 400

Fehlerfall¶

Im Fehlerfall wird ein JSON-Objekt der Form
{code: xx, description: 'yy'}
ausgeliefert.

Erfolgsfall¶

Konnte die Karte erstellt werden, wird sie mit HTTP-Statuscode 200 und Header "image/jpg" sowie weiteren Headern - abhängig von Parameter "disposition" - als JPEG-Image ausgeliefert. In diesem Fall ist keine JSON-Ausgabe möglich.

Zwischen 1 und 25 Wegepunkten werden Standardmarker und Route angezeigt, über 25 Punkten werden lediglich durchnummerierte Marker angezeigt.

vor Verwendung¶

Es ist vor Verwendung zu prüfen, ob der MIME-Type "image/jpg" ist. Wenn nicht, enthält die Rückgabe kein Image, sondern das Fehler-JSON.

Beispielaufruf mit Curl¶

tid=xxx ersetzen durch gültige tid. Die Ausgabe von curl wird in eine Datei umgeleitet, ansonsten sieht man im Erfolgsfall nur "binary"-Code auf dem Screen.

curl -u test:test -XPOST -H "Content-Type: application/json" "localhost:3000/get_static_map?tid=xxx" -d '
{
  "static_map": {
    "file_name": "mein_image.jpg",
    "disposition": "attachment",
    "mapsize_width": 800,
    "mapsize_height": 800
  }
}
' > mein_image.jpg

Beispiel-Ergebnis¶

Webservice-Optimierung¶

Der Webservice-Optimierung-Aufruf¶

Wenn man die aktuelle Tour im Modus 'nur anzeigen' gestartet hat, kann man mit diesem Aufruf
die Optimierung starten

https://webservice.tourenplaner.biz/optimize?tid=<transaktions-ID>
oder
https://webservice.tourenplaner.biz/optimize.json?tid=<transaktions-ID>

GET Parameter¶

Beispiel:¶

curl -u test:test -H "Content-Type: application/json" "localhost:3000/optimize?tid=123456" 
curl -u test:test -H "Content-Type: application/json" "localhost:3000/optimize?tid=123456&time_window=true&time_window_caclculation_time=120" 

Postleitzahlen entlang der Tour¶

Um zusätzlich mögliche Kundenbesuche entlang einer Tour identifizieren zu können, besteht die Möglichkeit, nach den von der Tour tangierten PLZ-Gebieten zu suchen.
Mit den Ergebnissen kann z.B. im CRM, ERP, usw. nach weiteren Kunden gesucht werden („welche Kunden sind in den PLZ, die von der Tour berührt/geschnitten werden?“), die anschließend in die Tour integriert werden könnten.

Webservice-Aufruf¶

Ohne Puffer:¶

https://webservice.tourenplaner.biz/get_postcodes_along_tour?tid=<transaktions-ID>
oder
https://webservice.tourenplaner.biz/get_postcodes_along_tour.json?tid=<transaktions-ID>

Dieser Aufruf liefert die Postleitzahlen aller PLZ-Gebiete zurück, die von der Tour-Linie be-rührt/geschnitten werden (im Bild unten gelb dargestellt).

Optional zusätzlich mit Puffer:¶

https://webservice.tourenplaner.biz/get_postcodes_along_tour?tid=<transaktions-ID>&buffer=<Meter>
oder
https://webservice.tourenplaner.biz/get_postcodes_along_tour.json?tid=<transaktions-ID>&buffer=<Meter>

Dieser Aufruf liefert die Postleitzahlen aller PLZ-Gebiete zurück, die von der der gepuffertenTour-Linie (=Polygon) berührt/geschnitten werden (im Bild unten gelb dargestellt).

Der Puffer wird in der Projektion "Lambert Azimuthal Equal Area" angewandt (PLZ für Europa).

Ergebnis¶

{
  "postcodes": ["80796","80797","80801","80802","80803","80805"]
}

Erweiterung¶

{
  "data": [
  {
  "country": "DE",
  "postcodes": ["80796","80797","80801","80802","80803","80805"]
  },
  {
  "country": "AT",
  "postcodes": ["1000", "1001"]
  }
  ]
}

h3. Voraussetzung

Für diese Funktion ist für Abfragen außerhalb Deutschlands der Erwerb von Lizenzen für PLZ Geometriedaten erforderlich (deutsche PLZ sind kostenlos enthalten).

Webservice-AdditionalPoints¶

Es können jederzeit zu einer Tour zusätzliche Punkte hinzugefügt werden.

"waypoints":¶

Geliefert werden muss ein Array mit dem einzelnen Objekt

Es können beliebige key value(String) Paare angegeben werden, diese werden einfach durchgereicht.

address¶

coordinate¶

time¶

Achtung¶

1. Zeitangaben in ISO 8601 Format
2. duration_of_stay wird nicht für den Ersten Punkt ausgewertet.
3. arrival, departure es wir nur ein fixer Termin verwendet.
   1. Es wird beim ersten Datensatz wo es eine arrival oder departure Angabe findet als Fixtermin festgelegt.
   2. Wenn arrival und departure angegeben sind, dann wird arrival als Fixtermin festgelegt.

Beispiel¶

[
     {
        "uid":"1",
        "coordinate" : {"lat":"48.163415","lon":"11.577531"},
        "address": {"locality": "München", "postcode": "80803", "street": "Pündterplatz 8"}
     },
     {
        "uid":"2",
        "coordinate" : {"lat":"49.454345","lon":"11.073495"},
        "address": {"locality": "Nürnberg", "postcode": "90403", "street": "Weintraubengasse 1"}
        "time": {"duration_of_stay" : 60}
     },
     {
        "uid":"3",
        "coordinate" : {"lat":"48.136415","lon":"11.577531"},
        "address": {"locality": "München", "postcode": "80331", "street": "Tal 1"}
     }
]

Curl Beispiel:¶

curl -u test:test -XPOST -H "Content-Type: application/json" "https://webservice.tourenplaner.biz/add_corridor_points?tid=AG-nhaaIPX6DkVwQCOMd1w" -d '
{
  "waypoints": [
     {
        "uid":"20",
        "name" : "Test1",
        "address": {"locality": "Oberschleißheim", "postcode": "", "street": ""}
     },
     {
        "uid":"21",
        "name" : "Test2",
        "address": {"locality": "Moosinning", "postcode": "85452", "street": "Am Bleibach 4a"}
     },
     {
        "uid":"22",
        "name" : "Test3",
        "address": {"locality": "Ahrensburg", "postcode": "22926", "street": "Beimoorkamp 6"}
     },
     {
        "uid":"23",
        "name" : "Test4",
        "address": {"locality": "Saarbrücken", "postcode": "66125", "street": "Beim Weisenstein 13"}
     }
]
}'

Webservice Download¶

Der Webservice-Download-Aufruf¶

https://webservice.tourenplaner.biz/download?tid=<transaktions-ID>&building_coordinates=true&format=<format>

Formate¶

Formate abfragen¶

Man kann sämtliche Formate erhalten mit

https://webservice.tourenplaner.biz/getexportformats

Spezialformate im Browser für Mobile Navigation¶

https://webservice.tourenplaner.biz/google_maps?tid=<transaktions-ID>
https://webservice.tourenplaner.biz/google_maps?tid=<transaktions-ID>&building_coordinates=true
https://webservice.tourenplaner.biz/apple_maps?tid=<transaktions-ID>
https://webservice.tourenplaner.biz/apple_maps?tid=<transaktions-ID>&building_coordinates=true
Oder als Auswahlseite:
https://webservice.tourenplaner.biz/navi_maps?tid=<transaktions-ID>
https://webservice.tourenplaner.biz/navi_maps?tid=<transaktions-ID>&building_coordinates=true

Weitere Aufrufe¶

Webservice-Delete¶

https://webservice.tourenplaner.biz/delete.json?tid=<tid>

Rückgabe¶

HTTP-Statuscode 200 bzw. 500

Dynamische Karte¶

Karte mit einer Tour anzeigen¶

https://webservice.tourenplaner.biz/map_only/<tid>(?building_coordinates=true)

Rückgabe¶

HTTP-Statuscode 200 bzw. 500

Die dynamische Karte kann z.B. als iFrame eingebunden werden.

Gleichzeitiges Anzeigen mehrerer Touren und eines Punktes¶

Diese Funktion kann genutzt werden, um für eine neue Adresse visuell zu bewerten, zu welcher bestehenden Tour diese am nächsten ist.

https://webservice.tourenplaner.biz/map_tours/<tids>?locality=<ort>&street=<straße>

Interaktive Oberfläche (muss freigeschaltet sein)¶

https://webservice.tourenplaner.biz/tid/<tid>(?building_coordinates=true)