Setup guide for address lookup

Key features

• Global address autocomplete
• Quick and straightforward setup
• Only pay when a full address is retrieved, with credit packs from £27
• Uses the autocomplete/find and autocomplete/retrieve API endpoints

1. Get an API key

Sign up for a free trial and you'll receive an API key with 300 trial credits for testing. No payment details required - and you can request more trial credits if you need them.

2. Create an address form

Create an address form and add the following fields onto it:

<label for="country">Country:</label>
<select id="country" name="country">
	<option value="uk">United Kingdom</option>
	<option value="us">United States</option>
	<!-- All other countries supported -->
</select>

<label for="search_input">Start typing your address or postcode:</label>
<input type="text" id="search_input" name="search_input">

<label for="address-line-1">Address line 1:</label>
<input type="text" id="address_line_1" name="address_line_1">

<label for="address-line-2">Address line 2:</label>
<input type="text" id="address_line_2" name="address_line_2">

<label for="city">Town / City:</label>
<input type="text" id="post_town" name="post_town">

<label for="state">County / State:</label>
<input type="text" id="county" name="county">

<label for="postcode">Postcode / ZIP Code / Postal code:</label>
<input type="text" id="postcode" name="postcode">

Create a form with the following fields:

1. Country
Type: Dropdown, id="country"
Options:
- United Kingdom, value="uk"
- United States, value="us"

2. Start typing your address or postcode
Type: Single-line text input, id="search_input"

3. Address line 1
Type: Single-line text input, id="address_line_1"

4. Address line 2
Type: Single-line text input, id="address_line_2"

5. Town / City
Type: Single-line text input, id="post_town"
								
6. County / State
Type: Single-line text input, id="county"

7. Postcode / ZIP Code / Postal code
Type: Single-line text input, id="postcode"

Edit the country dropdown and include the countries you want to support. Ensure that each list item has a name (the country name) and a value (its 2-character country code). To limit to just one country, without a dropdown, see the Customisation options.

Save the form.

3. Set up your page

Add a new page or edit an existing one.

Add the form you just created to the page. The method for doing this will depend on the platform you're using. For example, in WordPress, you can embed your form using a shortcode.

Below the form, add a custom HTML block and paste the following code into it:

<script src="https://cdn.jsdelivr.net/gh/postcoder-api/integrator-js@v2/build/integrator.min.js"></script>

<script>
	document.addEventListener('DOMContentLoaded', function () {
		const postcoder = new PostcoderAddressAutocomplete({
			apikey: 'YOUR_API_KEY',
			country: '#country',
			searchinput: '#search_input',
			outputfields: {
				addressline1: '#address_line_1',
				addressline2: '#address_line_2',
				posttown: '#post_town',
				county: '#county',
				postcode: '#postcode',
			},
		});
	});
</script>

Replace YOUR_API_KEY with the API key you received via email after signing up for a Postcoder trial in step one.

Replace the input and output field names (e.g. #country, #address_line_1) with the correct query selector for each form field, such as an ID (#country) or name attribute selector ([name="country"]).

Save the page.

4. Test your page

View your page and confirm that address suggestions appear as you type, and that the form is correctly filled when you select a suggestion. Use the Customisation options to make changes if required.

Note: If you make changes, always provide an option for users to enter their address manually if they cannot find it using your address lookup integration.

5. Review security and alert settings

Before deploying to production, review the API key security guidance and update your settings. You can configure:

• Rate limits: Limit requests to protect your credits
• Trusted IP addresses: For server-side integrations, lock your API key to trusted IP addresses
• Trusted website URLs: For client-side integrations, restrict your API key to trusted website URLs

You can also enable email alerts to help you monitor your account. These include:

• Low credit alerts: Choose when to be notified about low credits
• Credit expiry alerts: Set reminders before your credits expire
• Usage alerts: Get notified about high or zero usage
• Security alerts: Get notified when requests are being rate-limited

We recommend sending alerts to multiple people or a group distribution list so they never depend on one person.

6. Buy credits and go live

To go live, all you need to do is buy a credit pack or set up a monthly plan. There are different sizes to suit your requirements and prices start from just £27. Speak to our team if you have any questions.