Skip to main content
Address Capture provides real-time address search and verification as users type, reducing errors and improving data quality.

​
Coverage

  • Global: Address data for over 250 countries and territories
  • UK Premium: AddressBase Premium data with Geolocation support

​
Available Endpoints

Address Capture provides three API endpoints:

​
Core Endpoints

  • Find - Search for addresses and places as users type
  • Retrieve - Get full address details based on the selected ID

​
Additional Endpoint

  • Geolocation - Find addresses within a radius of latitude/longitude coordinates (UK AddressBase Premium only)

​
Getting Started

  1. Create an API key if you don’t have one
  2. Make a Find request to search for addresses as the user types
  3. Make a Retrieve request to get the full address when they select one
Here’s a simple example request for the Find endpoint: 
curl --request GET \
  --url https://api.addressy.com/Capture/Interactive/Find/v1.20/json6.ws

​
What Address Capture Returns

A typical Address Capture workflow:
  • Find returns a list of matching addresses based on search text
  • Retrieve returns the complete formatted address in multiple formats

​
Find Response

Response should be in the following format: 
{
  "Items": [
    {
      "Id": "GB|RM|B|55605138|ENG",
      "Type": "Address",
      "Text": "G B G Evermore 128 Queen Victoria Street",
      "Highlight": "0-1,2-3,4-5",
      "Description": "London EC4V 4BJ"
    }
  ]
}

​
Retrieve Response

{
  "Items": [
    {
      "Id": "GB|RM|B|55605138|ENG",
      "DomesticId": "55605138",
      "Language": "ENG",
      "LanguageAlternatives": "",
      "Department": "",
      "Company": "G B G",
      "SubBuilding": "",
      "BuildingNumber": "128",
      "BuildingName": "Evermore",
      "SecondaryStreet": "",
      "Street": "Queen Victoria Street",
      "Block": "",
      "Neighbourhood": "",
      "District": "",
      "City": "London",
      "Line1": "G B G Evermore",
      "Line2": "128 Queen Victoria Street",
      "Line3": "",
      "Line4": "",
      "Line5": "",
      "AdminAreaName": "",
      "AdminAreaCode": "",
      "Province": "",
      "ProvinceName": "",
      "ProvinceCode": "",
      "PostalCode": "EC4V 4BJ",
      "CountryName": "United Kingdom",
      "CountryIso2": "GB",
      "CountryIso3": "GBR",
      "CountryIsoNumber": "826",
      "SortingNumber1": "",
      "SortingNumber2": "",
      "Barcode": "",
      "POBoxNumber": "",
      "Label": "G B G Evermore\n128 Queen Victoria Street\nLondon\nEC4V 4BJ\nUnited Kingdom",
      "Type": "Commercial",
      "DataLevel": "Premise",
      "Field1": "",
      "Field2": "",
      "Field3": "",
      "Field4": "",
      "Field5": "",
      "Field6": "",
      "Field7": "",
      "Field8": "",
      "Field9": "",
      "Field10": "",
      "Field11": "",
      "Field12": "",
      "Field13": "",
      "Field14": "",
      "Field15": "",
      "Field16": "",
      "Field17": "",
      "Field18": "",
      "Field19": "",
      "Field20": ""
    }
  ]
}
And you can use this information below to interpret the response fields:

​
Search Results

FieldTypeDescription
IdstringUnique identifier for the address or container (for further results). Can change over time
TypestringType of result: Address, Container, Postcode, Street, BuildingName, or Building. If Type is Address, pass Id to Retrieve. Otherwise, pass Id as Container to another Find request
TextstringFirst half of the address displayed to the user
HighlightstringNumber ranges showing which characters match the search term. Use to highlight matching text in bold. Empty if Container Id included in request
DescriptionstringSecond half of the address, including address count for Containers

​
Address Label Format

FieldTypeDescription
LabelstringComplete formatted address with line breaks (\n). Ideal for display or printing on envelopes
FieldTypeDescription
CompanystringCompany name
Line1stringFirst line of formatted address
Line2stringSecond line of formatted address
Line3stringThird line of formatted address
Line4stringFourth line of formatted address
Line5stringFifth line of formatted address
CitystringTown or city name
ProvincestringEither ProvinceName or ProvinceCode based on country standards
PostalCodestringFull postal code (Postcode, ZIP Code, etc.)

​
Address Elements Format

FieldTypeDescription
DepartmentstringDepartment name for business addresses
SubBuildingstringSub-building identifier (Flat 4, Unit 2, etc.)
BuildingNumberstringHouse or building number
BuildingNamestringBuilding name if applicable
SecondaryStreetstringSecondary thoroughfare name
StreetstringMain thoroughfare name
BlockstringBlock details
NeighbourhoodstringNeighbourhood name
DistrictstringDistrict name

​
Geographic and Administrative

FieldTypeDescription
AdminAreaNamestringAdministrative area name (e.g., county council)
AdminAreaCodestringAdministrative area code
ProvinceNamestringLargest administrative division name (state, county)
ProvinceCodestringAdministrative division code
CountryNamestringFull country name (ISO 3166-1)
CountryIso2stringTwo-character ISO country code
CountryIso3stringThree-character ISO country code
CountryIsoNumberstringISO numeric country code

​
Additional Fields

FieldTypeDescription
IdstringUnique address identifier
DomesticIdstringReference number in source dataset (e.g., UDPRN)
LanguagestringThree-letter language code
TypestringAddress type: Residential, Commercial, or Unknown (available in select countries)
DataLevelstringData precision level: Unknown, Premise, RangedPremise, Street, or City
POBoxNumberstringPO Box number if applicable
BarcodestringBarcode for bulk mailing schemes
Field1 - Field20stringCustom fields when using Field1Format - Field20Format parameters
Note: Use Field1Format through Field20Format request parameters to return custom data (e.g., latitude, longitude) in these fields.
When an error occurs, the API returns an error response with the following structure:
FieldTypeDescription
ErrorstringThe error ID
DescriptionstringA description of the error
CausestringThe cause of the error
ResolutionstringActions to resolve the error

​
Common Error Codes

Status CodeMeaningCommon Causes
400Bad RequestInvalid parameters, malformed request, missing required fields
401UnauthorizedInvalid or missing API key
403ForbiddenAPI key doesn’t have permission for this service, or daily limit exceeded
500Internal Server ErrorServer-side issue, temporary service disruption
Tip: Check the Resolution field for specific steps to fix the error. For more details on error responses, see Find in API documentation.
Note: Address Capture provides three response formats: Label (single string), Lines (recommended for forms), and Elements (individual components). Use one format consistently to avoid duplication or missing data.

​
Integration Methods

Beyond direct API integration, Address Capture can be integrated using:
  • Tag: Automatically-generated code snippets for your website forms - Tag Setup Guide
  • SDK: Pre-built SDK for quick custom integration - Capture SDK
  • Pre-built integrations: Ready-made integrations for Adobe Commerce, Shopify Plus, and more - All Integrations
See the Ways to Integrate page for guidance on choosing the best method.

​
Try Address Capture

Test Address Capture using the Find Playground to make your first request.

​
FAQ

The best method depends on your technical requirements and resources. Use Tags for quick website integration, the SDK for custom web applications, direct APIs for full control, or pre-built integrations for supported platforms. See the Ways to Integrate page for detailed guidance.
Address Capture provides three formats: Label (single formatted string), Lines (recommended for multi-line forms), and Elements (individual address components). Choose one format based on your form structure. The Lines format works best for most forms with separate fields for company, address lines, city, and postcode. Do not mix formats to avoid duplication or missing data. See the Retrieve API documentation for all available fields.
Consider performance, complexity, and security when deciding. Client-side calls provide faster user experience but expose your API key. Server-side calls are more secure but add latency. See the API Security page for detailed guidance on integration options and security best practices.
Yes. Use the field1format={Latitude} and field2format={Longitude} parameters in your Retrieve request to return coordinates in Field1 and Field2. Coordinates are returned where available in the dataset. For Tag integrations, configure these parameters in the mappings wizard. See the Retrieve API documentation for details on custom field formatting.