Automatic completion of postal data
- More user friendly than ever with fast and convenient address entry
- Accurate address data from initial contact
- Fewer returns thanks to correct postal data
- Simplified generation of routing codes with DHL-compliant data
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
- You can find contact information for further support and a Testsuite in chapter Additional Information
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.
URI is understood here as a resource identifier as opposed to a resource locator URL.
- 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.
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".
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
Deutsche Post Direkt GmbH
Fon +49 2241 2661-0
Fax +49 2241 2661-1111
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
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.
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.
The interface must be called with one or more parameters. All parameters of the interface are listed in this section.
The parameter can be used to determine for which country the suggestions should be completed.
This parameter is only needed for feedback. As soon as the user selects one of the suggestions, its UUID and the parameters used to generate the suggestions should be sent.
This parameter should be used if the data are structured, e.g., if there is a separate field for the postal code. Only suggestions whose postal code contains the fragments delivered in the parameter are delivered.
This parameter should be used if the data are structured, e.g., if there is a separate field for the city. Only suggestions whose city contains the fragments delivered in the parameter are delivered.
This parameter should be used if the data are structured, e.g., if there is a separate field for the district. Only suggestions whose district contains the fragments delivered in the parameter are delivered.
This parameter should be used if the data are structured, e.g., if there is a separate field for the street. Only suggestions whose street value contains the fragments delivered in the parameter are delivered.
This parameter is optional and can be used if the called function should only deliver information of one type, e.g., "Street". In this case, this parameter can be used to specify which information is required. If the parameter is not used, the data are not filtered.
This parameter should be used if it is a combination field and it is therefore unclear what address information the respective address fragments supplied represent. Suggestions are provided where each of the fragments is present in at least one of the pieces of address information. The "combined" parameter cannot be used in combination with the parameters mentioned above (exception: combined + address_type parameter).
?combined=53 Tr Jun
?combined=53 Tr Jun&adress_type=a
This parameter should be used if the data are structured, e.g., if there is a separate field for the house number. Only suggestions whose house number contains the fragments delivered in the parameter are delivered.
This parameter should be used if the data are structured, e.g., if there is a separate field for the postal routing code. Only suggestions whose postal routing code contains the fragments delivered in the parameter are delivered.
This parameter should be used if it is a combination field and it is therefore unclear what building information the respective building fragments supplied represent. Suggestions are provided where each of the fragments is present in at least one of the pieces of building information. The "combined" parameter cannot be used in combination with the parameters mentioned above.
?combined=53 Tr Jun 57
The parameters are attached to the URI as key-value pairs (key=value). The individual parameters can be found in the Parameter section. If a combination is used, the individual key-value pairs must be separated by the character "&".
Below are some examples:
- https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities?combined=53 Bo
- https://autocomplete2.postdirekt.de/autocomplete2/search/de/postalcodes_cities_streets?combined=Bo 531 Fri
- https://autocomplete2.postdirekt.de/autocomplete2/search/de/buildings?combined=53 Kri Jun 5
Example: Request with incomplete street
Taking into account the postal code and the city, a request with an incomplete street name will give you the correct result:
Example: Request at the building level
Taking into account the input of the postal code, city (district), street and house number fields in the combo box, incomplete values result in the correctly delimited building list.
GET/autocomplete2/search/de/buildings?combined=53 Kri Jun 5
Example: Restriction of an address type: Packstation
The Type parameter allows pre-filtering by Packstation. The number is transmitted in the street field for both Packstation and Postfiliale Direkt. If no street is specified, all four known Packstation numbers are returned in this example:
As soon as the user selects a suggestion, feedback must be sent to the application. This feedback consists of the universally unique identifier (UUID) of the selected suggestion and the data sent to generate the suggestion. The feedback functions are used in the same way as the suggestion generation functions, except that the UUID is transferred and a different URL is called.
Below is an example:
This section presents the formats in which the results can be delivered. For information on the delivered results, refer to the Return value section.
You can use the HTTP request header "Accept" to define the format in which the results are to be delivered. If this header is not available or if the header contains several or none of the supported formats, the results are delivered in JSON format.
Below you can see the format and the value that must be set in the header to receive the response in this format.
For professional and technical questions, please contact:
IT Customer Support