US Census Address Geocoding API

Geocode recurring US address batches with the official US Census Geocoder. Turn street addresses into standardized matches, latitude and longitude, Census tract and block identifiers, county and place data, match status, and source provenance—without obtaining a Census API key.

The Actor keeps one output row per input address and preserves input order. A successful source match triggers the matched-geocode event; no-match and upstream-error diagnostic rows have no per-result charge.

What does this Actor do?

Submit one or many one-line US street addresses. For each address, the Actor calls the official Census Geocoder and exports:

• the original address and its input position;
• a standardized matched address;
• latitude and longitude;
• normalized street, city, state, and ZIP components;
• Census state, county, tract, block, block-group, place, and district identifiers when exposed;
• TIGER/Line segment provenance;
• an explicit matched, ambiguous, not_found, or error status;
• source benchmark, vintage, URL, and processing time.

It uses the current public address-range benchmark. This is address-range geocoding, not postal deliverability certification.

Who is it for?

• CRM operators cleaning and enriching recurring lead or customer lists.
• Analysts joining street-address records to Census tract or county datasets.
• Logistics teams preparing addresses for routing or delivery-review workflows.
• Real-estate teams adding map coordinates and Census geography to property lists.
• Developers who need a batch-friendly JSON interface around the public Census service.

Why use it?

The Census service is authoritative, public, and does not require an API key, but integrating it still requires input validation, concurrency limits, retries, output normalization, and diagnostics. This Actor provides those operational pieces and produces an integration-ready Apify dataset.

Key behavior:

1. Accepts up to 10,000 addresses per run.
2. Preserves duplicates and source order for safe joins back to your input.
3. Retries only transient timeouts, rate limits, and temporary server failures.
4. Returns useful status rows for unmatched addresses instead of silently dropping them.
5. Does not use a proxy, browser, login, or third-party geocoding provider.

Getting started

1. Open the Actor in Apify Console.
2. Paste addresses into US street addresses.
3. Keep Include Census geography enabled if you need tract, block, county, place, or district identifiers.
4. Click Start.
5. Open the Geocoding results dataset view.
6. Export JSON, CSV, Excel, XML, or another supported dataset format.

A ready-to-run input:

{
  "addresses": [
    "1600 Pennsylvania Ave NW, Washington, DC 20500",
    "350 5th Ave, New York, NY 10118",
    "1 Dr Carlton B Goodlett Pl, San Francisco, CA 94102"
  ],
  "includeGeographies": true
}

Input parameters

Field	Type	Default	Description
addresses	string array	required	Between 1 and 10,000 one-line US street addresses, each 5–500 characters.
includeGeographies	boolean	true	Include current Census geography layers. Disable for standardized address and coordinates only.
maxConcurrency	integer	5	Concurrent requests, from 1 to 20. The default is considerate of the public service.
maxRequestRetries	integer	2	Retries per address for transient failures, from 0 to 4.

Malformed input fails the run before any address request. A syntactically valid address that Census cannot match produces not_found.

Output fields

Group	Fields	Meaning
Input	inputIndex, inputAddress	Stable join keys back to the submitted array.
Outcome	matchStatus, matchQuality, matchCount, errorMessage	Match result and bounded diagnostic.
Match	matchedAddress, latitude, longitude	Standardized source match and coordinates.
Address	addressNumber, streetName, streetType, city, state, zipCode	Normalized components exposed by Census.
Geography	stateFips, countyFips, countyName, censusTract, censusBlock, blockGroup	Common Census geography identifiers.
Place/district	placeFips, placeName, congressionalDistrict, geographyIds	Place, current district, and every other exposed layer GEOID.
TIGER/Line	tigerLineId, tigerLineSide	Source street-segment provenance.
Provenance	benchmark, vintage, sourceName, sourceUrl, processedAt	Source and processing metadata.

Fields that the source does not expose are null. The dynamic geographyIds object preserves additional layer GEOIDs under the layer names returned by Census.

Example output

This abbreviated record reflects the Actor's current response for the White House address:

{
  "inputIndex": 0,
  "inputAddress": "1600 Pennsylvania Ave NW, Washington, DC 20500",
  "matchStatus": "matched",
  "matchQuality": "single_match",
  "matchCount": 1,
  "matchedAddress": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500",
  "latitude": 38.89869893252,
  "longitude": -77.03518753691,
  "stateFips": "11",
  "countyFips": "11001",
  "countyName": "District of Columbia",
  "censusTract": "11001980000",
  "censusBlock": "110019800001034",
  "tigerLineId": "76225813",
  "benchmark": "Public_AR_Current",
  "vintage": "Current_Current",
  "sourceName": "US Census Geocoder",
  "sourceUrl": "https://geocoding.geo.census.gov/geocoder/"
}

Exact coordinates and current geography layers can change when Census updates its benchmark or vintage.

Match statuses and diagnostics

• matched: one source match was selected.
• ambiguous: the source returned multiple matches; the first is normalized and matchCount preserves the ambiguity signal.
• not_found: the request succeeded but the source returned no address match.
• error: retries were exhausted or the response was invalid; errorMessage explains the bounded failure.

If every address request ends in error, the Actor fails rather than presenting an empty or misleading successful run. Completed matches and no-match outcomes remain ordinary dataset rows.

How much does it cost to geocode US addresses?

Pricing has a $0.005 start fee plus a tier-dependent fee for each matched geocode. At the BRONZE tier, a matched geocode is $0.00796. Unmatched and errored addresses have no per-result charge.

BRONZE examples:

Submitted batch outcome	Cost
1 matched address	$0.005 + (1 × $0.00796)
10 matched addresses	$0.005 + (10 × $0.00796)
100 matched addresses	$0.005 + (100 × $0.00796)
80 matches and 20 not found	$0.005 + (80 × $0.00796); no per-result fee for the 20 no-match rows

Higher account tiers receive lower per-match prices. Actual run cost follows the active tier shown in Apify Console.

Reliability, retries, and respectful use

The Actor sends direct HTTPS requests to the official public JSON service. It uses no proxy and no browser. Each request has a 30-second timeout. Only network failures, HTTP 429, and temporary 5xx responses receive bounded exponential-backoff retries.

For large jobs:

• keep concurrency at the default unless you have measured a reason to change it;
• split operationally critical batches so one upstream incident does not delay all work;
• retain inputIndex when joining output back to source records;
• schedule during a suitable window if the Census service is under load.

The Actor cannot make the public service available during a Census outage.

Coverage and limitations

The US Census Geocoder matches against address ranges in its current benchmark. It is not USPS CASS certification and does not prove that mail can be delivered to a unit, apartment, or business.

Common reasons for not_found include:

• a new street not yet present in the benchmark;
• incomplete or misspelled street details;
• unsupported PO boxes or non-street descriptions;
• missing city/state context;
• an address outside the United States.

Geography fields depend on the layers Census exposes for the matched point. Some fields may be null.

Export and integration workflows

Use the default dataset to:

• export CSV for CRM re-import;
• join tract GEOIDs to Census demographic tables;
• send latitude and longitude into mapping or routing tools;
• filter not_found rows into a manual review queue;
• preserve source order in Make, Zapier, n8n, or custom ETL jobs;
• schedule periodic enrichment for newly added CRM records.

For incremental workflows, submit only new or changed addresses. This Actor does not maintain a cross-run change history.

Run with the Apify API

Replace YOUR_TOKEN with an Apify API token.

cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~us-address-geocoding-api/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addresses":["1600 Pennsylvania Ave NW, Washington, DC 20500"],"includeGeographies":true}'

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/us-address-geocoding-api').call({
  addresses: ['350 5th Ave, New York, NY 10118'],
  includeGeographies: true,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("automation-lab/us-address-geocoding-api").call(run_input={
    "addresses": ["1 Dr Carlton B Goodlett Pl, San Francisco, CA 94102"],
    "includeGeographies": True,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

Use with MCP and AI assistants

Add the Actor to Claude Code through Apify MCP:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/us-address-geocoding-api"

Setup for Claude Desktop, Cursor, or VS Code

Use this equivalent HTTP MCP configuration in Claude Desktop, Cursor, or VS Code:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/us-address-geocoding-api"
    }
  }
}

Example prompts:

• “Geocode these US office addresses and return input address, standardized address, latitude, longitude, county, and Census tract.”
• “Check this CRM address batch and separate matched records from addresses that need manual review.”
• “Add Census block identifiers to these property addresses while preserving their original order.”

Legality and responsible use

Street addresses may contain personal information. Process only data you are permitted to use, minimize retention, and follow applicable privacy and contractual obligations.

The geocoding response comes from the US Census Bureau's public service. Review Census terms, service notices, and attribution expectations for your use case. Do not represent a geocoder match as postal deliverability, occupancy, ownership, or identity verification.

Troubleshooting

Why did a real address return not_found?

Try a complete street, city, state, and ZIP combination. Census address-range coverage differs from postal delivery databases and may lag recent construction.

Why are geography fields null?

Confirm includeGeographies is true. A source match can still lack a particular geography layer.

Why did the run fail after producing error rows?

The Actor intentionally fails when every upstream request fails. Check the run log for an outage or rate-limit pattern, then retry later rather than treating the data as valid.

Can I submit coordinates for reverse geocoding?

No. This Actor's supported contract is forward geocoding of one-line US street addresses.

FAQ

Do I need a Census API key?
No. The public Census Geocoder endpoint used here does not require one.

Are duplicate addresses removed?
No. Each input produces its own ordered row so you can safely join results back to the original batch.

Are unmatched addresses charged?
No. Only successful or ambiguous matched geocodes trigger the per-match event; every run also has the stated start fee.

Can I geocode international addresses?
No. The source and Actor are scoped to US street addresses.

How many addresses can one run process?
Up to 10,000. The upstream public service remains the practical availability constraint.

Related automation-lab Actors

For another CRM hygiene step, use Bulk Email Address Verifier to validate email syntax, domain, MX, disposable-domain, and role-address signals. It is a separate product and does not alter this Actor's address-geocoding results.