geplante API Dokumentation
++
+-
+
- 1. Einführung +
- 2. + Interfaces + + +
- 3.
+ Methoden
+
-
+
- 3.1 Route +
- 3.2 Dist +
- 3.3 Geocode +
- 3.4 SMS +
- 3.5 Bank +
- 3.6 Boxcar +
- 3.7 Postcode-Match +
- 3.8 Postcode-Shape +
+ - 4. Fehlermeldungen +
Einführung
++ Die Mesngr API enthält viele Funktionen, die von Fahrradkurierdiensten benötigt werden. +
+Interfaces
++ Die Mesngr API stellt verschiedene Interfaces bereit, die unterschiedlich angesprochen werden, aber das selbe tun. +
+XML-RPC
+
+ Interface-URI: http://api.mesngr.de/xmlrpc
+
+ Die aufgerufene Methode wird dabei im <methodName /> übergeben.
+
+ Das XML-RPC Interface nimmt die Parameter der aufgerufenen Methode als <struct /> inerhalb des ersten <param /> entgegen, alle weiteren <param />s werden ignoriert.
+
+ Zeichen außerhalb des ASCII-Sets sind als HTML Entities zu übergeben. +
+XML
+
+ Interface-URI: http://api.mesngr.de/xml/<methode>
+
+ Die aufgerufene Methode wird im Pfad der Interface-URI übergeben. +
++ Parameter können via HTTP per GET oder POST im Format application/x-www-form-urlencoded übergeben werden. +
++ Die Ausgabe erfolgt als XML Markup. +
+JSON
+
+ Interface-URI: http://api.mesngr.de/json/<methode>
+
+ Die aufgerufene Methode wird im Pfad der Interface-URI übergeben. +
++ Parameter können via HTTP per GET oder POST im Format application/x-www-form-urlencoded oder JSON-Objekt übergeben werden. +
++ Die Ausgabe erfolgt als JSON-Objekt. +
+JSONP
+
+ Interface-URI: http://api.mesngr.de/jsonp/<methode>?callback=<callback>
+
+ Die aufgerufene Methode wird im Pfad der Interface-URI übergeben. +
++ Der Name für die Callback-Methode wird als Parameter Callback übergeben. +
++ Parameter können via HTTP per GET im Format application/x-www-form-urlencoded übergeben werden. +
++ Die Ausgabe erfolgt als Javascript-Funktionsaufruf mit einem JSON-Objekt als Parameter. +
+PHP
+
+ Interface-URI: http://api.mesngr.de/php/<methode>
+
+ Die aufgerufene Methode wird im Pfad der Interface-URI übergeben. +
++ Parameter können via HTTP per GET oder POST im Format application/x-www-form-urlencoded übergeben werden. +
++ Die Ausgabe erfolgt als serialisiertes PHP-Objekt. +
+Methoden
+Route
+route
+ Diese Methode ermittelt die Routing-Entfernung zwischen zwei Koordinaten. +
+Parameter
+| Parameter | +Typ | +Beschreibung | +
| apikey | +str[20] | +Der API Key | +
| type | +enum[car,bicycle,foot] | +Die gewünschte Routing-Methode | +
| flon | +float | +Der Längengrad des Startpunktes | +
| flat | +float | +Der Breitengrad des Startpunktes | +
| tlon | +float | +Der Längengrad des Zielpunktes | +
| tlat | +float | +Der Breitengrad des Zielpunktes | +
Ausgabe
+| Parameter | +Typ | +Beschreibung | +
| status | +bool | +Fehlerindikator | +
| distance | +float | +Die ermittelte Routing-Distanz in km | +
Dist
+dist
+ Diese Methode ermittelt die direkte Entfernung zwischen zwei Koordinaten. +
+Parameter
+| Parameter | +Typ | +Beschreibung | +
| apikey | +str[20] | +Der API Key | +
| flon | +float | +Der Längengrad des Startpunktes | +
| flat | +float | +Der Breitengrad des Startpunktes | +
| tlon | +float | +Der Längengrad des Zielpunktes | +
| tlat | +float | +Der Breitengrad des Zielpunktes | +
Ausgabe
+| Parameter | +Typ | +Beschreibung | +
| status | +bool | +Fehlerindikator | +
| distance | +float | +Die ermittelte Routing-Distanz in km | +
Geocode
+geocode
+ Ermittelt die Koordinaten zu einer Adresse. Diese Methode ist Kostenpflichtig. +
+Parameter
+| Parameter | +Typ | +Beschreibung | +
| apikey | +str[20] | +Der API Key | +
| type | +enum[fast, complete] | +Die Eingabemethode. Im Modus fast wird der Parameter number an den Parameter street angehängt sowie der Parameter postcode vor den Parameter city; Die Parameter postcode und number werden dann ignoriert. |
+
| street | +str | +Der Straßenname der Adresse | +
| number | +str | +Die Hausnummer der Adresse | +
| postcode | +str | +Die Postleitzahl der Adresse | +
| city | +str | +Die Stadt der Adresse | +
| country | +str | +Das Land der Adresse, ISO 3166 | +
Ausgabe
+| Parameter | +Typ | +Beschreibung | +
| status | +bool | +Fehlerindikator | +
| stage | +enum[1,2,3] | +
+ Grad des Erfolges des Geocodings: + 1 → Es stehen mehrere mögliche Adressen zur Auswahl. + 2 → Eine mögliche Adresse als Korrekturvorschlag. + 3 → Die Adresse konnte verifiziert und zugehörige Geokoordinaten ermittelt werden. + |
+
| data | +array | ++ Die ermittelten Adressdaten + | +
| data[i] | +array | ++ Ein ermittelter Adressdatensatz + | +
| data[i][street] | +str | +Name der Straße | +
| data[i][nr] | +str | +Hausnummer | +
| data[i][fragment] | +str | +Hausnummernzusatz (z.B. a bei 12a) | +
| data[i][postcode] | +str | +Postleitzahl | +
| data[i][city] | +str | +Ort | +
| data[i][country] | +str[2] | +Land (gemäß ISO 3166) | +
| data[i][accuracy] | +int | +Genauigkeit (Genau > Ungenau) | +
| data[i][lat] | +float | +Breitengrad | +
| data[i][lon] | +float | +Längengrad | +
SMS
+sms
+ Versendet eine SMS-Nachricht. Diese Methode ist kostenpflichtig. +
+Parameter
+| Parameter | +Typ | +Beschreibung | +
| apikey | +str[20] | +Der API Key | +
| from | +str[11]|tel[16] | +Der gewünschte Absender (optional) | +
| to | +tel[15] | +Emfänger-Nummer (gemäß ITU-T E.123) | +
| ref | +str | +Referenz für Antworten | +
| callback | +str | +Callback-URL für SMS-Antworten. Noch nicht implementiert. | +
Ausgabe
+| Parameter | +Typ | +Beschreibung | +
| status | +bool | +Fehlerindikator | +
Bank
+bank
+ Prüft Bankdaten auf Plausibilität. +
+Parameter
+| Parameter | +Typ | +Beschreibung | +
| apikey | +str[20] | +Der API Key | +
| country | +[de] | +Das Land des Bankdatenformates | +
| bank | +int[8] | +Die Bankleitzahl | +
| account | +int[10] | +Die Kontonummer (optional) | +
Ausgabe
+| Parameter | +Typ | +Beschreibung | +
| status | +bool | +Fehlerindikator | +
| bank | +array | +Der Bankdatensatz | +
| bank[id] | +int[8] | +Die Bankleitzahl | +
| bank[name] | +str | +Name der Bank | +
| bank[city] | +str | +Stadt | +
| bank[bic] | +str | +Der BIC der Bank | +
| account | +array | +Der Kontodatensatz | +
| account[id] | +int[10] | +Die Kontonummer | +
Boxcar
+boxcar
+ Sendet eine Push-Notification via Boxcar. Ist der Boxcar-user nicht subskribiert, wird statt der Nachricht eine Subskriptions-Anfrage gesendet. +
+Parameter
+| Parameter | +Typ | +Beschreibung | +
| apikey | +str[20] | +Der API Key | +
| to | +str | +E-Mail-Adresse des Boxcar-Accounts | +
| from | +str | +Absender | +
| message | +str | +Die Nachricht | +
| url | +str | +Die URL die aufgerufen werden soll | +
Ausgabe
+| Parameter | +Typ | +Beschreibung | +
| status | +bool | +Fehlerindikator | +
Postcode-Match
+postcodematch
+ Liefert die Schwerpunkt-Koordinaten aller Postleizahlengebiete innerhalb eines Bereiches. +
+Parameter
+| Parameter | +Typ | +Beschreibung | +
| apikey | +str[20] | +Der API Key | +
| bbox_n | +float | +Maximale Latitude | +
| bbox_s | +float | +Minimale Latitude | +
| bbox_e | +float | +Maximale Longitude | +
| bbox_w | +float | +Minimale Longitude | +
Ausgabe
+| Parameter | +Typ | +Beschreibung | +
| status | +bool | +Fehlerindikator | +
| postcodes | +array | +Ergebnisse | +
| postcodes[i] | +array | +Ergebnis | +
| postcodes[i][postcode] | +str | +Postleitzahl | +
| postcodes[i][lat] | +float | +Latitude des Schwerpunktes | +
| postcodes[i][lon] | +float | +Longitude des Schwerpunktes | +
Postcode-Shape
+postcodeshape
+ Gibt eine Näherung an die geografische Definition eines Postleitzahlengebietes aus. +
+Parameter
+| Parameter | +Typ | +Beschreibung | +
| apikey | +str[20] | +Der API Key | +
| postcode | +str | +Die Postleitzahl des Gebietes | +
Ausgabe
+| Parameter | +Typ | +Beschreibung | +
| status | +bool | +Fehlerindikator | +
| postcode | +str | ++ |
| center | +array | ++ |
| center[lat] | +flaot | ++ |
| center[lon] | +flaot | ++ |
| bbox | +array | ++ |
| bbox[n] | +float | ++ |
| bbox[s] | +float | ++ |
| bbox[w] | +float | ++ |
| bbox[e] | +float | ++ |
| shape | +array | +Alle Shapes dieses Postleitzahlengebietes | +
| shape[i] | +array | +Ein Shape des Postleitzahlengebietes | +
| shape[i][j] | +array | +Ein Punkt des Shapes | +
| shape[i][j][lat] | +array | +Die Latitude des Punktes | +
| shape[i][j][lon] | +array | +Die Longitude des Punktes | +
Fehlercode
+
+ Wenn der Ausgabeparameter status einen Fehler indiziert, werden alle weiteren Ausgabeparameter ersetzt durch die Parameter code und msg.
+
| Parameter | +Typ | +Beschreibung | +
| status | +bool | +Fehlerindikator | +
| code | +int[3] | +Fehlercode | +
| msg | +str | +Fehlermeldung | +
| result | ++ | Optionale weitere Daten | +
Fehlercodes
+| Code | +Bedeutung | +
| 900 | +Die aufgerufene Methode existiert nicht | +
| 901 | +Der API-Key ist ungültig | +
| 902 | +Fehler in externer API | +
| 903 | +Encoding-Problem: Ein Nicht-UTF-8-Zeichen hat den Parser gestoppt | +
| 904 | +Es wurden keine gültigen JSON-Daten im POST-Request gefunden | +
| 910 | +Ungültige Eingabemethode | +
| 911 | +Die eingegebenen Daten reichen nicht aus, um die Adresse zu bestimmen | +
| 912 | +Die Adresse wurde nicht gefunden | +
| 913 | +Für diese Adresse wurden keine Koordinaten gefunden | +
| 914 | +Die Koordinaten für diese Adresse sind nicht eindeutig | +
| 921 | +Ungültige Koordinaten | +
| 922 | +Keine Route gefunden | +
| 930 | +Keine Verbindung zum Gateway | +
| 931 | +Empfänger fehlerhaft | +
| 932 | +Absenderkennung zu lang | +
| 933 | +Nachrichtentext zu lang | +
| 934 | +Messagetyp nicht korrekt | +
| 935 | +Falscher SMS-Typ | +
| 936 | +Fehler bei Login | +
| 937 | +Guthaben zu gering | +
| 938 | +Netz wird von Route nicht unterstützt | +
| 939 | +Feature nicht über diese Route möglich | +
| 940 | +Ungültige BLZ | +
| 941 | +Ungültige Kontonummer | +
| 942 | +Ungültiges Land | +
| 945 | +Ungültiger Empfänger | +
| 946 | +Keine Nachricht angegeben | +
| 947 | +Der Empfänger ist nicht subskribiert | +
| 948 | +Der Empfänger hat den Dienst abgeschaltet | +
| 950 | +Die Postleitzahl ist ungültig. | +
| 951 | +Für diese Postleitzahl gibt es keine Shapes. | +
| 952 | +In diesem Bereich wurden keine Postleitzahlen gefunden. | +
| 953 | +Dieser Bereich enthält zu viele Postleitzahlen. | +
| 999 | +Unbekannter Fehler | +