# Geocoding API - Address Verification and Lat Long Lookup (`nabeelbaghoor/geocoding-address-api`) Actor

Turn addresses into rooftop latitude and longitude, or verify and standardize them against global postal reference data. Returns ranked candidates with a precision code, parsed address components, postal code plus add-on and per field match flags. Worldwide coverage.

- **URL**: https://apify.com/nabeelbaghoor/geocoding-address-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 address results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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

```json
{
  "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

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

### Example output

A geocode row.

```json
{
  "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.

```json
{
  "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

# Actor input Schema

## `mode` (type: `string`):

Geocode turns each address into coordinates and returns ranked candidates with a precision code. Verify checks each address against postal reference data and returns the standardized form with a pass or fail status. These are separately entitled services at this provider, so a subscription may cover one and not the other.

## `addresses` (type: `array`):

One entry per address. A plain string is used as a whole address in one line, which is what the geocoding service prefers. An object may use this provider's own field names, addressLine1, addressLine2, firmName, city, stateProvince, postalCode and country, and everyday names are accepted too, so line1, town, state, zip and company all work. Whichever shape you give, the other is assembled for you, so the same list runs through either mode.

## `apiKey` (type: `string`):

Your own API key for this provider. Bring your own credentials: nothing is shared between runs and the credentials are never written to the dataset. The key and secret are issued as a pair per project, and are exchanged once per run for an access token.

## `apiSecret` (type: `string`):

Your own API secret for this provider, the other half of the pair. It is used only for the token exchange and never reaches a data call.

## `bundle` (type: `string`):

How precisely the geocoding service places a point. This sits in the request path at this provider, so it decides both the accuracy and the price, and your subscription has to cover the tier you pick. Ignored in verify mode.

## `country` (type: `string`):

A country applied to every address that does not name its own, given as a name or an ISO code such as USA, GBR, DEU or AUS. This provider selects its reference data by country, so setting it correctly is what decides which sources an address is checked against.

## `matchMode` (type: `string`):

How much difference between your address and the reference data the geocoding service will tolerate. Exact accepts almost nothing. Standard is the sensible default. Relaxed finds more at the cost of some wrong matches. The two named for a single country only work in that country.

## `maxCandidates` (type: `integer`):

How many possible matches the geocoding service may return for one address. Above one is how an ambiguous address returns every possibility rather than a single guess. Each candidate is a row and is charged as a row.

## `fallbackGeo` (type: `boolean`):

When no address level match is possible, return the centre of the geographic region instead of nothing. Useful for mapping at a glance, misleading for anything that needs a real location, because the point will look precise and will not be.

## `fallbackPostal` (type: `boolean`):

When no address level match is possible, return the centre of the postal code instead of nothing. Same caution as the region fallback: check the precision code before treating a coordinate as exact.

## `removeAccentMarks` (type: `boolean`):

Suppress accents and other diacritical marks in the returned address. Turn this on when the result has to go into a system that cannot store them.

## `outputCasing` (type: `string`):

How the standardized address is capitalised in verify mode. Upper case is what most postal standards expect. Mixed case is what you want if the address will be shown to a person.

## `batchSize` (type: `integer`):

How many addresses go up in one verification request. The provider takes a batch but does not publish a ceiling, so this is this actor's own chunk size and is deliberately conservative. Lower it if large batches are being refused.

## `skipUnmatched` (type: `boolean`):

Leave addresses that did not match out of the dataset entirely. Off by default, because a confirmed non match is usually the row worth knowing about. They are charged either way, because the provider bills the lookup.

## `baseUrl` (type: `string`):

Overrides the host outright. Leave empty unless your account was issued a dedicated hostname or you run this provider's software on your own network.

## `maxResults` (type: `integer`):

Stop after this many rows. Rows are charged individually, so this is the ceiling on what a run can cost.

## `requestsPerMinute` (type: `integer`):

How fast to call the provider. Lower this if your subscription has a tighter rate ceiling than the default.

## Actor input object example

```json
{
  "mode": "geocode",
  "addresses": [
    "4750 Walnut St., Boulder CO, 80301",
    {
      "addressLine1": "210 King St",
      "city": "San Francisco",
      "stateProvince": "CA",
      "postalCode": "94107"
    }
  ],
  "bundle": "premium",
  "country": "USA",
  "matchMode": "Standard",
  "maxCandidates": 1,
  "fallbackGeo": true,
  "fallbackPostal": true,
  "removeAccentMarks": false,
  "outputCasing": "U",
  "batchSize": 25,
  "skipUnmatched": false,
  "maxResults": 100,
  "requestsPerMinute": 120
}
```

# Actor output Schema

## `addresses` (type: `string`):

One row per result, alongside the input address it came from.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "addresses": [
        "4750 Walnut St., Boulder CO, 80301",
        {
            "addressLine1": "210 King St",
            "city": "San Francisco",
            "stateProvince": "CA",
            "postalCode": "94107"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/geocoding-address-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "addresses": [
        "4750 Walnut St., Boulder CO, 80301",
        {
            "addressLine1": "210 King St",
            "city": "San Francisco",
            "stateProvince": "CA",
            "postalCode": "94107",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/geocoding-address-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "addresses": [
    "4750 Walnut St., Boulder CO, 80301",
    {
      "addressLine1": "210 King St",
      "city": "San Francisco",
      "stateProvince": "CA",
      "postalCode": "94107"
    }
  ]
}' |
apify call nabeelbaghoor/geocoding-address-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/geocoding-address-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/1bnuZYPfZR93DFrS1/builds/B2w5zIyC87xpNuEnv/openapi.json