Address Verification API - Global Cleanse and Geocode

Turn the addresses, email addresses and phone numbers you already hold into ones you can actually ship to, mail to and call. Eight services over one key, 245 countries, one flat row per result.

What this actor does

• Verifies and corrects addresses in 245 countries. Every address comes back standardised into its parts - building, sub-building, street, locality, region, postal code, country - with the local format and script respected rather than forced into a single layout.
• Grades every match rather than passing or failing it. The provider returns a compound verification code whose leading character says how well the address matched, and the actor lifts that out as both a plain number and a readable label. That is the difference between "verified to the exact premise" and "we found the street", and shipping decisions turn on it.
• Keeps every candidate for an ambiguous address. When one input matches several real addresses, each candidate is written as its own row. Collapsing an ambiguous address to its first candidate is how the wrong address gets quietly chosen for you.
• Separates searching from retrieving, and says so. Type-ahead search narrows a partial string and costs nothing; turning the result into a full address is what gets charged. Search results are also often containers - a postcode, a street, a building - which have to be searched into rather than used, and the actor follows them down automatically. You can also run search with retrieval off, which costs nothing and hands you identifiers to retrieve later.
• Verifies email addresses with a risk level, not just a verdict. Valid, catch-all, invalid or timed out, plus a low, medium or high estimate of how likely the address is to bounce, plus a disposable-mailbox flag. Batches of up to a hundred, or one at a time when a per-address timeout matters.
• Says plainly when an email verdict proves nothing. A catch-all result means the domain accepts mail for every possible mailbox, so a positive answer there says nothing about the individual address. It is returned as its own verdict rather than folded into valid.
• Validates phone numbers against the live network. Number type, network operator, network country, national format, and whether the number has been ported or is currently roaming. The provider also distinguishes "could not reach the network" from "bad number", and so does the output.
• Geocodes in both directions. Place names and postal codes into coordinates, coordinates into places, with a bad coordinate pair dropped before the request rather than sent and charged for.
• Checks UK bank accounts. Account number and sort code, in either order, returning the bank and branch and whether the account takes faster payments, direct debits and CHAPS.
• Waits out a protective throttle instead of failing. This provider trips a surge protector on unusually heavy traffic, and it clears on its own. That is retried rather than reported, which is what keeps a long batch alive.
• Tells five kinds of refusal apart. An unknown key, an empty balance, a spent daily limit, a key restricted by URL, IP or service, and a malformed request all arrive as the same shape here. They need five different reactions and the actor gives them five.
• Never charges for a miss. Only rows carrying a resolved result are billed.

Input

Field	What it does
mode	Which of the eight services to call.
addresses	Addresses to verify, as text or JSON objects.
searches	Partial addresses to search for.
addressIds	Identifiers from an earlier search, to retrieve.
emails	Email addresses to verify.
phones	Phone numbers to verify.
locations	Places or postal codes to geocode.
coordinates	Coordinate pairs to reverse geocode.
bankAccounts	UK sort code and account number pairs.
countries	Restrict searches to these countries.
defaultCountry	Country to assume when an input does not say.
geocode	Return coordinates alongside verified addresses.
minVerificationLevel	Keep only addresses matched at least this well.
maxMatchesPerAddress	Candidate matches allowed per ambiguous address.
outputCasing	How verified addresses are cased.
outputScript	Script verified addresses are transliterated into.
retrieveAddresses	Retrieve the full address after a search.
followContainers	Search inside partial matches.
searchLimit	Results returned per search query.
language	Language code for the search mode.
findTypes	Keep only these kinds of search result.
emailResponseCodes	Keep only these email verdicts.
emailRiskLevels	Keep only these email risk levels.
excludeDisposableEmail	Drop throwaway mailboxes.
emailTimeoutMs	Milliseconds allowed per email address.
phoneNumberTypes	Keep only mobiles, landlines or VoIP.
requireValidPhone	Keep only confirmed numbers.
forceSingle	Verify email addresses one at a time.
batchSize	Records per request, up to one hundred.
requestsPerMinute	Pace the run under your plan's rate limit.
skipNotFound	Leave inputs with no result out of the dataset.
maxResults	Hard cap on rows, and therefore on spend and run time.
apiKey	Your own API key. Stored as a secret.

Example output

{
  "found": true,
  "mode": "address-verify",
  "query": "10 Downing Street, London, SW1A 2AA, GB",
  "inputId": "0",
  "addressVerificationCode": "V44-I44-P6-100",
  "verificationLevel": 5,
  "verificationMatch": "Verified",
  "addressQualityIndex": "A",
  "addressComplete": "10 Downing Street\nLondon\nSW1A 2AA\nUnited Kingdom",
  "addressLine1": "10 Downing Street",
  "buildingNumber": "10",
  "street": "Downing Street",
  "locality": "London",
  "administrativeArea": null,
  "postalCode": "SW1A 2AA",
  "country": "United Kingdom",
  "countryIso2": "GB",
  "countryIso3": "GBR",
  "latitude": 51.5034,
  "longitude": -0.1276,
  "geoAccuracy": "P4",
  "deliveryPointSuffix": "1A",
  "matchedFields": "BSPCZ",
  "error": null,
  "raw": { }
}

Frequently asked questions

What is the difference between verifying an address and searching for one?

Verifying takes an address you already hold, corrects it, standardises it and tells you how well it matched. Searching is for an address you do not have yet: you type a fragment, the service narrows it, and you end up with an identifier that has to be retrieved to become a real address. They also cost differently. Searching is free and retrieving is charged, which is why a run that only searches spends nothing and collects no addresses, and why this actor retrieves by default.

What does the verification code actually mean?

It is a compound string, and its first character is the part that matters: verified, partially verified, ambiguous, unverified, reverted or conflict, followed by digits grading the individual components. The actor lifts that leading character out as both a readable label and a number from one to five, so you can filter on it without parsing a string. Set the minimum verification level to five when only exact premise matches will do, and to three or four when a street-level match is good enough.

Why would one address come back as several rows?

Because it genuinely matches several real addresses. A street with no building number, or a building with unlisted sub-units, has more than one correct resolution, and the provider returns all of them. Each candidate is written as its own row rather than collapsed to the first one, since silently choosing among them is how a parcel ends up at the wrong flat. Use the maximum matches setting to cap how many candidates one input may produce.

What is a catch-all email result and why is it separate from valid?

A catch-all domain is configured to accept mail addressed to every possible mailbox, whether or not it exists. Checking any address there comes back positive and proves nothing about the individual mailbox. This provider returns that as its own verdict rather than folding it into valid, and this actor keeps that distinction, because treating it as valid is how a list that looks clean still bounces.

What does the phone check tell me beyond valid or invalid?

The number type, so a messaging campaign can keep the mobiles and a call list can keep the landlines; the network operator and the country that network is in; the national format for display; and whether the number has been ported to another network or is currently roaming abroad. It also has a third verdict beyond yes and no, meaning the network could not be reached, which is not the same as a bad number and should not be filtered out as one.

Can I search without spending anything?

Yes. Turn retrieval off and the search mode writes the identifiers and descriptions it found without turning any of them into full addresses. Searching is free on this provider, so that run costs nothing, and the identifiers can be fed into the retrieve mode later. Note that the provider does watch the ratio between the two and will eventually object to a very large number of searches with no retrievals behind them.

Why does batching addresses by country matter?

Because the provider's own guidance is to keep one batch to one country where you can. Its verification engine loads reference data per country, and a batch mixing twenty countries makes it work far harder than a batch of a hundred addresses all in one. The batch ceiling is a hundred records either way; grouping by country before you run is free and noticeably faster.

My key works elsewhere but is refused here. Why?

Keys on this provider carry their own security settings: a key can be restricted to particular URLs, particular IP addresses, particular services, or a daily lookup limit, and any of those will refuse a request that is otherwise perfectly valid. The actor reports each of these separately rather than as one generic rejection, so the message tells you which restriction was hit. An unknown key, an empty balance, a spent daily limit and a service restriction are four different problems with four different fixes.

Do I need my own API key?

Yes. This actor does not include data access. You use your own API key from Loqate, which is the provider whose address verification API this actor calls, created in your account there. Your own plan, credit balance and terms apply. Paste the key into the apiKey field, where it is stored as an Apify secret. Keys look like AA11-AA11-AA11-AA11.

What happens when an input returns nothing?

An invalid email address or an unverifiable address is a verdict, not a miss: the provider telling you the input is bad is the question you asked, so that row is written and billed like any other. A miss is an input the provider returned no result for at all, and those are written with found: false and never billed. Set skipNotFound to true to leave them out of the dataset entirely.

How much does a run cost?

Pricing is pay per result: you are charged for each result written to the dataset, and never for misses, for rows dropped by the filters, or for duplicates. Note that an ambiguous address returning three candidates is three rows, and that a search drilling into a postcode can return every address inside it, so the maximum results cap is doing real work in those modes. Apify platform usage is included in the per-result price. Your own API provider's credit balance is separate and billed by them.

Keyword map

address verification API, address validation API, global address verification, international address cleansing, address standardisation, address autocomplete, address capture, type-ahead address search, postal address correction, delivery point validation, address geocoding, reverse geocoding API, latitude longitude lookup, postcode lookup, email verification API, email validation, catch-all detection, disposable email detection, email risk score, phone validation API, phone number lookup, mobile or landline detection, number porting check, roaming check, UK bank account validation, sort code check, modulus check, checkout address validation, data quality API, CRM address hygiene