A typical address search is made up of a series of Find requests, fired on user input, followed by a Retrieve based on the user selection.
Please note that the Saas Platform is currently only available in North America.

​
Base URL

All API requests use the same base URL of: https://api-us.platform.loqate.com
Note: we don’t support API connections using HTTP - all calls should use HTTPS.

​
Authentication

API requests are authenticated using your API key as the value of a “key” parameter on the request. An authenticated sample request would therefore look like this: 
https://api-us.platform.loqate.com/address-capture/find?text=GBG PLC&key=[insert your key here]

​
Find (GET)

​
Request parameters

ParameterRequiredTypeDescription
KeyRequiredstringThe key used to authenticate with the service.
TextRequiredstringThe search text to find. Ideally a postcode or the start of the address.
CountriesOptionalarrayA container for the search. This should only be another Id previously returned from this service when the Type of the result was not ‘Address’.
LimitOptionalstringThe maximum number of results to return.
ContainerOptionalstringA container for the search. This should only be another Id previously returned from this service when the Type of the result was not ‘Address’.
IsMiddlewareOptionalbooleanWhether the API is being called from a middleware implementation (and therefore the calling IP address should not be used for biasing).
OriginOptionalstringA starting location for the search. This can be the name or ISO 2 or 3 character code of a country, WGS84 coordinates (comma separated) or IP address to search from.
LanguageOptionalstringThe preferred language for results. This should be a 2 or 4 character language code (e.g. en, fr, en-gb, en-us etc.).
BiasOptionalbooleanWhen Bias is set to True and when the Origin value provided is WGS84 coordinates or an IP address, this allows the user to find addresses that are near to them with less entry. When Bias is set to False, information provided in the Origin field will be used to prefer address matches from the country that Origin field identifies.
FiltersOptionalstringYou can include or exclude certain type of addresses or locations from the address matches presented back to end user. All Filters are currently operating on the basis of an exact match. Multiple Filters can be provided in the same request.

​
Return fields

The service returns an object with a key of items that contains an array of possible matches.
FieldTypeDescription
idstringThis can be an address Id or a container Id for further results.
textstringThe name of the result.
typestringIf the Type is ‘Address’ then the Id can be passed to the Retrieve service. Any other Id should be passed as the Container to a further Find request to get more results.
descriptionstringDescriptive information about the result.
highlightstringA list of number ranges identifying the matched characters in the Text and Description.
languagestringThe language of the result

​
Example request

Add your API key into the code below for a sample FIND request: 
https://api-us.platform.loqate.com/address-capture/find?text=GBG PLC&key=[insert your key here]

​
Example response

{
  "items": [
    {
      "id": "GB|RM|A|27964893|A5|ENG",
      "text": "Suzuki GB plc Winnall Down Farm Alresford Road Winchester SO21 1FP",
      "type": "Address",
      "description": "",
      "highlight": "7-9,10-13",
      "language": "ENG"
    },
    {
      "id": "GB|RM|A|50958735|A3|ENG",
      "text": "Toyota GB plc Aspen Building Vantage Point Business Village Mitcheldean GL17 0AF",
      "type": "Address",
      "description": "",
      "highlight": "7-9,10-13",
      "language": "ENG"
    },
    {
      "id": "GB|RM|A|12243871|ENG",
      "text": "Toyota (GB) plc PO Box 449 Epsom KT18 5WG",
      "type": "Address",
      "description": "",
      "highlight": "12-15",
      "language": "ENG"
    },
    {
      "id": "GB|RM|A|646784|A1|ENG",
      "text": "Suzuki GB plc Lloyd House 471-478 Garretts Green Lane Birmingham B33 0SG",
      "type": "Address",
      "description": "",
      "highlight": "7-9,10-13",
      "language": "ENG"
    },
    {
      "id": "GB|RM|A|28091924|ENG",
      "text": "Suzuki GB plc Steinbeck Crescent Snelshall West Milton Keynes MK4 4AE",
      "type": "Address",
      "description": "",
      "highlight": "7-9,10-13",
      "language": "ENG"
    },
    {
      "id": "GB|RM|A|12243866|ENG",
      "text": "Toyota (GB) plc Yew Tree Bottom Road Epsom KT18 5UX",
      "type": "Address",
      "description": "",
      "highlight": "12-15",
      "language": "ENG"
    },
    {
      "id": "GB|RM|A|12243943|ENG",
      "text": "Toyota (GB) plc PO Box 327 Epsom KT18 5XQ",
      "type": "Address",
      "description": "",
      "highlight": "12-15",
      "language": "ENG"
    },
    {
      "id": "GB|RM|A|27695927|A1|ENG",
      "text": "Suzuki GB plc PO Box 450 Brighton BN1 1SN",
      "type": "Address",
      "description": "",
      "highlight": "7-9,10-13",
      "language": "ENG"
    },
    {
      "id": "GB|RM|A|26871817|A5|ENG",
      "text": "Home Service GB Ltd South Staffordshire Water plc Green Lane Walsall WS2 7PD",
      "type": "Address",
      "description": "",
      "highlight": "13-15,46-49",
      "language": "ENG"
    },
    {
      "id": "GB|RM|A|4624695|A3|ENG",
      "text": "Eware Interactive GB Group plc The Foundation Herons Way Chester Business Park Chester CH4 9GB",
      "type": "Address",
      "description": "",
      "highlight": "18-20,27-30",
      "language": "ENG"
    }
  ]
}

​
Retrieve (GET)

​
Request parameters

ParameterRequiredTypeDescription
KeyRequiredstringThe key used to authenticate with the service.
idRequiredstringAn Id resulting from a Find method to retrieve the details for.

​
Return fields

FieldTypeDescription
idstringThe id of the result.
domesticIdstring
languagestringThe language of this result.
languageAlternativesstring
departmentstringThe ‘department’ part of the address.
companystringThe ‘company’ part of the address.
subBuildingstringThe ‘subBuilding’ part of the address.
buildingNumberstringThe building number of the address.
buildingNamestringThe building name of the address.
secondaryStreetstringThe ‘secondaryStreet’ part of the address.
streetstringThe ‘street’ part of the address.
blockstringThe ‘block’ part of the address.
neighbourhoodstringThe ‘neighbourhood’ part of the address.
districtstringThe ‘district’ part of the address.
citystringThe ‘city’ part of the address.
line1stringA formatted first line of the address. The line 1-5 properties attempt to format an address into usable lines. Depending on the length of the address the later lines may be empty.
line2stringA formatted second line of the address.
line3stringA formatted third line of the address.
line4stringA formatted fourth line of the address.
line5stringA formatted fifth line of the address.
adminAreaNamestringThe ‘adminAreaName’ part of the address.
adminAreaCodestringThe ‘adminAreaCode’ part of the address.
provincestringThe ‘province’ part of the address.
provinceNamestringThe ‘provinceName’ part of the address.
provinceCodestringThe ‘provinceCode’ part of the address.
postalCodestringThe ‘postalCode’ part of the address.
countryNamestringThe ‘countryName’ part of the address.
countryIso2stringThe two character ISO representation of the address country.
countryIso3stringThe three character ISO representation of the address country.
countryIsoNumberstringThe numerical ISO representation of the address country.
sortingNumber1string
sortingNumber2string
barcodestring
poBoxNumberstringThe PO Box Number part of the address.
labelstringA formatted label for the address.
typestring
dataLevelstring
sourcestring

​
Example request

Add your API key into the code below for a sample RETRIEVE request: 
https://api-us.platform.loqate.com/address-capture/retrieve?id=GB|RM|A|4624695|ENG&key=[insert your key here]

​
Example response

{
  "items": [
    {
      "id": "GB|RM|A|4624695|A3",
      "domesticId": "4624695",
      "language": "ENG",
      "languageAlternatives": "",
      "department": null,
      "company": "GBG plc",
      "subBuilding": "",
      "buildingNumber": "",
      "buildingName": "The Foundation",
      "secondaryStreet": "",
      "street": "Herons Way",
      "block": null,
      "neighbourhood": null,
      "district": "Chester Business Park",
      "city": "Chester",
      "line1": "The Foundation",
      "line2": "Herons Way",
      "line3": "Chester Business Park",
      "line4": "",
      "line5": "",
      "adminAreaName": "Cheshire West and Chester",
      "adminAreaCode": null,
      "province": "Cheshire",
      "provinceName": "Cheshire",
      "provinceCode": null,
      "postalCode": "CH4 9GB",
      "countryName": "United Kingdom",
      "countryIso2": "GB",
      "countryIso3": "GBR",
      "countryIsoNumber": "826",
      "sortingNumber1": "30213",
      "sortingNumber2": null,
      "barcode": "(CH49GB1AR)",
      "poBoxNumber": null,
      "label": "Phonelink plcThe FoundationHerons WayChester Business ParkCHESTERCH4 9GBUNITED KINGDOM",
      "type": 1,
      "dataLevel": 0,
      "source": "P"
    },
    {
      "id": "GB|RM|A|4624695|A3",
      "domesticId": "4624695",
      "language": "CYM",
      "languageAlternatives": "",
      "department": null,
      "company": "GBG plc",
      "subBuilding": "",
      "buildingNumber": "",
      "buildingName": "The Foundation",
      "secondaryStreet": "",
      "street": "Herons Way",
      "block": null,
      "neighbourhood": null,
      "district": "Chester Business Park",
      "city": "Caer",
      "line1": "The Foundation",
      "line2": "Herons Way",
      "line3": "Chester Business Park",
      "line4": "",
      "line5": "",
      "adminAreaName": "Cheshire West and Chester",
      "adminAreaCode": null,
      "province": "Cheshire",
      "provinceName": "Cheshire",
      "provinceCode": null,
      "postalCode": "CH4 9GB",
      "countryName": "United Kingdom",
      "countryIso2": "GB",
      "countryIso3": "GBR",
      "countryIsoNumber": "826",
      "sortingNumber1": "30213",
      "sortingNumber2": null,
      "barcode": "(CH49GB1AR)",
      "poBoxNumber": null,
      "label": "Phonelink plcThe FoundationHerons WayChester Business ParkCAERCH4 9GBUNITED KINGDOM",
      "type": 1,
      "dataLevel": 0,
      "source": "W"
    }
  ]
}