Back to ADDRESSA

Introduction to Addressa

ADDRESSA is an online address validation solution that verifies and validate international postal addresses in real time.

You can access ADDRESSA over Secure Sockets Layer (SSL) connections. ADDRESSA can be integrated in common CRM systems, online shops or other solutions where address varification is needed.

This documentation is tailored to address validation and verification for Germany. Other countries will be added soon.

Key Features

ADDRESSA provides two main features: Address autocomplete and address validation. Please consult the appropriate section of this documentation.

Autocomplete Plug In

Requirements

  • Ability to add HTML to your web page
  • All your address input fields need to have a unique identifier (#id, .class, input[name='your-input-name'] or similar)
  • jQuery 1.10 or newer

Implementation

Copy and paste this code into your web page: 

<script src="//addressa.de/v2/autocomplete.min.js"></script>
<link rel="stylesheet" href="//addressa.de/v2/addressa.css"></script>


Copy and paste this code into your web page and replace the values with the appropriate #id, .class or input[name='your-input-name'] of your input fields for street, city and zip. 


                            <script>
                            var street = "your-street-input-identifier"
                            var zip = "your-zip-input-identifier"
                            var city = "your-city-input-identifier"
                            </script>

If you do not already fulfill the requirements, you need to copy and paste this code into your web page: 

<script src="//addressa.de/v2/jquery-1.10.2.min.js"></script>
<script src="//addressa.de/v2/jquery-ui.min.js"></script>

Getting Help

If you need help with your set up, write us or call us: +49 30 25 740 160

Autocomplete API

ADDRESSA provides two main features: Address autocomplete and address validation. Please consult the appropriate section of this documentation. Authentication

Request

Authentification

We use API Keys to identify and validate a request. API keys should be sent within the request to provide access to our data. API keys will be generated in your user profile. At the moment user accounts are not implemented. Please request an API key via mail if you are interested in testing our API.

Supported request methods

The Autocomplete API supports only GET requests as the address completion is done in an interactive mode.

Request Parameters

Authentication parameter

A request will only be processed if the request containts a valid API-Key. Please generate an API-Key in your dashboard and include it into every request.

Example

Proper URL construction is required for all API requests. Here is an example URL: 

https://api.addressa/autocomplete?api-key=YOUR-API-KEY-HERE&

Process parameters

ADDRESSA offers you several mandatory and optional parameters you can attach to your request. Let us introduce the options you have. Please note that at least one address parameter needs to be given (street, city or postcode) to be able to make suggestions.

Name Type Default Value Description
street string (empty) Street name
city string (empty) City name
postcode string (empty) ZIP Code
suggestions integer 20 Maximum number of address suggestions. Default is 20, maximal allowed value is 40.
city_filter string (empty) A list of city names, separated by commas, to which to limit the results.
zip_filter string (empty) A list of zipcodes, separated by commas, to which to limit the results.

Response

Format

All output is encoded in JSON. Every valid response will result in a list of suggestions. All address consist of a street, city, cityplus and postcode.

Output

Field Name Type Definition
street varchar(50) Contains the street address.
postcode varchar(50) Contains the zipcode.
city varchar(50) Contains the city.
cityplus varchar(50) Contains the additional information, usually name of the district.

Status Code

All responses have a status header with a numeric value. Please only parse response body that are 200 responses.

Status Code Response and Explanation
200 OK (success!): The response body is a JSON object with a suggestions array containing suggestions based on the supplied input parameters.
404 Not Found: Either your API Key or the name of the parameter is not equal to our records.

Example

The following request could lead to the proceeding response:

Input: 
https://api.addressa/autocomplete?api-key=YOUR-API-KEY-HERE&street=donau&city=berl&

Please note that all query string parameter values must be url-encoded (spaces become + or %20, for example) to ensure that the data is transferred correctly.

Output: 
[
	{
	  "street": "Donaustr.",
	  "postcode": "12043",
	  "city": "Berlin",
	  "cityplus": "Neukölln"
	},
	// more suggestions truncated...
  ]
}

Getting Help

If you need help with your set up, write us or call us: +49 30 25 740 160

Address validation API

Request

Authentification

We use API Keys to identify and validate a request. API keys should be sent within the request to provide access to our data. API keys will be generated in your user profile. At the moment user accounts are not implemented. Please request an API key via mail if you are interested in testing our API.

Supported request methods

This API supports only GET requests.

Proper URL construction is required for all API requests. Here is an example URL: 
https://api.addressa/validate?api-key=YOUR-API-KEY-HERE&

Request Parameters

Authentication parameter

A request will only be processed if the request containts a valid API-Key.

Example

Proper URL construction is required for all API requests. Here is an example URL: 

https://api.addressa/validate?api-key=YOUR-API-KEY-HERE&

Process parameters

ADDRESSA offers you several mandatory and optional parameters you can attach to your request. Let us introduce the options you have.

Important

Please note that at least the street parameter and one other address parameter (street, city or postcode) needs to be given to be able to make suggestions.

Name Type Default Value Description
street string blank The street line of the address, or an entire address
city string blank The city name
postcode string blank The ZIP Code
suggestions integer 5 Maximum number of address suggestions, Max Value: 15
city_filter string (empty) A list of city names, separated by commas, to which to limit the results.

Response

Format

All output is encoded in JSON. Every valid response will result in a list of suggestions. All address consist of a street_line, postcode, city and cityplus.

Output

Field Name Type Definition
street varchar(50) Contains the street address.
postcode varchar(50) Contains the postcode.
city varchar(50) Contains the city.
cityplus varchar(50) Contains the additional information, usually name of the district.

Status Code

Responses will have a status header with a numeric value. This value is what you should check for when writing code to parse the response. The only response body that should be read and parsed is a 200 response.

Status Code Response and Explanation
200 OK (success!): The response body is a JSON object with a suggestions array containing suggestions based on the supplied input parameters.
404 Not Found: Either your API Key or the name of the parameter is not equal to our records.

Example

The following request could lead to the proceeding response:

Input:

Here is an example request with street and postcode fields: 

curl -v 'https://api.addressa.de/validate?
		api-key=YOUR-API-KEY-HERE&
		street=Friedrich&
		postcode=10969&'

Please note that all query string parameter values must be url-encoded (spaces become + or %20, for example) to ensure that the data is transferred correctly.

Output: 

[
	{
	"street": "Friedrichstr.",
	"postcode": "10969",
        "city": "Berlin",
        "cityplus": "Kreuzberg",
	},
	// more suggestions truncated...
]

Getting Help

If you need help with your set up, write us or call us: +49 30 25 740 160