Tools (28)

Extracted live via the executor SDK.

• addressSearch.addressAutocomplete

  The address autocomplete API returns a list of address suggestions that match the query ordered by relevance.

  This API can be used to power realtime address finders, also known as address autofill or address autocomplete.

  Consider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments.

  Implementing Address Autocomplete

  Rapid address autocompletion using our Address Autocomplete API is a 2 step process.

  1. Retrieve partial address suggestions via /autocomplete/addresses
  2. Retrieve the entire address with the ID provided in the suggestion

  Step 2 will decrement your lookup balance.

  Please note, this API is not intended to be a free standalone resource.

  Filters

  You can strictly narrow your result by adding filters to your querystring. For instance, you can restrict to postcode SW1A 2AA by appending postcode=sw1a2aa.

  If a filter term is invalid, e.g. postcode=SW1A2AAA, then an empty result set is returned and no lookup is incurred.

  You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: postcode_outward=e1,e2,e3. Multiple terms are OR'ed, i.e. the matching result sets are combined.

  All filters can accept multiple terms unless stated otherwise below.

  Filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: su_organisation_indicator=Y&postcode_area=n. Multiple filters are AND'ed, i.e. each additional filter narrows the result set.

  A maximum of 10 terms are allowed across all filters.

  Biases

  You can boost certain addresses results that match specific address criteria. All bias searches are prefixed with bias_.

  Biasing (unlike filtering) also allow unmatched addresses to appear with lower precedence.

  For instance, can boost addresses with postcode areas SW and SE by appending bias_postcode_area=SW,SE.

  No bias effect applies to bias terms that are invalid. e.g. bias_postcode=SW1A2AAA

  You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: bias_postcode_outward=e1,e2,e3.

  All biases can accept multiple terms unless stated otherwise below.

  A combined maximum of 5 terms are allowed across all biases.

  Suggestion Format

  The suggestion format is prone to change over time. Attempts to parse the suggestion may result in your integration breaking. Instead use the suggestion as-is.

  Rate Limiting

  You can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit.

  Header	Description
  X-RateLimit-Limit	The maximum number of requests that can be made in 5 minutes
  X-RateLimit-Remaining	The remaining requests within the current rate limit window
  X-RateLimit-Reset	The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds

  Pricing

  This API currently does not affect your balance. However, resolving a suggestion into a full address requires a paid request.

  Please note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve an address may be disrupted via tightened rate limits. Continued misuse will result in account suspension.

• addressSearch.resolve

  Resolves an address autocompletion by its address ID.

  Resolved addresses (including global addresses) are returned in a UK format (up to 3 address lines) using UK nomenclature (like postcode and county).

• addressSearch.resolveUsa

  Resolves an address autocompletion by its address ID.

  Resolved addresses (including global addresses) are returned in a US format (up to 2 address lines) using US nomenclature (like zipcode, state and city).

• configs.createConfig

  Create a config

• configs.deleteConfig

  Permanently deletes a configuration object.

• configs.listConfigs

  Lists configurations associated with a key

• configs.retrieveConfig

  Retrieve config object by name

• configs.updateConfig

  Updates configuration object

• emails.emailValidation

  Query for and validate email addresses.

• keys.keyAvailability

  Returns public information on key. Currently only returns whether the key is currently useable via the available property. Use this to discover if the key is useable before making further requests.

  You may pass both API Keys (beginning ak_) and Sub-licensed Keys (beginning sl_).

  Testing

  To test your implementation of our API, you may use the following test keys.

  • iddqd Availability will return as true
  • idkfa Availability will return as false
• keys.keyDetails

  Returns private data on the key including remaining lookups, available datasets and usage limits.

• keys.keyLogs

  Reports lookup information on a key for paid lookups.

  This method requires a user_token, which can be found on your accounts page.

  A maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval.

  Download Usage History (CSV)

  GET /keys/:key/lookups

  Returns a CSV download of lookups performed and associated information.

  Note that the Content-Type returned will be CSV (text/csv). For a non 200 response, the Content-Type will revert to JSON with the error code and message embedded.

  Data Redaction

  Personally Identifiable Data (PII) caught in this your usage log (including IP, search term and URL data) will be redacted on a weekly basis.

  By default, PII will be redacted if it is older than 21 days. This timeframe can be configured from your dashboard.

  You may prevent PII collection altogether by setting the interval to 0 days.

• keys.keyUsage

  Reports the number of lookups consumed on a key for a range of days.

  A maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval.

• licensees.createLicensee

  Create a licensee for the specified API Key.

• licensees.deleteLicensee

  Cancels a licensee key. This renders a licensee unusable. This action can be reversed if you get in contact with us.

• licensees.listLicensees

  Returns a list of licensees for a key.

• licensees.retrieveLicensee

  Returns licensee information as identified by the licensee key.

• licensees.updateLicensee

  Update Licensee

• phoneNumbers.phoneNumberValidation

  Query for and validate phone numbers.

• placeSearch.findPlace

  Query for geographical places across countries. Each query will return a list of place suggestions, which consists of a place name, descriptive name and id.

  This API returns geographical information such as countries, capitals, administrative areas and more. It is ideal for correctly identifying a place along with any other details like geolocation.

  Implementing Place Autocomplete

  Extracting the full information of a place is a 2 step process:

  1. Retrieve place suggestions via /places
  2. Retrieve the entire place with the ID provided in the suggestion

  Suggestion Format

  Each place suggestion contains a descriptive name which you can provide to users to uniquely idenfity a place.

  Rate Limiting

  You can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit.

  Header	Description
  X-RateLimit-Limit	The maximum number of requests that can be made in 5 minutes
  X-RateLimit-Remaining	The remaining requests within the current rate limit window
  X-RateLimit-Reset	The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds

  Pricing

  This API currently does not affect your balance. However, resolving a suggestion into a full place requires a paid request.

  Please note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve an place may be disrupted via tightened rate limits.

• placeSearch.resolvePlace

  Resolves a place autocompletion by its place ID.

• uk.addressCleanse

  The address cleanse API attempts to return the closest matching address for any given address inputs. We also return a number of Match Level indicators that describe the degree to which the suggested address matches the input address. The more impaired the input address, the harder it is to cleanse.

  Confidence Score

  The confidence score is a number ranging between 0 and 1. Where 1 implies a full match and 0 implies no major elements completely match. Each incorrect, missing or misspelled element will subtract from the overall confidence score.

  Deciding on an Acceptable Confidence Score Threshold

  Different address cleanse projects can have radically different inputs. However, within each project, the inputs tend to repeat the same errors. For instance, some input datasets may be exclusively inputted manually and be prone to typos. Others may have a persistently missing datapoint such as organistation name or postcode. For this reason, it is important to understand that there is no absolute Confidence Score threshold. Instead, the acceptable confidence score must be determined on a project by project basis based on systematic errors present in the data and business goals.

  When determining an acceptable Confidence Score threshold you should load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top-to-bottom you will be able to observe matches from best to worst. As you start to hit the lower quality searches, you will be able to roughly determine:

  • Which confidence scores indicate ambigious matches (i.e. up to building level only)
  • Which confidence scores indicate a poor or no match (i.e. the nearest matching address is too far from the input address)

  Depending on your business goals, you can also use the Match Levels to determine an acceptable match. For instance, do you need to match up to the throroughfare or building name only? Are accurate organisation names an important feature?

• uk.addresses

  Extract a list of complete addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and 0 respectively).

  If a valid postcode is passed as the query string, the entire address list for that postcode is passed as a result. Note, in these cases, limit and page parameters are ignored.

  This API is designed as a multi-purpose tool for generating address lists, cleansing and wholesale data extraction according to specific parameters.

  For address autocomplete, see our address finder API - which is designed for speed and address completion.

  Reverse Geocoding

  Return a list of addresses around a point using the lon= and lat= querystring arguments. Addresses will be sorted in order of distance to the point. The search radius is 100m.

  Filters

  You can strictly narrow your result by adding filters to your query string which correspond with an address attribute.

  For instance, you can restrict to postcode SW1A 2AA by appending postcode=sw1a2aa.

  If a filter term is invalid, e.g. postcode=SW1A2AAA, then an empty result set is returned and no lookup is incurred.

  You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: postcode_outward=e1,e2,e3. Multiple terms are OR'ed, i.e. the matching result sets are combined.

  All filters can accept multiple terms unless stated otherwise below.

  Multiple filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: su_organisation_indicator=Y&postcode_area=n. Multiple filters are AND'ed, i.e. each additional filter narrows the result set.

  A combined maximum of 5 terms are allowed across all filters.

  Biases

  You can boost certain addresses results that correspond with a certain address attribute. All bias searches are prefixed with bias_.

  Biased searches, unlike filtered searches, also allow unmatched addresses to appear . These will rank lower.

  For instance, you can boost addresses with postcode areas SW and SE by appending bias_postcode_area=SW,SE.

  If a bias term is invalid, e.g. bias_postcode=SW1A2AAA no bias effect is applied.

  You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: bias_postcode_outward=e1,e2,e3.

  All biases can accept multiple terms unless stated otherwise below.

  A combined maximum of 5 terms are allowed across all biases.

  Search by Postcode and Building Name or Number

  Search by postcode and building attribute with the postcode filter and query argument. E.g. For "SW1A 2AA Prime Minister" /v1/addresses?postcode=sw1a2aa&q=prime minister.

  The advantage of using filters is a postcode mismatch does not result in a lookup as no results are returned.

  Search By UPRN

  Search by UPRN using the uprn filter and excluding the query argument. E.g. /v1/addresses?uprn=100.

  Testing

  • ID1 1QD Returns a successful query response 2000
  • ID1 KFA Returns an empty query response 2000
  • ID1 CLIP Returns "no lookups remaining" error 4020
  • ID1 CHOP Returns "daily (or individual) lookup limit breached" error 4021

  Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.

• uk.postcodes

  Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive.

  The Postcode Lookup API provides a JSON interface to search UK addresses from a postcode. It can be used to power Postcode Lookup driven address searches, like Postcode Lookup.

  Postcode Not Found

  Lookup balance is unaffected by invalid postcodes. The API returns a 404 response with response body:

  json

  {  "code": 4040,  "message": "Postcode not found",  "suggestions": ["SW1A 0AA"]}

  Suggestions

  If a postcode cannot be found, the API will provide up to 5 closest matching postcodes. Common errors will be corrected first (e.g. mixing up O and 0 or I and 1).

  If the suggestion list is small (fewer than 3), there is a high probability the correct postcode is there. You may notify the user or immediately trigger new searches.

  The suggestion list will be empty if the postcode has deviated too far from a valid postcode format.

  Multiple Residence

  A small number of postcodes will return more than 100 premises. These may require pagination. Use page to paginate the result set.

• uk.udprn

  Returns an address as identified by its Unique Delivery Point Reference Number (UDPRN).

  You may find it useful to store UDPRN information as it can be used to retrieve the most recent information for an address. It can also be used to test for a deleted address.

  UDPRNs are an eight digit unique numeric code (e.g. 25962203) for any premise on the Postcode Address File. It's essentially a unique identifier for every address in the UK that Royal Mail has in its database.

  Testing

  To test your implementation of our API we have a range of test UDPRNs that yield both successful and unsuccessful responses to your request.

  They are the following:

  • 0 Returns a successful UDPRN lookup response 2000
  • -1 Returns "UDPRN not found", error 4044
  • -2 Returns "no lookups remaining", error 4020
  • -3 Returns "daily (or individual) lookup limit breached", error 4021

  Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.

• uk.umprn

  Returns a multiple occupancy address identifited via its UMPRN (Multiple Residence Unique ID).

  UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.

  Testing

  To test your implementation of our API we have a range of test UMPRNs that yield both successful and unsuccessful responses to your request. They are the following

  • 0 Returns a successful UMPRN lookup response 2000
  • -1 Returns "UMPRN not found", error 4044
  • -2 Returns "no lookups remaining", error 4020
  • -3 Returns "daily (or individual) lookup limit breached", error 4021

  Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.

  Pricing

  Per lookup charges apply. Empty responses are not charged.

• openapi.previewSpec

  Preview an OpenAPI document before adding it as a source

• openapi.addSource

  Add an OpenAPI source and register its operations as tools