You are on the documentation page of the DHL DATAFACTORY AUTOCOMPLETE 2.0 API of Post Direkt. In the following chapters we offer you:

• An Overview of the business functions covered via the API
• The technical documentation of the API
  • The User Guide describes connections and authentication
  • Open API Specification in Reference Docs
  • Code examples in Use Cases,
• You can find contact information for further support and a Testsuite in chapter Additional Information

Scope

DATAFACTORY AUTOCOMPLETE 2.0 from Deutsche Post Direkt offers effective assistance in recording address data. Once integrated into your IT infrastructure, postal data can be simply and conveniently augmented on the basis of original Deutsche Post postcode data.

As soon as the first alphanumerical characters have been entered into the input field, your users will receive up to 15 suggestions to complete the address fields. A total of around 1.2 million different address suggestions are available, including all delivery-relevant streets, more than 16,000 postcodes associated with destinations, 14,000 town/ city names, 75,000 town district names, 7,000 postal retail outlets and 4,000 PACKSTATIONS.

Basis for automatic completion is the street directory based on the original Deutsche Post postal routing data. In addition, the API has been expanded to include the building directory, which makes it possible to complete the house number. This also makes it possible to generate a routing code, which is required for parcel delivery. You can access up-to-date postal data quickly and securely via an interface connection and encryption.

Using the API

DATAFACTORY AUTOCOMPLETE 2.0 is based on Representational State Transfer (REST).

The requests are implemented using HTTP GET requests. The base uniform resource locator (URL) for this service is: https://autocomplete2.postdirekt.de/autocomplete2

The following sections describe the uniform resource identifiers (URIs) with which the requests can be implemented.
 

Note: 
URI is understood here as a resource identifier as opposed to a resource locator URL.

Example:

• 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

The interface offers two functions. The "search" function accepts structured address fragments and provides suitable suggestions. Each of these suggestions is delivered with an ID. This ID is used to call the "select" function as soon as one of the suggestions is selected and serves to improve the generation of suggestions.

Input suggestions

A suggestion represents a completion of the data entered.

The following types of requests are available, each of which returns unique suggestions. The selection is made by selecting the path of the call:

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

DATAFACORY AUTOCOMPLETE will answer each request with up to fifteen suggestions. A request can be pre-filtered using three different address types (A, F, P).

The following provides an overview on how to get access to the API.

• Technical Details on the API calls can be found here: "API Specification".
• Further hints on API usage are given in the section "Additioinal Information".

Get Access

A prerequisite for this use of DATAFACTORY AUTCOMPLETE 2 is a contractual agreement, authorization by approval from POST DIREKT, authentication by the CUSTOMER by entering a user name and password, and transmission of the UUID (Universally Unique Identifier / Identifier) when the CUSTOMER selects a proposal.

Apply for release

Request an offer

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

Authentication

The user of the interface requires an account that has received the necessary authorization for Autocomplete 2 from Deutsche Post Direkt. Authentication as the owner of this account takes place using HTTP Basic authentication against the token interface/token. All subsequent requests are carried out using a "token", which is created during initial authentication and transmitted to the user. Only when the token becomes invalid (limited to fifteen minutes), must the username and password for this account must be retransmitted in the "Authorization" header of an HTTP request. The user must protect these data from access by third parties.

Deutsche Post Direkt webservice

• Address of the application:           https://autocomplete2.postdirekt.de/autocomplete2
• Address of the token interface:     https://autocomplete2.postdirekt.de/autocomplete2/token
• Organization responsible:             Deutsche Post Direkt GmbH

Encryption

Communication with the interface takes place via HTTPS and is therefore SSL encrypted.

The interface is used via an encrypted connection to protect the data provided for authentication against access by third parties. The delivered suggestions do not need to be encrypted for further use.

Error codes

Every request is answered with an HTTP response. The status of the HTTP response should first be checked.
 

Code             Status                                    Description

200                 OK                                        Standard response for success HTTP requests.

400                 BAD REQUEST                The server cannot or will not process the request due to an apparent
                                                                        client error (e.g., malformed request syntax, size too large, invalid
                                                                        request message framing; or deceptive request routing).

401                 UNAUTHORIZED            The User is not authorized tu use Autocomplete 2 (user name/
                                                                        password incorrect or missing authorization).

403                 FORBIDDEN                     The request was rejected because the client was not authorized.

404                 NOT FOUND                     The request resource could not be found.

500                 Internal Server                  A generic error message, given when an unexpected condition
                                                                         was encountered nd no more specific Error message is suitable.
 

We offer DATAFACTORY AUTOCOMPLETE 2.0 for test purposes within a test phase.

The test phase includes:
1.    up to a maximum of 6,000 actually selected suggestions (The report is provided on the basis of the transmitted Universally Unique Identifier, UUID)
2.    a maximum of 2,000 actually selected suggestions as part of a stress test (a firmly defined time window shall be agreed in advance with Deutsche Post Direkt for this test)

If the customer does not make use of the option under Item 2 during the test phase, the number of actually selected suggestions shall increase under Item 1 to a maximum of 8,000.

Any inquiry beyond this number shall be charged at EUR 0.03 (the report is provided on the basis of the transmitted UUID).

The test period runs for a maximum of 8 weeks from the date of receipt of the order confirmation by Deutsche Post Direkt.

Order test phase