# U.S. Census Geocoder (`maximedupre/us-census-geocoder`) Actor

Match U.S. street addresses or coordinates with the Census Geocoder. Export standardized addresses, coordinates, TIGER/Line details, and available Census geography.

- **URL**: https://apify.com/maximedupre/us-census-geocoder.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Developer tools, Business, Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$9.90 / 1,000 matched geocodes

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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

### 🗺️ Turn U.S. addresses into Census-ready location data

U.S. data analysts, researchers, and operations teams can match street addresses or coordinates against the official U.S. Census Geocoder. Get standardized addresses, latitude and longitude, TIGER/Line details, and available state, county, tract, block, and GEOID fields—while keeping every submitted item correlated with its outcome.

- Run a **[geocode lookup by address](https://apify.com/maximedupre/us-census-geocoder/examples/geocode-lookup-by-address)** for customer, property, or facility records.
- Retrieve a **[2020 census tract identifier](https://apify.com/maximedupre/us-census-geocoder/examples/2020-census-tract-identifier)** when that geography is available from the source.
- Perform an **[11 digit census tract number lookup](https://apify.com/maximedupre/us-census-geocoder/examples/11-digit-census-tract-number-lookup)** with the returned tract GEOID.
- Automate batch address matching through a **[census geocoder api](https://apify.com/maximedupre/us-census-geocoder/examples/census-geocoder-api)** workflow.
- Build a **[census geocoder python](https://apify.com/maximedupre/us-census-geocoder/examples/census-geocoder-python)** pipeline with the Apify API client and dataset exports.
- Use **[reverse geocode U.S. coordinates](https://apify.com/maximedupre/us-census-geocoder/examples/reverse-geocode-u-s-coordinates)** to associate points with nearby Census/TIGER street ranges.

#### 📦 Returned data

Every processed input produces one correlated row with `status` set to `matched`, `unmatched`, or `error`. `itemIndex` preserves input order, and your optional `reference` is returned unchanged.

| Field | Description |
| --- | --- |
| `status` | Match outcome: `matched`, `unmatched`, or `error`. |
| `itemIndex`, `reference` | Zero-based input position and optional caller reference. |
| `requestedAddress` | Original address for address runs. |
| `requestedLatitude`, `requestedLongitude` | Original point for coordinate runs. |
| `matchedAddress`, `latitude`, `longitude` | Standardized match and coordinates when matched. |
| `addressComponents` | Available street name, directions, street type, city, state, and ZIP code. |
| `tigerLine` | Available line ID, street side, and address range. |
| `geography` | Available Census state, county, tract and tract GEOID, block and block GEOID, and geography layers. |
| `error` | Item-level error message after bounded retries. |

Fields that do not apply or were not supplied by the source are omitted.

#### 🚀 Running the Actor

1. Choose **Street addresses** or **Coordinates** as the Target.
2. Add one or more items to the active Target section.
3. Run the Actor and open the default dataset. Census geography is included automatically on matched outcomes.

Choose one Target per run. To process both addresses and coordinates, use separately configured runs.

#### 🎯 Input

| Input | Type | Description |
| --- | --- | --- |
| `target` | String | Required: `addresses` or `coordinates`. |
| `addresses` | Array | Objects containing a non-empty `address` and optional string `reference`. |
| `coordinates` | Array | Objects containing numeric `latitude`, `longitude`, and optional string `reference`. |

Example address input:

```json
{
  "target": "addresses",
  "addresses": [
    {
      "address": "4600 Silver Hill Rd, Suitland, MD 20746",
      "reference": "headquarters"
    }
  ]
}
````

#### 🧾 Output example

```json
{
  "target": "addresses",
  "status": "matched",
  "itemIndex": 0,
  "reference": "headquarters",
  "requestedAddress": "4600 Silver Hill Rd, Suitland, MD 20746",
  "matchedAddress": "4600 SILVER HILL RD, SUITLAND, MD, 20746",
  "latitude": 38.845985,
  "longitude": -76.92744,
  "tigerLine": {
    "lineId": "76355984",
    "side": "L",
    "fromAddress": "4600",
    "toAddress": "4698"
  },
  "geography": {
    "stateName": "Maryland",
    "stateFips": "24",
    "countyName": "Prince George's County",
    "countyFips": "033",
    "censusTract": "802400",
    "censusBlock": "1000",
    "blockGeoid": "240338024001000",
    "layers": []
  }
}
```

Values above illustrate the schema; source-returned match details vary by location.

#### 💳 Pricing

This Actor uses pay-per-event pricing. A **Matched geocode** costs $0.0099 and is charged once for each successfully matched address or coordinate result made visible in the dataset. Available Census geography is included in that event at no separate charge.

Unmatched inputs, item-level errors, empty work, retries, status-only records, and failed work are not charged as matched geocodes. A charge limit can stop a run with partial correlated results.

#### 🔌 Integrations

https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4

Use the Apify API to run repeatable jobs from Python, JavaScript, or other HTTP clients. Results are stored in the default Apify dataset and can be exported in standard dataset formats, scheduled, or passed to downstream workflows with webhooks.

#### ⚠️ Coverage and precision

The Actor queries the official U.S. Census Geocoder and uses current TIGER/Line data. Coverage is U.S.-only. Matches represent Census/TIGER street-address ranges, not guaranteed rooftop positions or postal-deliverability verification. PO boxes, rural routes, malformed or nonexistent addresses, and new construction absent from current Census data may be unmatched.

For coordinate runs, the Actor finds a nearby address-bearing TIGER/Line street segment and interpolates an address from its official range. It does not provide routing, distance calculations, demographic statistics, or confidence scores.

#### ❓ FAQ

##### Why did a valid-looking address return `unmatched`?

The Census source may not contain a suitable TIGER/Line match. Check the full street, city, state, and ZIP input; PO boxes, rural routes, recent construction, and locations outside the U.S. may not match.

##### Is a coordinate result a rooftop address?

No. Reverse results use a nearby address-bearing TIGER/Line segment and interpolate its address range. Treat them as street-range matches rather than parcel or rooftop verification.

##### How do I form an 11-digit tract GEOID?

The returned `censusTract` is the six-digit tract component when available, while `tractGeoid` is the complete 11-digit identifier. You can also form it from `stateFips` (2 digits), `countyFips` (3 digits), and `censusTract` (6 digits). `blockGeoid` is a separate, longer block identifier.

##### Do I need a U.S. Census API key?

No. The public input does not request Census credentials. You still need an Apify account to run the Actor on Apify.

##### Can I submit addresses and coordinates together?

Not in one run. Choose one Target, then create a separate run for the other Target.

##### What happens when one source request fails?

Transient source requests receive bounded retries. If an item still fails, its correlated row has `status: "error"`; it is not silently dropped and is not charged as a match.

### 📝 Changelog

- 0.1: Initial release.

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~us-census-geocoder/issues) to contact the maintainer.

### 🔗 Other actors

- [FCC License Search ↗](https://apify.com/maximedupre/fcc-license-search-scraper) - Search public FCC licenses or look up Census geography for U.S. coordinates.
- [Business Address Scraper ↗](https://apify.com/maximedupre/business-address-scraper) - Find physical addresses published on company websites before geocoding.
- [Realtor Scraper ↗](https://apify.com/maximedupre/realtor-scraper) - Collect property listings with addresses and coordinates before geocoding.
- [Google Maps Shared List Scraper ↗](https://apify.com/maximedupre/google-maps-shared-list-scraper) - Export addresses and coordinates from public shared place lists.
- [Yellow Pages Scraper ↗](https://apify.com/maximedupre/yellowpages-scraper) - Gather public U.S. business addresses for batch matching.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `target` (type: `string`):

Choose whether to match street addresses or latitude/longitude points. Run separately configured searches in separate runs.

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

U.S. street addresses to match. Each item needs an address and may include your own reference, which is returned unchanged for reconciliation.

## `coordinates` (type: `array`):

U.S. latitude/longitude points to match to the nearest Census/TIGER address range. Each item may include your own reference, which is returned unchanged.

## Actor input object example

```json
{
  "target": "addresses",
  "addresses": [
    {
      "address": "4600 Silver Hill Rd, Washington, DC 20233",
      "reference": "headquarters"
    }
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

Review every correlated Census Geocoder outcome in the default dataset overview.

# 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 = {
    "target": "addresses",
    "addresses": [
        {
            "address": "4600 Silver Hill Rd, Washington, DC 20233",
            "reference": "headquarters"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/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 = {
    "target": "addresses",
    "addresses": [{
            "address": "4600 Silver Hill Rd, Washington, DC 20233",
            "reference": "headquarters",
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/us-census-geocoder").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "target": "addresses",
  "addresses": [
    {
      "address": "4600 Silver Hill Rd, Washington, DC 20233",
      "reference": "headquarters"
    }
  ]
}' |
apify call maximedupre/us-census-geocoder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=maximedupre/us-census-geocoder",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "U.S. Census Geocoder",
        "description": "Match U.S. street addresses or coordinates with the Census Geocoder. Export standardized addresses, coordinates, TIGER/Line details, and available Census geography.",
        "version": "0.1",
        "x-build-id": "uer8iv9W7nBHlkN2P"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/maximedupre~us-census-geocoder/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-maximedupre-us-census-geocoder",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/maximedupre~us-census-geocoder/runs": {
            "post": {
                "operationId": "runs-sync-maximedupre-us-census-geocoder",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/maximedupre~us-census-geocoder/run-sync": {
            "post": {
                "operationId": "run-sync-maximedupre-us-census-geocoder",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "target"
                ],
                "properties": {
                    "target": {
                        "title": "Target",
                        "enum": [
                            "addresses",
                            "coordinates"
                        ],
                        "type": "string",
                        "description": "Choose whether to match street addresses or latitude/longitude points. Run separately configured searches in separate runs."
                    },
                    "addresses": {
                        "title": "Addresses",
                        "minItems": 1,
                        "maxItems": 1000000,
                        "type": "array",
                        "description": "U.S. street addresses to match. Each item needs an address and may include your own reference, which is returned unchanged for reconciliation.",
                        "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                                "address"
                            ],
                            "properties": {
                                "address": {
                                    "title": "Address",
                                    "description": "A complete U.S. street address, such as 4600 Silver Hill Rd, Washington, DC 20233.",
                                    "type": "string",
                                    "minLength": 1
                                },
                                "reference": {
                                    "title": "Reference",
                                    "description": "Optional caller-supplied reference returned unchanged.",
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "coordinates": {
                        "title": "Coordinates",
                        "minItems": 1,
                        "maxItems": 1000000,
                        "type": "array",
                        "description": "U.S. latitude/longitude points to match to the nearest Census/TIGER address range. Each item may include your own reference, which is returned unchanged.",
                        "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                                "latitude",
                                "longitude"
                            ],
                            "properties": {
                                "latitude": {
                                    "title": "Latitude",
                                    "description": "Latitude in decimal degrees, from -90 to 90.",
                                    "type": "number",
                                    "minimum": -90,
                                    "maximum": 90
                                },
                                "longitude": {
                                    "title": "Longitude",
                                    "description": "Longitude in decimal degrees, from -180 to 180.",
                                    "type": "number",
                                    "minimum": -180,
                                    "maximum": 180
                                },
                                "reference": {
                                    "title": "Reference",
                                    "description": "Optional caller-supplied reference returned unchanged.",
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```