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

• Einen Überblick über die von der DATAFACTORY AUTOCOMPLETE 2.0 API abgedeckten fachlichen Funktionen
• Die technische Dokumentation der API
  • Das Benutzerhandbuch beschreibt Verbindungen und Authentifizierung 
  • Open API Spezifikation in Referenzdokumentation
  • Code-Beispiele und Postman-Testsuite unter Downloads
• Im Kapitel Weitere Informationen finden Sie Kontaktinformationen zum weiterführenden Support.

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.

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

• Technische Details zu den API-Aufrufen finden Sie hier: "API Specification".
• Weitere Hinweise zur Verwendung der API finden Sie im Abschnitt  "Additional Information".

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.

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