Address Capture Implementation Guide

Reduce address entry errors and improve data quality with real-time address autocomplete as users type.

Who Should Use This Guide

For: Business owners and developers integrating address autocomplete without complex setup. You’ll need: A Loqate API key and basic HTML knowledge. Not covered: Tag-based integrations (see Tag Setup) or pre-built platform integrations (see Integrations).

What You’ll Build

An address autocomplete form that:

Shows address suggestions as users type
Fills in complete address details when selected
Works with addresses in over 250 countries
Provides formatted address lines for easy form population

Quick Start

To set up Address Capture, you’ll need an API key. Find out how to get yours here.

Choose Your Approach

Standalone Form
Integrate with Existing Form

Use case: Testing the API or adding to a static pageA self-contained HTML file you can copy and use immediately.Jump to standalone HTML example

Using Shopify or WordPress? Check pre-built integrations.

Add Your Key

Replace YOUR_API_KEY in the code with your actual Loqate API key.

Test

Open your page
Start typing an address like “10 Downing”
Select from the suggestions
Complete address populates automatically

Address Capture supports over 250 countries and territories. Use the Countries parameter to restrict results to specific countries.

Sample Project: Checkout Form Integration

This walkthrough shows how to add address autocomplete to a checkout form. Follow along to see a basic form transform into an intelligent address capture form.

This is a detailed walkthrough. If you just want working code, skip to Integration Example or Standalone HTML Example.

Before: Manual Address Entry

A checkout form with manual address entry: This form works, but users must type complete addresses manually. Let’s add autocomplete.

How Address Capture Works

Address Capture uses a two-step process:

1. Find Step

What it does: Searches for addresses as users type. When to use: On every keystroke or with debouncing (recommended). What you get: A list of matching addresses and containers (groups of addresses). API endpoint: https://api.addressy.com/Capture/Interactive/Find/v1.10/json6.ws Key parameters:

Text - The search term (what the user typed)
Container - Optional ID for drilling down into results
Countries - Optional filter (e.g., “GBR” for UK only)

2. Retrieve Step

What it does: Gets the complete address details. When to use: When a user selects an address from the suggestions. What you get: Full address in multiple formats (lines, elements, label). API endpoint: https://api.addressy.com/Capture/Interactive/Retrieve/v1.00/json6.ws Key parameter:

Id - The unique address identifier from Find results

How They Work Together

User types "10 Dow"
    ↓
Find API returns suggestions
    ↓
User selects "10 Downing Street"
    ↓
Retrieve API returns complete address
    ↓
Form fields populate automatically

Standalone HTML Example

A minimal address autocomplete form for quick testing: Perfect for:

Quick API testing
Learning how address autocomplete works
Simple integrations without checkout flows

To use:

Copy the code
Replace YOUR_API_KEY
Save and test with different addresses

This example searches all countries by default. Add a Countries parameter to restrict results.

Code on GitHub

If you’d like to browse the code snippets in this implementation guide or clone them, visit the repository on GitHub.

Integration Example

Here’s the checkout form with full address autocomplete integrated: To use this code:

Copy the code
Replace YOUR_API_KEY with your actual Loqate API key
Save as an HTML file
Open in a browser to test
Customize styling to match your brand

Key features in this example:

Real-time address suggestions as users type
Debounced API calls to reduce requests
Automatic form population on selection
Support for multiple countries
Clean, production-ready code structure

This example uses debouncing (300ms delay) to reduce API calls while users type. Adjust the delay based on your needs.

Integration Tips

Adding to Your Existing Forms

To add address autocomplete to your current forms:

Add the autocomplete functions from the integration example to your page’s <script> section
- findAddress() for searching
- retrieveAddress() for getting full details
Add the dropdown styles from the integration example to your page’s <style> section
- Positions suggestions below the input
- Provides hover and selection states
Add the suggestion dropdown element next to your address input field
- <div id="suggestions" class="suggestions"></div>
Add the event listeners to trigger search and handle selection
- Input event with debouncing for Find
- Click event on suggestions for Retrieve

Reference the integration example above for all the code you need.

Debouncing API Calls

Debouncing delays API calls until the user stops typing, reducing unnecessary requests:

let debounceTimer;

addressInput.addEventListener('input', function(e) {
    const searchTerm = e.target.value;
    
    clearTimeout(debounceTimer);
    
    if (searchTerm.length < 3) {
        hideSuggestions();
        return;
    }
    
    debounceTimer = setTimeout(async () => {
        const results = await findAddress(searchTerm);
        showSuggestions(results);
    }, 300); // Wait 300ms after last keystroke
});

Recommended delay: 300-500ms balances responsiveness with API efficiency.

Restricting to Specific Countries

Limit results to one or more countries using ISO codes:

async function findAddress(text, container = '') {
    const params = new URLSearchParams({
        Key: apiKey,
        Text: text,
        Container: container,
        Countries: 'GBR,USA' // UK and US only
    });
    
    const response = await fetch(
        `https://api.addressy.com/Capture/Interactive/Find/v1.10/json6.ws?${params}`
    );
    
    return response.json();
}

Common country codes:

GBR - United Kingdom
USA - United States
CAN - Canada
AUS - Australia
FRA - France

Handling Container Results

Some Find results are “containers” (groups of addresses) that need another Find call:

if (result.Type === 'Address') {
    // Final address - retrieve full details
    const address = await retrieveAddress(result.Id);
    populateForm(address);
} else {
    // Container - search again with this as Container parameter
    const moreResults = await findAddress(result.Text, result.Id);
    showSuggestions(moreResults);
}

Populating Form Fields

Map the Retrieve response to your form fields using the Lines format (recommended):

function populateForm(address) {
    document.getElementById('company').value = address.Company || '';
    document.getElementById('addressLine1').value = address.Line1 || '';
    document.getElementById('addressLine2').value = address.Line2 || '';
    document.getElementById('city').value = address.City || '';
    document.getElementById('postalCode').value = address.PostalCode || '';
    document.getElementById('country').value = address.CountryName || '';
}

Available formats:

Lines (recommended) - Line1, Line2, City, PostalCode
Elements - BuildingNumber, Street, District
Label - Single formatted string with \n line breaks

Adding Custom Data

Get additional fields like latitude/longitude using Field parameters:

const params = new URLSearchParams({
    Key: apiKey,
    Id: addressId,
    Field1Format: '{Latitude}',
    Field2Format: '{Longitude}'
});

const response = await fetch(
    `https://api.addressy.com/Capture/Interactive/Retrieve/v1.00/json6.ws?${params}`
);

const data = await response.json();
// Access via data.Items[0].Field1 and Field2

Customize the suggestions dropdown to match your design:

.suggestions {
    position: absolute;
    background: white;
    border: 1px solid #ddd;
    border-top: none;
    max-height: 300px;
    overflow-y: auto;
    z-index: 1000;
    box-shadow: 0 4px 6px rgba(0,0,0,0.1);
}

.suggestion {
    padding: 12px;
    cursor: pointer;
    border-bottom: 1px solid #f0f0f0;
}

.suggestion:hover {
    background: #f5f5f5;
}

.suggestion-text {
    font-weight: 500;
    color: #333;
}

.suggestion-description {
    font-size: 12px;
    color: #666;
}

Troubleshooting

Invalid API Key

Verify you’ve replaced YOUR_API_KEY with your actual key from your Loqate account.

No Suggestions Appearing

Check:

Search term is at least 3 characters (recommended minimum)
You have available credits in your account
API key hasn’t been restricted by domain, IP, or rate limits (check account settings)
Browser console for errors
Network tab shows successful API calls

Suggestions Not Closing

Ensure you handle clicks outside the dropdown:

document.addEventListener('click', function(e) {
    if (!e.target.closest('.address-field') && 
        !e.target.closest('.suggestions')) {
        hideSuggestions();
    }
});

Address Not Populating Form

Check:

You’re calling retrieveAddress() with the correct Id from Find results
Result type is “Address” (not “Container”)
Form field IDs match the JavaScript selectors
Response contains expected fields (check browser console)

Ensure the parent container has position: relative:

.address-field-container {
    position: relative;
}

.suggestions {
    position: absolute;
    top: 100%;
    left: 0;
    right: 0;
}

CORS Errors

The examples must be hosted on a web server, not opened as local file:// URLs. Upload to your website or use a development server like Python’s http.server or Node’s http-server.

Data Privacy

Addresses searched through Loqate’s API
Stored in infrastructure logs for 30 days for operational purposes
Results returned immediately
See Privacy Policy for complete details

Overview

Location Solutions

Data Validation

Resources

Address Capture Implementation Guide

Who Should Use This Guide

What You’ll Build

Quick Start

Choose Your Approach

Add Your Key

Test

Sample Project: Checkout Form Integration

Before: Manual Address Entry

How Address Capture Works

1. Find Step

2. Retrieve Step

How They Work Together

Standalone HTML Example

Code on GitHub

Integration Example

Integration Tips

Adding to Your Existing Forms

Debouncing API Calls

Restricting to Specific Countries

Handling Container Results

Populating Form Fields

Adding Custom Data

Troubleshooting

Invalid API Key

No Suggestions Appearing

Suggestions Not Closing

Address Not Populating Form

CORS Errors

Data Privacy

Support

Overview

Location Solutions

Data Validation

Resources

​Who Should Use This Guide

​What You’ll Build

​Quick Start

​Choose Your Approach

​Add Your Key

​Test

​Sample Project: Checkout Form Integration

​Before: Manual Address Entry

​How Address Capture Works

​1. Find Step

​2. Retrieve Step

​How They Work Together

​Standalone HTML Example

​Code on GitHub

​Integration Example

​Integration Tips

​Adding to Your Existing Forms

​Debouncing API Calls

​Restricting to Specific Countries

​Handling Container Results

​Populating Form Fields

​Adding Custom Data

​Styling the Dropdown

​Troubleshooting

​Invalid API Key

​No Suggestions Appearing

​Suggestions Not Closing

​Address Not Populating Form

​Dropdown Positioning Issues

​CORS Errors

​Data Privacy

​Support

​Related

Who Should Use This Guide

What You’ll Build

Quick Start

Choose Your Approach

Add Your Key

Test

Sample Project: Checkout Form Integration

Before: Manual Address Entry

How Address Capture Works

1. Find Step

2. Retrieve Step

How They Work Together

Standalone HTML Example

Code on GitHub

Integration Example

Integration Tips

Adding to Your Existing Forms

Debouncing API Calls

Restricting to Specific Countries

Handling Container Results

Populating Form Fields

Adding Custom Data

Styling the Dropdown

Troubleshooting

Invalid API Key

No Suggestions Appearing

Suggestions Not Closing

Address Not Populating Form

Dropdown Positioning Issues

CORS Errors

Data Privacy

Support

Related