DATAFACTORY AUTOCOMPLETE 2.0 (Post & Parcel Germany)
v 1.0
Division: Post, Post und Paket Deutschland

Automatische Vervollständigung postalischer Daten

Am besten geeignet für:

  • Mehr Benutzerfreundlichkeit durch schnelle und komfortable Adresseingabe
  • Korrekte Adressdaten ab dem ersten Kontakt
  • Reduzierung von Retouren durch postalisch korrekte Daten
  • Vereinfachung der Leitcode-Generierung durch DHL-konforme Daten
Region: Deutschland
Used for: Addresse
Übersicht

Sie befinden sich auf der Dokumentations-Seite der DATAFACTORY AUTOCOMPLETE 2.0 API von Post Direkt. In den folgenden Kapiteln bieten wir Ihnen:

Umfang

Bei unvollständigen Adressdaten bietet DATAFACTORY AUTOCOMPLETE 2.0 von Deutsche Post Direkt wirkungsvolle Unterstützung. Integriert in Ihre eigene IT-Infrastruktur können Sie jetzt ganz einfach postalische Daten ergänzen.

Bereits bei der Eingabe der ersten alphanumerischen Zeichen in das Eingabefeld erhalten Sie bis zu 15 Vorschläge. Insgesamt stehen etwa 1,2 Millionen unterschiedliche Adressvorschläge zur Verfügung, darunter alle zustellrelevanten Straßen, mehr als 16.000 Postleitzahlen, 14.000 Ortsnamen und 75.000 Ortsteilnamen sowie 7.000 POSTFILIALE DIREKT-Daten und 4.000 PACKSTATION-Angaben.

Grundlage der automatischen Vervollständigung ist das Straßenverzeichnis auf Basis der Original-Postleitdaten der Deutschen Post. Zudem wurde die API um das Gebäudeverzeichnis erweitert, wodurch eine Vervollständigung der Hausnummer möglich ist. Dies ermöglicht es außerdem einen Leitcode zu generieren, welcher für den Paketversand erforderlich ist. Per Schnittstellenanbindung und Verschlüsselung können Sie schnell und sicher auf stets aktuelle postalische Daten zugreifen.

Benutzung der API

DATAFACTORY AUTOCOMPLETE 2 basiert auf Representational State Transfer (REST).

Die Anfragen werden über HTTP GET Anfragen realisiert. Die Basis URL (Uniform Ressource Locator) für diesen Service ist die folgende: https://autocomplete2.postdirekt.de/autocomplete2

Im weiteren Verlauf werden die URI (Uniform Ressource Identifier) beschrieben, mit denen die Anfragen realisiert werden können.

Hinweis: 
URI wird hier als Resource Identifier in Abgrenzung zu Ressource Locator URL verstanden.

Beispiel:

  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities?postal_code=05
  • https://autocomplete2.postdirekt.de/autocomplete2 is the base URL
  • /search/de/postalcodes_cities?postal_code=05 is the URI

Die Schnittstelle bietet zwei Funktionen. Die Funktion "search" nimmt strukturierte Adressfragmente entgegen und liefert passende Vorschläge. Jeder dieser Vorschläge wird mit einer ID geliefert. Diese ID wird verwendet, um die Funktion "select" aufzurufen, sobald einer der Vorschläge ausgewählt wird und dient zur Verbesserung der Generierung von Vorschlägen.

Vorschläge zur Eingabe

Ein Vorschlag stellt eine Vervollständigung der eingegebenen Daten dar.

Folgende Arten von Anfragen stehen zur Verfügung, welche jeweils eindeutige Vorschläge zurückliefern. Die Auswahl erfolgt über die Auswahl des Pfades des Aufrufs:

  • Suggested postal codes
  • Suggested towns/cities
  • Suggested districts
  • Suggested streets
  • Suggested Packstations
  • Suggested Deutsche Post retail outlets
  • Suggested possible combinations of postal code and town/city
  • Suggested possible combinations of postal code, town/city and district
  • Suggested possible combinations of postal code, town/city and street
  • Suggested possible combinations of all elements
  • Suggested building data including house number suffix (if ordered)

Jede Anfrage wird von DATAFACORY AUTOCOMPLETE mit bis zu 15 Vorschlägen beantwortet. Anhand von drei verschiedenen Adresstypen (A, F, P) kann eine Anfrage vorgefiltert werden.

Benutzerhandbuch

Im Folgenden finden Sie einen Überblick, wie Sie Zugang zur API erhalten.

Zugang erhalten

Voraussetzung für diese Nutzung der DATAFACTORY AUTCOMPLETE 2 ist eine Vertragsvereinbarung, die Autorisierung durch Freigabe seitens POST DIREKT, die Authentifizierung seitens des KUNDEN durch Eingabe von Benutzername und Passwort sowie die Übermittlung der UUID (Universally Unique Identifier/ Identifikator) bei Vorschlagsauswahl durch den KUNDEN.

Freigabe beantragen:

Angebot anfordern

Deutsche Post Direkt GmbH
Junkersring 57
53844 Troisdorf
Fon +49 2241 2661-0
Fax +49 2241 2661-1111

Authentifizierung

Der Benutzer der Schnittstelle benötigt einen Account, der durch Deutsche Post Direkt die notwendige Autorisierung für Autocomplete 2 erhalten hat. Die Authentifizierung als Inhaber dieses Accounts erfolgt mittels HTTP Basic Authentifizierung gegen die Token-Schnittstelle /token. Alle nachfolgenden Anfragen werden mittels eines sogenannten "Tokens" durchgeführt, der bei der initialen Authentifizierung erstellt und an den Benutzer übermittelt wird. Erst wenn der Token ungültig wird (zeitlich begrenzt auf 15 min), muss erneut der Benutzername und das Passwort für diesen Account in dem "Authorization"-Header eines HTTP-Request übermittelt werden. Der Nutzer hat diese Daten vor dem Zugriff Dritter zu schützen.

Deutsche Post Direkt Webservice

  • Adresse der Applikation:                        https://autocomplete2.postdirekt.de/autocomplete2
  • Adresse der Token-Schnittstelle:       https://autocomplete2.postdirekt.de/autocomplete2/token
  • Verantwortliche Organisation:            Deutsche Post Direkt GmbH

Verschlüsselung

Die Kommunikation mit der Schnittstelle erfolgt über HTTPS und ist somit SSL verschlüsselt.

Die Nutzung der Schnittstelle erfolgt über eine verschlüsselte Verbindung, um die mitgelieferten Daten zur Authentifizierung vor dem Zugriff Dritter zu schützen. Die gelieferten Vorschläge müssen bei der weiteren Verwendung nicht verschlüsselt werden.

Fehlercodes

Jede Anfrage wird mit einem HTTP-Response beantwortet. Zunächst sollte der Status der HTTP-Response überprüft werden.

Code             Status                                    Beschreibung

200                 OK                                         Die Anfrage wurde korrekt beantwortet. Die Response
                                                                        muss den Rückgabewert "Ergebnisse" beinhalten. 

400                 BAD REQUEST                 Entweder fehlt ein notwendiger Parameter oder der
                                                                        Parameter ist nicht valide (exakte Fehlerbeschreibung beachten). 

401                 UNAUTHORIZED            Der Benutzer ist nicht autorisiert, Autocomplete 2 zu nutzen
                                                                        (Benutzername / Passwort falsch oder fehlende Berechtigungen). 

403                 FORBIDDEN                       Die Anfrage wurde mangels Berechtigung des Clients abgewiesen.

404                 NOT FOUND                       Die angefragte Resource wurde nicht gefunden.

500                 Internal Server                  Interner Serverfehler.

Testssuite

Die DATAFACTORY AUTOCOMPLETE 2 können wir Ihnen für Testzwecke zunächst innerhalb einer Testphase anbieten.

Die Testphase beinhaltet:

1. bis zu max. 6.000 tatsächlich ausgewählte Vorschläge (Der Report erfolgt auf Basis der übermittelten Universally Unique Identifier UUID)

2. max. 2.000 tatsächlich ausgewählte Vorschläge im Rahmen eines Stresstests (Für diesen Test ist vorab ein fest definiertes Zeitfenster mit Deutsche Post Direkt abzustimmen)

Sofern der Kunde während der Testphase nicht von der Option in Ziffer 2. Gebrauch macht, erhöht sich die Anzahl der tatsächlich ausgewählten Vorschläge nach Ziffer 1. auf max. 8.000.

Preis für Testphase auf Anfrage.

Jede weitere Anfrage über Option in Ziffer 1 & 2 hinaus wird gesondert berechnet.

(Der Report erfolgt auf Basis der übermittelten UUID).

Der Testzeitraum läuft maximal 8 Wochen ab Erhalt der Auftragsbestätigung von Deutsche Post Direkt.

Testphase beantragen

Benutzerhandbuch

Parameter

Die Schnittstelle muss mit einem oder mehreren Parameter aufgerufen werden. In diesem Abschnitt werden alle Parameter der Schnittstelle aufgeführt.

Parameter

Typ

Beschreibung

Beispiel

country

Path parameter

Über den Parameter kann bestimmt werden, für welches Land die Vorschläge zur Vervollständigung kommen sollen.

/search/de/cities?

 

uuid

Query parameter

Dieser Parameter wird lediglich für das Feed-back benötigt. Sobald der Anwender einen der Vorschläge auswählt, sollte dessen UUID, sowie die Parameter gesendet werden die zur Generierung der Vorschläge herangezogen wurden.

?uuid=abcd...

postal_code

 

Query parameter

Dieser Parameter sollte verwendet werden, wenn es sich um ein Kombinationsfeld handelt und somit unklar ist, welche Adressinformation die jeweiligen gelieferten Adressfragmente darstellen. Es werden Vorschläge geliefert bei denen jedes der Fragmente in mindestens einer der Adressinformationen vorhanden ist.

?postal_code=538

 

city

Query parameter

Dieser Parameter sollte verwendet werden, wenn es sich um strukturierte Daten handelt, z. B. ein eigenes Feld für den Ort existiert. Es werden lediglich Vorschläge geliefert, deren Ort die im Parameter gelieferten Fragmente enthält.

?city=Tro

district

Query parameter

Dieser Parameter sollte verwendet werden, wenn es sich um strukturierte Daten handelt, z. B. ein eigenes Feld für den Ortsteil existiert. Es werden lediglich Vorschläge geliefert, deren Ortsteil die im Parameter gelieferten Fragmente enthält.

?district=Kri

street

Query parameter

Dieser Parameter sollte verwendet werden, wenn es sich um strukturierte Daten handelt, z. B. ein eigenes Feld für die Straße existiert. Es werden lediglich Vorschläge geliefert, deren Straßen-Wert die im Parameter gelieferten Fragmente enthält.

?street=Jun

address_type

Query parameter

Dieser Parameter ist optional und kann verwendet werden, wenn die aufgerufene Funktion nur Informationen von einem Typ, z. B. ¿Strasse` liefern soll. In diesem Fall kann mit Hilfe dieses Parameters angegeben werden, welche Informationen gewünscht sind. Wird der Parameter nicht verwendet, so werden die Daten nicht gefiltert.

A -> Es sollen nur Straßen (Anschrift) geliefert werden.

F -> Es sollen nur Postfilialen (Nummern) geliefert werden.

P -> Es sollen nur Packstationen (Nummern) geliefert werden.

?address_type=A

combined (street)

Query parameter

Dieser Parameter sollte verwendet werden, wenn es sich um ein Kombinationsfeld handelt und somit unklar ist, welche Adress-information die jeweiligen gelieferten Adress-fragmente darstellen. Es werden Vorschläge geliefert, bei denen jedes der Fragmente in mindestens einer der Adressinformationen vorhanden ist. Der combined-Parameter kann nicht in Kombination mit den oben genannten Parametern verwendet werden (Ausnahme: combined + address_type-Parameter).

?combined=53 Tr Jun

?combined=53 Tr Jun&adress_type=a

house_ number

 

Query parameter

 

Dieser Parameter sollte verwendet werden, wenn es sich um strukturierte Daten handelt, z. B. ein eigenes Feld für die Hausnummer existiert. Es werden lediglich Vorschläge geliefert, deren Hausnummern die im Parameter gelieferten Fragmente enthält.

?house_number =57

 

distribution_ code

 

Query parameter

 

Dieser Parameter sollte verwendet werden, wenn es sich um strukturierte Daten handelt, z. B. ein eigenes Feld für den Leitcode existiert. Es werden lediglich Vorschläge geliefert, deren Leitcode die im Parameter gelieferten Fragmente enthält.

?combined=53844286057

 

combined

(buildings)

Query parameter

 

Dieser Parameter sollte verwendet werden, wenn es sich um ein Kombinationsfeld handelt und somit unklar ist, welche Gebäude-informationen die jeweiligen gelieferten Gebäudefragmente darstellen. Es werden Vorschläge geliefert, bei denen jedes der Fragmente in mindestens einer der Gebäude-informationen vorhanden ist. Der combined-Parameter kann nicht in Kombination mit den oben genannten Parametern verwendet werden.

?combined=53 Tr Jun 57

 

Anfragesyntax

Die Parameter werden als Schlüssel-Wert-Paare (schlüssel=wert) an den URI gehangen. Die einzelnen Parameter können in dem Abschnitt Parameter nachgelesen werden. Sollte eine Kombination verwendet werden, so sind die einzelnen Schlüssel-Wert-Paare durch das Zeichen "&" voneinander zu trennen.

Nachfolgend einige Beispiele:

  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities?postal_code=531&city=B
  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities?city=Bo
  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities?combined=53 Bo
  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities?postal_code=503
  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities_streets?street=Fried
  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities_streets?city=Bo&postal_code=531&street=Fri
  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities_streets?combined=Bo 531 Fri
  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/buildings?postal_code=531&city=B&house_number=1
  • https://autocomplete2.postdirekt.de/autocomplete2/search/de/buildings?combined=53 Kri Jun 5

Beispiel: Anfrage mit unvollständiger Straße

Unter Berücksichtigung der PLZ und des Ortes bekommt man durch die Anfrage mit unvollständigem Straßennamen das richtige Ergebnis:
GET/autocomplete2/search/de/postalcodes_cities_streets?street=Jun&postal_code=53844&city=Troisdorf

incomplete street

Beispiel: Anfrage auf Gebäudeebene

Unter Berücksichtigung der Eingabe der Felder PLZ Ort (Ortsteil), Straße und Hausnummer im Kombinationsfeld erhält man mit unvollständigen Werten die korrekte eingegrenzte Gebäudeliste.

GET/autocomplete2/search/de/buildings?combined=53 Kri Jun 5

Example_Request_building_level

Beispiel: Einschränkung eines Adresstypen: Packstation

Durch den Parameter Type kann hierbei eine Vorfilterung nach Packstation vorgenommen werden. Die Nummer wird bei Packstation wie auch Postfiliale Direkt im Straßenfeld übermittelt. Ohne Angabe einer Straße werden in diesem Beispiel alle vier bekannten Packstationsnummern zurückgeliefert:

GET/autocomplete2/search/de/postalcodes_cities_streets?street=1&postal_code=53113&city=Bonn&address_type=P

Example_Restriction_address_type_Packstation

Selects

Sobald der Anwender einen der Vorschläge auswählt, muss ein Feedback an die Anwendung geschickt werden. Dieses Feedback besteht aus der UUID (Universally Unique Identifier) des ausgewählten Vorschlags, sowie aus den Daten, die zur Generierung der Vorschläge versendet wurden. Die Verwendung der Funktionen für das Feedback geschieht analog zu den Funktionen zur Vorschlagsgenerierung, mit dem Unterschied, dass die UUID übermittelt wird und eine andere URL aufgerufen wird.

Nachfolgend ein Beispiel:

https://autocomplete2.postdirekt.de/autocomple2/de/select/postalcodes_cities_streets?uuid=78647

Rückgabeformat

Dieser Abschnitt stellt die Formate dar, in denen die Ergebnisse geliefert werden können. Informationen zu den gelieferten Ergebnissen, können im Abschnitt Rückgabewert nachgelesen werden.

Mittels des HTTP-Request-Header ¿Accept¿ kann definiert werden, in welchem Format die Ergebnisse geliefert werden sollen. Ist dieser Header nicht vorhanden oder enthält der Header mehrere oder keines der unterstützten Formate, so wird im JSON-Format geliefert.

Nachfolgend das Format sowie der Wert der im Header gesetzt werden muss, um die Antwort in diesem Format zu erhalten.

 

Format       Accept-Header-Wert

JSON          application/json;charset=UTF-8

 

FAQ

Bei funktionalen und technischen Fragen wenden Sie sich bitte an:

dataservices@postdirekt.de

Support

IT Customer Support 

Email: dataservices@postdirekt.de