This quickstart guide will show you how to start making your first simple Address Capture API requests. Here are the steps to follow to get up and running with Address Capture:
  • Create an account, if you don’t already have one
  • Create an API key for use with Address Capture
  • Make one or more requests to the Capture Find endpoint with your search text
  • Using the output of the Capture Find request, make a request to the Capture Retrieve endpoint
  • Interpret the response from your Capture Retrieve request

​
Creating an account and API key

Before you can start making any requests, you’ll need to have a valid Loqate account and an API key to use with Address Capture. If you don’t have these set up already, you can:
  • Create an account at account.loqate.com
  • Create an API key by selecting the Add a service option within your account. See our Creating API Keys page for full details – we recommend creating a generic API key for use with Address Capture

​
Making a simple Address Capture request

With a valid account and API key, you can now start making Address Capture requests. Address Capture consists of two main API requests:
  • A Find request is used to narrow down a possible list of addresses
  • A Retrieve request is used to retrieve a fully formatted address
The simplest address search is made up of a Find request followed by a Retrieve, taking the address id from the Find response and using it as the search parameter in the Retrieve request. That situation assumes that the initial Find request returns the required address in the results (either as a single address, or within a list of addresses). In some cases, however, a Find request will instead return one or more ‘containers’, which are groupings of addresses. To see the list of addresses within a container, you can make another Find request using the id of the container.
In practice, as Address Capture is a type-ahead service a Find request will often be made with only a small portion of an address. See the Type-ahead requests section below for more information about how this works.
In the Example requests and responses section below we will provide examples for both situations – first a single-address request and then a container request.

​
Address Capture endpoints

The endpoints to use are:
We don’t support API connections using HTTP – make sure you are using HTTPS for all requests.

​
Considerations

Before you make your first Address Capture requests, here are a couple of considerations to be aware of:
  • All ids returned in Find or Retrieve requests are only temporary, as they change over time as the data changes
  • A Retrieve may bring back multiple records for an address, for example when that address is available in multiple languages (you’ll see this in the examples below)

​
Example requests and responses

Below we have provided some simple examples of Capture Find and Retrieve requests. You can copy and paste these example requests into a tool such as Postman – just remember to replace the sample API key with your own valid API key.

​
Single-address request

This example request is based on searching for ‘Loqate’ to find the address of the Loqate HQ in Chester, UK. This search will return a single address. 
GET https://api.addressy.com/Capture/Interactive/Find/v1.10/json3.ws?&Key=AA11-AA11-AA11-AA11&Text=Loqate
This Find request generates the following response: 
{
    "Items": [
        {
            "Id": "GB|RM|A|4624695|A1|ENG",
            "Type": "Address",
            "Text": "Loqate Ltd The Foundation Herons Way",
            "Highlight": "0-6",
            "Description": "Chester Business Park Chester CH4 9GB"
        }
    ]
}
You can now take the Id from the Find response (i.e. “GB|RM|A|4624695|A1|ENG”) and use that in a Retrieve request: 
GET https:// api.addressy.com/Capture/Interactive/Retrieve/v1/json3.ws?Key=AA11-AA11-AA11-AA11&id=GB|RM|A|4624695|A1|ENG
This Retrieve request generates the following response:
This address is available in both English (ENG) and Welsh (CYM), so the Retrieve includes both versions of the address.
{
    "Items": [
        {
            "Id": "GB|RM|A|4624695|A1|ENG",
            "DomesticId": "4624695",
            "Language": "ENG",
            "LanguageAlternatives": "ENG,CYM",
            "Department": "",
            "Company": "Loqate Ltd",
            "SubBuilding": "",
            "BuildingNumber": "",
            "BuildingName": "The Foundation",
            "SecondaryStreet": "",
            "Street": "Herons Way",
            "Block": "",
            "Neighbourhood": "",
            "District": "Chester Business Park",
            "City": "Chester",
            "Line1": "The Foundation",
            "Line2": "Herons Way",
            "Line3": "Chester Business Park",
            "Line4": "",
            "Line5": "",
            "AdminAreaName": "Cheshire West and Chester",
            "AdminAreaCode": "",
            "Province": "Cheshire",
            "ProvinceName": "Cheshire",
            "ProvinceCode": "",
            "PostalCode": "CH4 9GB",
            "CountryName": "United Kingdom",
            "CountryIso2": "GB",
            "CountryIso3": "GBR",
            "CountryIsoNumber": 826,
            "SortingNumber1": "30213",
            "SortingNumber2": "",
            "Barcode": "(CH49GB1AR)",
            "POBoxNumber": "",
            "Label": "Loqate Ltd\nThe Foundation\nHerons Way\nChester Business Park\nCHESTER\nCH4 9GB\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": ""
        },
        {
            "Id": "GB|RM|A|4624695|A1|ENG",
            "DomesticId": "4624695",
            "Language": "CYM",
            "LanguageAlternatives": "ENG,CYM",
            "Department": "",
            "Company": "Loqate Ltd",
            "SubBuilding": "",
            "BuildingNumber": "",
            "BuildingName": "The Foundation",
            "SecondaryStreet": "",
            "Street": "Herons Way",
            "Block": "",
            "Neighbourhood": "",
            "District": "Chester Business Park",
            "City": "Caer",
            "Line1": "The Foundation",
            "Line2": "Herons Way",
            "Line3": "Chester Business Park",
            "Line4": "",
            "Line5": "",
            "AdminAreaName": "Cheshire West and Chester",
            "AdminAreaCode": "",
            "Province": "",
            "ProvinceName": "",
            "ProvinceCode": "",
            "PostalCode": "CH4 9GB",
            "CountryName": "United Kingdom",
            "CountryIso2": "GB",
            "CountryIso3": "GBR",
            "CountryIsoNumber": 826,
            "SortingNumber1": "30213",
            "SortingNumber2": "",
            "Barcode": "(CH49GB1AR)",
            "POBoxNumber": "",
            "Label": "Loqate Ltd\nThe Foundation\nHerons Way\nChester Business Park\nCAER\nCH4 9GB\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": ""
        }
    ]
}
See the Retrieve API docs for information about specific response fields.

​
Container request example

This example request is based on searching for the address of the Loqate HQ in Chester, UK, using part of the address.
You don’t always have to search for complete words, so in this example we’re using “ch” to represent the first two characters of the word “Chester”.
This search will return a container, so will require a second Find request before you can make a Retrieve request. 
GET https://api.addressy.com/Capture/Interactive/Find/v1.10/json3.ws?&Key=AA11-AA11-AA11-AA11&Text=Herons%20Way%20ch
This Find request generates the following response: 
{
    "Items": [
        {
            "Id": "GB|RM|A|24675835|ENG",
            "Type": "Address",
            "Text": "Herons Way Chapel Row",
            "Highlight": "0-6,7-10,11-13",
            "Description": "Ightham Sevenoaks TN15 9AG"
        },
        {
            "Id": "GB|RM|A|18606507|ENG",
            "Type": "Address",
            "Text": "Herons Way Church End",
            "Highlight": "0-6,7-10,11-13",
            "Description": "Fleet Holbeach Spalding PE12 8NQ"
        },
        {
            "Id": "GB|RM|A|4606729|ENG",
            "Type": "Address",
            "Text": "Heronsway Chapel Close",
            "Highlight": "0-9,10-12",
            "Description": "Rowton Chester CH3 7QS"
        },
        {
            "Id": "gb-rm|Fofx7pgB1H6m_iwEut93",
            "Type": "Container",
            "Text": "Herons Way",
            "Highlight": "0-6,7-10,11-13;6-8",
            "Description": "Chester Business Park Chester CH4 - 27 Addresses"
        }
    ]
}
As you can see, this response includes several individual addresses and a single container. The address of the Loqate HQ is not included in the individual addresses, so the next step is to make a second Find request using the container id of “gb-rm|Fofx7pgB1H6m_iwEut93”. For this second Find request, you can remove the Text parameter and replace it with Container. 
GET https://api.addressy.com/Capture/Interactive/Find/v1.10/json3.ws?&Key=AA11-AA11-AA11-AA11&Container=gb-rm|Fofx7pgB1H6m_iwEut93
This Find request generates the following response: 
{
    "Items": [
        {
            "Id": "GB|RM|A|4624694|ENG",
            "Type": "Address",
            "Text": "Customer Service Department Marks & Spencer plc Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9GA"
        },
        {
            "Id": "GB|RM|A|54889327|ENG",
            "Type": "Address",
            "Text": "Bank of America Merrill Lynch Amadeo Financial Centre Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9FE"
        },
        {
            "Id": "GB|RM|A|57643066|ENG",
            "Type": "Address",
            "Text": "A A C Waterproofing Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|56948967|A1|ENG",
            "Type": "Address",
            "Text": "Alderstone Solicitors Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|57358146|ENG",
            "Type": "Address",
            "Text": "Arpadis UK Ltd Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|57975786|ENG",
            "Type": "Address",
            "Text": "Atomos Financial Planning Ltd Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|56948967|ENG",
            "Type": "Address",
            "Text": "Birchall Blackburn Law Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|55678255|ENG",
            "Type": "Address",
            "Text": "Candid Financial Planning Ltd Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|58029467|ENG",
            "Type": "Address",
            "Text": "Chase De Vere Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|52362570|ENG",
            "Type": "Address",
            "Text": "Freeman Jones Solicitors Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|52567347|ENG",
            "Type": "Address",
            "Text": "G S Y S Ltd Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|56458380|ENG",
            "Type": "Address",
            "Text": "Mphasis Technologies Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|56447675|ENG",
            "Type": "Address",
            "Text": "Mphasis UK Ltd Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|56957578|ENG",
            "Type": "Address",
            "Text": "National Asbestos Helpline Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|4625264|ENG",
            "Type": "Address",
            "Text": "Regus Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|58076902|ENG",
            "Type": "Address",
            "Text": "Sail Legal Ltd Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|57572520|ENG",
            "Type": "Address",
            "Text": "Smart Auction UK Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|52760768|ENG",
            "Type": "Address",
            "Text": "White Oak Financial Planning Ltd Regus House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QR"
        },
        {
            "Id": "GB|RM|A|56818795|ENG",
            "Type": "Address",
            "Text": "Stansfield House Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QQ"
        },
        {
            "Id": "GB|RM|A|4624695|ENG",
            "Type": "Address",
            "Text": "GB Group plc The Foundation Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9GB"
        },
        {
            "Id": "GB|RM|A|4624695|A6|ENG",
            "Type": "Address",
            "Text": "Eware Interactive GB Group plc The Foundation Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9GB"
        },
        {
            "Id": "GB|RM|A|4624695|A2|ENG",
            "Type": "Address",
            "Text": "I D Scan Biometrics Ltd The Foundation Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9GB"
        },
        {
            "Id": "GB|RM|A|4624695|A1|ENG",
            "Type": "Address",
            "Text": "Loqate Ltd The Foundation Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9GB"
        },
        {
            "Id": "GB|RM|A|4624695|A3|ENG",
            "Type": "Address",
            "Text": "McLintocks Ltd The Foundation Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9GB"
        },
        {
            "Id": "GB|RM|A|4624695|A4|ENG",
            "Type": "Address",
            "Text": "Phonelink plc The Foundation Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9GB"
        },
        {
            "Id": "GB|RM|A|57310519|ENG",
            "Type": "Address",
            "Text": "Spa Medica The Foundation Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9GP"
        },
        {
            "Id": "GB|RM|A|4625256|ENG",
            "Type": "Address",
            "Text": "Chester Business Park Management Co Ltd The Lodge Herons Way",
            "Highlight": "",
            "Description": "Chester Business Park Chester CH4 9QL"
        }
    ]
}
If you scroll down nearly to the bottom of this response, you will see the address for the Loqate HQ with an id of “GB|RM|A|4624695|A1|ENG”. You can now take this id and search for it in a Retrieve request. 
GET https:// api.addressy.com/Capture/Interactive/Retrieve/v1/json3.ws?Key=AA11-AA11-AA11-AA11&id= GB|RM|A|4624695|A1|ENG
This Retrieve request generates the following response:
This address is available in both English (ENG) and Welsh (CYM), so the Retrieve includes both versions of the address.
{
    "Items": [
        {
            "Id": "GB|RM|A|4624695|A1|ENG",
            "DomesticId": "4624695",
            "Language": "ENG",
            "LanguageAlternatives": "ENG,CYM",
            "Department": "",
            "Company": "Loqate Ltd",
            "SubBuilding": "",
            "BuildingNumber": "",
            "BuildingName": "The Foundation",
            "SecondaryStreet": "",
            "Street": "Herons Way",
            "Block": "",
            "Neighbourhood": "",
            "District": "Chester Business Park",
            "City": "Chester",
            "Line1": "The Foundation",
            "Line2": "Herons Way",
            "Line3": "Chester Business Park",
            "Line4": "",
            "Line5": "",
            "AdminAreaName": "Cheshire West and Chester",
            "AdminAreaCode": "",
            "Province": "Cheshire",
            "ProvinceName": "Cheshire",
            "ProvinceCode": "",
            "PostalCode": "CH4 9GB",
            "CountryName": "United Kingdom",
            "CountryIso2": "GB",
            "CountryIso3": "GBR",
            "CountryIsoNumber": 826,
            "SortingNumber1": "30213",
            "SortingNumber2": "",
            "Barcode": "(CH49GB1AR)",
            "POBoxNumber": "",
            "Label": "Loqate Ltd\nThe Foundation\nHerons Way\nChester Business Park\nCHESTER\nCH4 9GB\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": ""
        },
        {
            "Id": "GB|RM|A|4624695|A1|ENG",
            "DomesticId": "4624695",
            "Language": "CYM",
            "LanguageAlternatives": "ENG,CYM",
            "Department": "",
            "Company": "Loqate Ltd",
            "SubBuilding": "",
            "BuildingNumber": "",
            "BuildingName": "The Foundation",
            "SecondaryStreet": "",
            "Street": "Herons Way",
            "Block": "",
            "Neighbourhood": "",
            "District": "Chester Business Park",
            "City": "Caer",
            "Line1": "The Foundation",
            "Line2": "Herons Way",
            "Line3": "Chester Business Park",
            "Line4": "",
            "Line5": "",
            "AdminAreaName": "Cheshire West and Chester",
            "AdminAreaCode": "",
            "Province": "",
            "ProvinceName": "",
            "ProvinceCode": "",
            "PostalCode": "CH4 9GB",
            "CountryName": "United Kingdom",
            "CountryIso2": "GB",
            "CountryIso3": "GBR",
            "CountryIsoNumber": 826,
            "SortingNumber1": "30213",
            "SortingNumber2": "",
            "Barcode": "(CH49GB1AR)",
            "POBoxNumber": "",
            "Label": "Loqate Ltd\nThe Foundation\nHerons Way\nChester Business Park\nCAER\nCH4 9GB\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": ""
        }
    ]
}
See the Retrieve API docs for information about specific response fields.

​
Type-ahead requests

Up to now, the examples we’ve provided all assume that you’re searching for a full address in one go. Address Capture is a type-ahead service though, designed to help find a customer’s address in just a few key presses. As such, in practice it will be making multiple Find calls as customers enter additional characters of their address. For example, as a customer types “High Street” into a search field, Address Capture will be making Find calls with gradually increasing levels of detail:
  1. &Text=H
  2. &Text=Hi
  3. &Text=Hig
  4. &Text=High
  5. &Text=High S
  6. &Text=High St
  7. and so on
As the Find requests become more detailed, the responses will return results that come closer to the customer’s search term. What this means is, in practice it’s likely that you will see multiple Find requests made before the intended address is returned, at which point selecting that address that will trigger a Retrieve request.
Now try out Address Capture

​
Further reading

Now that you’ve made your first Address Capture API requests, here are some additional resources that you might find useful as you continue setting up your integration: