# US Address Geocoder + Census Tract Lookup (Census Bureau) (`kdhan/us-census-geocoder`) Actor

Geocode US street addresses with the official Census Bureau Geocoder: latitude/longitude plus state, county, census tract and block FIPS codes with names. Batch-based, no API key. Unmatched or failed lookups are free and never reported as safe.

- **URL**: https://apify.com/kdhan/us-census-geocoder.md
- **Developed by:** [Doohan Kim](https://apify.com/kdhan) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 address records

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## US Address Geocoder + Census Tract Lookup (Census Bureau)

Turn US street addresses into latitude/longitude and the **census state, county, tract and block**
they fall in, using the official **U.S. Census Bureau Geocoder** (`geocoding.geo.census.gov`).
No API key, no scraping. Addresses are sent in batches of up to 10,000 per request.

Typical uses: attach a census tract to a customer list (to join ACS/Census statistics), check which
county or state an address falls in, add coordinates to a spreadsheet of addresses.

### What you get (one row per input address, in input order)

| Field | Meaning |
|---|---|
| `input` | Your address exactly as you sent it |
| `matched` | `true` = found, `false` = Census has no match, `null` = **not decided** (see `matchStatus`) |
| `matchStatus` | `Match`, `No_Match`, `Tie` (several equally good matches), `Invalid` (your input was unusable), `Error` (the lookup failed) |
| `matchedAddress`, `matchType` | Standardized address Census matched, and `Exact` / `Non_Exact` |
| `latitude`, `longitude`, `tigerLineId`, `side` | Interpolated point and the street segment it came from |
| `stateFips`, `stateName`, `stateAbbr` | State |
| `countyFips`, `countyGeoid`, `countyName` | County (3-digit and 5-digit code) |
| `tractCode`, `tractGeoid`, `tractName` | Census tract (6-digit and 11-digit GEOID) |
| `blockCode`, `blockGeoid`, `blockName` | Census block (4-digit and 15-digit GEOID) |
| `benchmark`, `vintage`, `dataAsOf`, `source`, `disclaimer` | Which Census data version answered, and when |
| `error`, `note`, `sectionErrors` | Why a row is undecided or incomplete |

### Input

```json
{
  "addresses": ["1600 Pennsylvania Ave NW, Washington, DC 20500"],
  "structuredAddresses": [{"street": "350 5th Ave", "city": "New York", "state": "NY", "zip": "10118"}],
  "includeGeographies": true,
  "benchmark": "Public_AR_Current",
  "vintage": "Current_Current"
}
```

All fields are optional; with no input the Actor geocodes an example public building. Include a city
and state, or a ZIP code, with every street. `benchmark` / `vintage` are checked against the
Census Bureau's own lists before the run starts.

### Read this before trusting a match

- **`matchType: Non_Exact` can be a different address.** In our test of 20 public buildings, 5 came
  back `Non_Exact`: for example `200 N Spring St, Los Angeles` was matched to `200 S SPRING ST`
  (about 350 m away) and `1 City Hall Sq, Boston` to `1 CITY HALL AVE`. Compare `matchedAddress`
  with your input when exactness matters.
- **Coordinates are interpolated** along a street segment's address range, not measured at the
  building. Address ranges include numbers where no building exists.
- **`Tie` is not "no match".** It means Census found several equally good candidates. Add a ZIP
  code or direction and retry. Ties are free and returned with `matched: null`.
- **Connecticut:** the batch service returns the legacy county codes (for example `09003`
  Hartford County). Census's single-address service with the "Current" vintage returns the newer
  planning-region codes (`09110`). Tracts have the same number, but the county part of the GEOID
  differs. Pick your join key accordingly.
- Some addresses lie across a state line from their postal name (the Census Bureau's own
  Suitland, MD headquarters is addressed "Washington, DC"): the state fields describe where the
  point is, not what the mailing address says.

### No silent failures

- An address Census cannot find is `matched: false` (free).
- If the Census service is down, times out, or leaves out a row, the row is `matched: null`,
  `matchStatus: "Error"` with an `error` text. It is never reported as "no match", and it is free.
- If a county name cannot be resolved the code is still returned and `sectionErrors` says so.

### Pricing event

`address-record`: one per address that **matched**. No-match, tie, error and invalid rows are free.
Your spending limit is respected: when the limit is reached the run stops and says so in the log.

### Privacy

The Actor never writes your addresses to its log (it logs counts only). Addresses are sent to the
Census Bureau's public service to be geocoded and returned in your dataset.

### Source and disclaimer

Data: U.S. Census Bureau Geocoder API (MAF/TIGER address ranges), provided as-is. This product uses
the Census Bureau Data API but is not endorsed or certified by the Census Bureau. The Census Bureau may
limit access to its service; the Actor paces its requests and retries on 429/5xx with back-off.

# Actor input Schema

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

US addresses such as 1600 Pennsylvania Ave NW, Washington, DC 20500. Include city and state or a ZIP code.

## `structuredAddresses` (type: `array`):

Objects like {"street": "350 5th Ave", "city": "New York", "state": "NY", "zip": "10118"}. Street plus a ZIP code, or street plus city and state.

## `includeGeographies` (type: `boolean`):

Add state, county, census tract and block codes and names to each match.

## `benchmark` (type: `string`):

Census address-range version, for example Public_AR_Current (default) or Public_AR_Census2020.

## `vintage` (type: `string`):

Census geography version used for census areas, for example Current_Current (default) or Census2020_Current.

## Actor input object example

```json
{
  "addresses": [
    "1600 Pennsylvania Ave NW, Washington, DC 20500"
  ],
  "includeGeographies": true,
  "benchmark": "Public_AR_Current",
  "vintage": "Current_Current"
}
```

# Actor output Schema

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

Match status, standardized address, coordinates, match type, TIGER line ID and census state/county/tract/block codes and names.

# 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": [
        "1600 Pennsylvania Ave NW, Washington, DC 20500"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("kdhan/us-census-geocoder").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": ["1600 Pennsylvania Ave NW, Washington, DC 20500"] }

# Run the Actor and wait for it to finish
run = client.actor("kdhan/us-census-geocoder").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": [
    "1600 Pennsylvania Ave NW, Washington, DC 20500"
  ]
}' |
apify call kdhan/us-census-geocoder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kdhan/us-census-geocoder"
        }
    }
}
```

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/A4vkLwLU7tpPerZOk/builds/0HkzAeylppyHsqgRi/openapi.json