Postcode API

International addresses

This API for autocompleting addresses is designed to work the same way for all supported countries.

The API is simple and can be integrated into any system. For web-based systems, such as webshop checkouts, all you need is the provided Javascript library and a small proxy script configured with your account credentials.

API methods

Autocomplete
Get a list of matches based on a single (partial) address string.
Get details
Get all details for an address found using the autocomplete method.
Get supported countries
Get the list of currently supported countries.

Example form with autocompletion

Options
Automatically focus the first autocomplete suggestion.
Automatically select the first full address suggestion on blur.

A few addresses to try:

Postcode.nl international address autocomplete widget

The Postcode.nl autocomplete widget enables people to quickly find and select from a list of address suggestions as they type.

Example implementation

The following example code can be used as a starting point for your implementation.

HTML

<form>
	<input type="text" class="input-autocomplete" placeholder="City, street or postcode">
</form>

Javascript

const inputElement = document.querySelector('.input-autocomplete'),
	autocomplete = new PostcodeNl.AutocompleteAddress(inputElement, {
		autocompleteUrl: 'https://your-proxy-script-autocomplete-url', // Required
		addressDetailsUrl: 'https://your-proxy-script-details-url', // Required
		// Specify more options here...
	});

inputElement.addEventListener('autocomplete-select', function (e) {
	console.log('Selected item:', e.detail);
});

Address selection

When a full address is selected from the autocomplete menu, call the getDetails method and use the result to populate form fields and show the address. Example:

HTML

<form class="autocomplete-example-form">
	<input type="text" class="input-autocomplete" placeholder="City, street or postcode">
	<input type="hidden" name="country">
	<input type="hidden" name="locality">
	<input type="hidden" name="postcode">
	<input type="hidden" name="street">
	<input type="hidden" name="building">
</form>

<address class="autocomplete-result"></address>

Javascript

const inputElement = document.querySelector('.input-autocomplete'),
	resultElement = document.querySelector('.autocomplete-result'),
	form = document.querySelector('.autocomplete-example-form'),
	autocomplete = new PostcodeNl.AutocompleteAddress(inputElement, {
		// Options
	});

inputElement.addEventListener('autocomplete-select', function (e) {
	if (e.detail.precision === 'Address')
	{
		autocomplete.getDetails(e.detail.context, function (result) {
			const fields = ['country', 'locality', 'postcode', 'street', 'building'];

			for (let i = 0, field; field = fields[i++];)
			{
				form.elements[field].value = result.address[field];
			}

			if (typeof result.mailLines !== 'undefined')
			{
				// Show the address.
				resultElement.innerHTML = result.mailLines.join('<br>');
			}
		});
	}
});

Setting defaults

The default value of each option can be set via the defaults object. Any autocomplete instance will then use the new default value.

Javascript

// Set default URL values:
PostcodeNl.AutocompleteAddress.defaults.autocompleteUrl = 'https://autocomplete-url';
PostcodeNl.AutocompleteAddress.defaults.addressDetailsUrl = 'https://details-url';

Options

context: string
Initial autocomplete context. E.g. a country code "nld", "bel" or "deu" to start searching in that country. Default: "nld"
autocompleteUrl: string
URL that will return autocomplete JSON data. Default: undefined
addressDetailsUrl: string
URL that will return address details JSON data. Default: undefined
tags: Object
Text to use with tags. Default:
{
	'unvalidated-housenumber': '(unknown house number)',
	'unvalidated-housenumber-addition': '(unknown house number addition)',
}
cssPrefix: string
Prefix for CSS classnames. Default: "postcodenl-autocomplete-"
minLength: number
Minimum number of characters typed before a search is performed. Default: 1
delay: number
Delay in milliseconds between when a keystroke occurs and when a search is performed. Default: 300
appendTo: string|HTMLElement
Which element the menu should be appended to. Default: document.body
autoFocus: boolean
Focus the first item when the menu is shown. Default: false
autoSelect: boolean
Select the first full address suggestion on blur (if any, and no menu item was selected). Default: false
getResponseMessage: Function
Get screen reader text for a successful response with at least one match. Override this function to translate the message. Default:
function (count)
{
	let message;

	if (count > 1)
	{
		message = count + ' address suggestions available. ';
	}
	else
	{
		message = 'One address suggestion available. ';
	}

	message += 'Use up and down arrow keys to navigate.';

	return message;
}

Methods

setCountry(iso3Code)

Set the country to start searching in.

iso3Code: string
ISO 3166-1 alpha-3 country code.

Trigger a search on the specified input element. If invoked without a term, the current input's value is used.

element: HTMLElement
Input element associated with the autocomplete instance.
term: string
Search query.
xhrGet(url, success) → {XMLHttpRequest}

Create an XMLHttpRequest GET request.

url: string
URL to which the request is sent.
success: Function
Function that is executed if the request succeeds.

Returns: XMLHttpRequest

Object representing the eventual completion/failure of the request, and its resulting value.
getSuggestions(context, term, response) → {XMLHttpRequest}

Get autocomplete matches for the specified context and term.

context: string
A place identifier denoting the context to search in. e.g. “nld”.
term: string
The search query to process. e.g. “2012ES”, “Haarlem”, “Julian”.
response: Function
Function that handles the response.

Returns: XMLHttpRequest

Object representing the eventual completion/failure of the request, and its resulting value.
getDetails(addressId, [dispatchCountry], response) → {XMLHttpRequest}

Get address details for the specified address identifier.

addressId: string
Address identifier returned by a match of precision “Address”.
dispatchCountry (optional): string
Dispatching country ISO3 code, used to determine country address line presence and language. If not given, country is not added in mailLines.
response: Function
Function that handles the response.

Returns: XMLHttpRequest

Object representing the eventual completion/failure of the request, and its resulting value.
renderItem(ul, item) → {HTMLElement}

Method that controls the creation of each menu item.

ul: HTMLElement
Element that the newly created list item must be appended to.
item: Object
Single autocomplete item.

Returns: HTMLElement

List item element containing an autocomplete match.
highlight(str, indices) → {string}

Highlight matched portions in the item label.

str: string
Item label to highlight.
indices: Array.Array.<number>
Array of character offset pairs.

Returns: string

Highlighted string (using <mark> elements).
announce(str)

Announce screen reader text via the live region.

str: string
Text to announce.

Events

autocomplete-open

Triggered when the menu is opened.

Example

inputElement.addEventListener('autocomplete-open', function () {});
autocomplete-close

Triggered when the menu is closed.

Example

inputElement.addEventListener('autocomplete-close', function () {});
autocomplete-focus

Triggered when focus is moved to an item by keyboard (not selecting). The default action is to replace the input element's value with the value of the focused item. Cancel this event to prevent updating the input element's value.

Example

inputElement.addEventListener('autocomplete-focus', function (e) {
	e.preventDefault(); // Event cancelled, input value won't be updated.});
autocomplete-select

Triggered when an item is selected from the menu. Selected item data is available on the detail property of the Event object. Cancel this event to prevent updating the input element's value.

Example

inputElement.addEventListener('autocomplete-select', function (e) {
	console.log('Selected item:', e.detail);
	e.preventDefault(); // Event cancelled, input value won't be updated.});

Triggered before a search is performed. Cancel this event to prevent the request for address suggestions.

Example

inputElement.addEventListener('autocomplete-select', function (e) {
	e.preventDefault(); // Event cancelled, no request made.});
autocomplete-response

Triggered after a search completes, before the menu is shown. Result data is available via the details property of the Event object. Cancel this event to prevent rendering address suggestions.

Example

inputElement.addEventListener('autocomplete-response', function (e) {
	console.log('Address suggestions:', e.detail.matches);
	e.preventDefault(); // Event cancelled, no items added to the menu.});
autocomplete-error

Triggered when the request for autocomplete suggestions fails.

Example

inputElement.addEventListener('autocomplete-error', function (e) {
	console.log('XMLHttpRequest ProgressEvent:', e.detail);
});