Geocoding API - Address Verification and Lat Long Lookup

Turn a list of addresses into precise latitude and longitude, or check and standardize them against global postal reference data, without stitching together two providers.

What it does

• Geocodes to rooftop accuracy. The premium tier places a point on the building itself rather than at the middle of the street or the centre of a postal code.
• Tells you how precise each point actually is. Every geocode row carries a precision code and level, so a rooftop match and a postal centroid fallback are never mistaken for each other.
• Verifies and standardizes addresses. The verify mode returns the address the way the postal authority writes it, with the postal code split into its base and add-on, plus a pass or fail status and a reason code when it fails.
• Returns parsed components, not just a string. House number, street name, unit type and value, place name and four levels of administrative area come back as separate fields.
• Shows which parts of the address actually matched. Per field match flags report whether the house number, street name, postal code and place name each matched the reference data, which is how you tell a confident result from a lucky one.
• Ranks alternatives when an address is ambiguous. Ask for more than one candidate and every possibility comes back ranked, instead of one arbitrary guess.
• Controls the fallback behaviour. Region and postal centroid fallbacks can be turned off, so an address that cannot be placed properly returns nothing rather than a plausible looking wrong point.
• Covers the whole world. Reference data is selected by country, so setting the country correctly is what decides which sources an address is checked against.
• Never loses a row. An address that matches nothing still produces a row saying so, so the output lines up with the input.

Input

Geocode mode: address to coordinates

{
  "mode": "geocode",
  "bundle": "premium",
  "country": "USA",
  "addresses": [
    "4750 Walnut St., Boulder CO, 80301",
    { "addressLine1": "210 King St", "city": "San Francisco", "stateProvince": "CA", "postalCode": "94107" }
  ],
  "matchMode": "Standard",
  "maxCandidates": 1,
  "maxResults": 100
}

Verify mode: standardize and validate

{
  "mode": "verify",
  "country": "USA",
  "addresses": [
    { "addressLine1": "4750 walnut st", "city": "boulder", "stateProvince": "co", "postalCode": "80301" }
  ],
  "outputCasing": "U",
  "batchSize": 25
}

Example output

A geocode row.

{
  "mode": "geocode",
  "matched": true,
  "inputIndex": 0,
  "inputSummary": "4750 Walnut St., Boulder CO, 80301",
  "candidateIndex": 0,
  "latitude": 40.018233,
  "longitude": -105.241023,
  "precisionCode": "S8HPNTSCZA",
  "precisionLevel": 1,
  "formattedStreetAddress": "4750 WALNUT ST",
  "mainAddressLine": "4750 WALNUT ST",
  "addressLastLine": "BOULDER, CO 80301-2532",
  "areaName1": "CO",
  "areaName3": "BOULDER",
  "postCode1": "80301",
  "postCode2": "2532",
  "country": "USA",
  "addressNumber": "4750",
  "streetName": "WALNUT",
  "matchOnAddressNumber": true,
  "matchOnStreetName": true,
  "matchOnPostCode1": true
}

A verify row.

{
  "mode": "verify",
  "matched": true,
  "status": "S",
  "addressLine1": "4750 WALNUT ST",
  "city": "BOULDER",
  "stateProvince": "CO",
  "postalCode": "80301-2532",
  "postalCodeBase": "80301",
  "postalCodeAddOn": "2532",
  "country": "UNITED STATES OF AMERICA",
  "blockAddress": "4750 WALNUT ST BOULDER CO 80301-2532"
}

Frequently asked questions

What is the difference between geocoding and address verification?

Geocoding answers where an address is: it returns latitude and longitude plus a precision code saying what those coordinates describe. Verification answers whether an address is real and how it should be written: it returns the standardized form and a pass or fail status. They are separately entitled services at this provider, so a subscription may cover one and not the other, and the mode option decides which one a run calls.

What do the accuracy tiers mean?

The tier is part of the request path, so it changes both what you get and what you pay. Premium geocodes to a rooftop or building level point using master location data. Advanced geocodes to street level. Basic geocodes to a place or postal code centroid. Pick the tier your subscription covers; a tier it does not cover is refused by the gateway.

How do I know whether a coordinate is exact?

Read the precision code and level on the row. A rooftop match and a postal code centroid both return a latitude and a longitude that look equally precise, and only the precision code distinguishes them. If you would rather have nothing than a centroid, turn off both the region and postal fallbacks and unmatchable addresses will come back as non matches instead.

What does the match mode do?

It sets how much difference between your address and the reference data is tolerated. Exact accepts near identical input only. Standard is the balanced default. Relaxed finds more matches and accepts more risk of a wrong one. Two further modes, Interactive and CASS, are United States only, and CASS is the postal certified mode used for mailing discounts.

Can it handle addresses outside the United States?

Yes. Reference data is selected by country, given as a name or an ISO code such as USA, GBR, DEU or AUS. Set the default country to cover a whole list, or put a country on individual addresses where the list is mixed. Getting the country right matters more than it looks, because it decides which reference sources the address is checked against at all.

What format should my addresses be in?

Either. A plain string is treated as a whole address in one line, which is what the geocoding service prefers. An object with separate fields is used as given, and the actor assembles whichever shape the chosen service needs. Everyday column names such as line1, town, state and zip are rewritten to the provider's own names for you, so a spreadsheet export usually works unchanged.

Do I need my own API key?

Yes. This actor is bring your own key: it calls the API using your own key and secret, which are exchanged once per run for an access token, so you keep your own subscription, your own entitlements and your own data agreement. The key and secret are issued as a pair per project at this provider rather than per account.

Why did an address come back with a status of F?

That is the verification service reporting a failure, and the reason is in the status code and status description on the same row. Common causes are an address that does not exist in the reference data, a postal code that contradicts the city, and a country the account is not entitled to. The row is kept rather than dropped, so you can sort by status code and see the pattern.

How much does a run cost?

Charging is per row. Every address result the provider returned is charged, matched or not, because the provider bills that lookup either way. Rows refused before sending, such as an entry with no address in it, are never charged. Asking for several candidates per address produces several rows and is charged for each. Set maxResults to cap what a run can spend.

Keyword map

geocoding API, address to latitude longitude, rooftop geocoding, forward geocoding API, address verification API, global address validation, address standardization API, postal code lookup, ZIP+4 add-on, address parsing API, address components API, precision code geocoding, batch geocoding, bulk address cleaning, international address verification, geocode by country, street level geocoding, centroid fallback, address match confidence, location data enrichment