Apify Public Data & Leads

US Census Address Geocoder

us_census_geocoder

Read-only

Geocode US addresses to Census tracts, blocks, county FIPS, congressional districts, and school districts for demographic joins, site selection, and district-based targeting.

Instructions

Geocode US street addresses into full Census Bureau geography, not just a pin: state and county FIPS, census tract and block GEOIDs, congressional district, incorporated place, school district and metro area (CBSA). Built on the official, public-domain Census Bureau geocoder.

Behavioral Transparency:

Execution: Network call executed synchronously in the cloud via Apify Actor 'captainhandsome/us-census-geocoder'.
Side Effects: Reads public sources and creates a billed Actor run and dataset on your Apify account.
Authentication: Requires APIFY_TOKEN environment variable.
Latency & Limits: Requests run five addresses at a time against the Census Bureau's geocoder with a 60-second timeout each; typical run duration is 10-60 seconds depending on list size, timeout capped at 120 seconds. Returns exactly one row per address, matched or not - output volume is set by the length of 'addresses', not by 'max_results'.

Usage Guidelines:

When to use: Use to append census tract, block, county FIPS, congressional district or school district GEOIDs to US street addresses for demographic joins, site selection, fair-lending/CRA reporting, or district-based targeting.
When NOT to use: Do not use for interactive place search, driving directions or points of interest; do not use for business entity or contractor license lookups (use 'us_business_entity_search' or 'us_contractor_license_search'). Addresses outside the United States are not supported.
Named alternatives: Use 'us_business_entity_search' or 'us_contractor_license_search' for entity and licensing lookups instead of an address. No other tool in this toolset performs US address geocoding.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`vintage`	No	Which geography vintage to report tract, block and district boundaries from. Defaults to 'Current_Current'. Use 'Census2020_Current' when you need boundaries as drawn at the 2020 Census, e.g. before a later congressional redistricting.	Current_Current
`addresses`	Yes	One or more one-line US addresses to geocode, e.g. ['1600 Amphitheatre Pkwy, Mountain View, CA 94043']. The Census parser is tolerant of punctuation but wants at least a street, a city and a state. Each address returns exactly one result row, matched or not.
`benchmark`	No	Which Census address file to match against. Defaults to 'Public_AR_Current', the live, continuously updated file. Use 'Public_AR_Census2020' to reconcile against the address file as it stood at the 2020 Census.	Public_AR_Current
`max_results`	No	Ceiling on the number of address rows you are willing to pay for. Defaults to 10. This Actor emits exactly one row per address (matched or not) and does not truncate your address list to this number, so keep 'addresses' at or below max_results to control both output volume and cost.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`run`	No
`error`	No
`status`	Yes
`results`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed82 schema fields changedv1.1.0Sep 15, 2026

addedInput schema / additionalProperties
```
Added value: +false
```
addedInput schema / properties / addresses / maxItems
```
Added value: +100
```
addedOutput schema / properties / error
```
Added value: +{
+  "type": "object"
+}
```

removedOutput schema / properties / results / description

Removed value: -"One geocoded row per input address, in input order, including addresses that failed to match."

changedOutput schema / properties / results / items / properties / benchmark_name / description

Previous value: -"The Census address benchmark that actually answered, echoed back by the API on every row."New value: +"The Census address benchmark that actually answered, echoed back by the API. Recorded per row so exports made weeks apart stay comparable after the Bureau rolls the benchmark forward."

addedOutput schema / properties / results / items / properties / benchmark_name / title
```
Added value: +"Benchmark used"
```
changedOutput schema / properties / results / items / properties / benchmark_name / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / block_geoid / description

Previous value: -"Fifteen-digit census block GEOID, the finest geography the Bureau publishes and the join key to decennial block data. Null when matched is false."New value: +"Fifteen-digit block GEOID: state (2) plus county (3) plus tract (6) plus block (4). The block is the finest geography the Bureau publishes and the join key to decennial block data. Null when matched is false."

addedOutput schema / properties / results / items / properties / block_geoid / title
```
Added value: +"Census block GEOID"
```
changedOutput schema / properties / results / items / properties / block_geoid / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / block_group_geoid / description

Previous value: -"Twelve-digit block group GEOID, the finest geography the American Community Survey publishes estimates for. Null when matched is false."New value: +"Twelve-digit block group GEOID: state (2) plus county (3) plus tract (6) plus block group (1). This is the finest geography the American Community Survey publishes estimates for - the block below it only carries decennial counts - so for income, housing or commute data this is the join key you actually want. Null when matched is false."

addedOutput schema / properties / results / items / properties / block_group_geoid / title
```
Added value: +"Block group GEOID"
```
changedOutput schema / properties / results / items / properties / block_group_geoid / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / cbsa_name / description

Previous value: -"Combined Statistical Area name, broader than the single metro area inside it (e.g. Washington joined with Baltimore). Null outside any CSA and when matched is false."New value: +"Name of the Combined Statistical Area containing the address. Despite the field name this is the Combined Statistical Areas layer, which is broader than the single CBSA metro area inside it, so Washington comes back joined with Baltimore. Null for addresses outside any CSA. Null when matched is false."

addedOutput schema / properties / results / items / properties / cbsa_name / title
```
Added value: +"Combined statistical area"
```
changedOutput schema / properties / results / items / properties / cbsa_name / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / city / description

Previous value: -"Postal city of the matched address, upper case. Can differ from place_name, the legally incorporated place. Null when matched is false."New value: +"Postal city of the matched address, upper case. This is the mailing city and can differ from place_name, which is the legally incorporated place. Null when matched is false."

addedOutput schema / properties / results / items / properties / city / title
```
Added value: +"City"
```
changedOutput schema / properties / results / items / properties / city / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / congressional_district_geoid / description

Previous value: -"Four-digit congressional district GEOID (state FIPS plus district), unique nationally and the join key to district-level Census tables. Null when matched is false."New value: +"Four-digit congressional district GEOID: state FIPS (2) plus district (2). Unlike congressional_district, which is a bare number repeated in every state, this is unique nationally and is the join key to district-level Census tables. Null when matched is false."

addedOutput schema / properties / results / items / properties / congressional_district_geoid / title
```
Added value: +"Congressional district GEOID"
```
changedOutput schema / properties / results / items / properties / congressional_district_geoid / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / county_fips / description

Previous value: -"Five-digit county GEOID (state FIPS plus county code), the county key used by ACS, BLS and most federal datasets. Null when matched is false."New value: +"Five-digit county GEOID: the two-digit state FIPS followed by the three-digit county code. This is the county key used by the American Community Survey, BLS and most other federal datasets. Null when matched is false."

addedOutput schema / properties / results / items / properties / county_fips / title
```
Added value: +"County FIPS code (GEOID)"
```
changedOutput schema / properties / results / items / properties / county_fips / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / county_name / description

Previous value: -"County or county-equivalent name (parish, borough, independent city). Null when matched is false."New value: +"County or county-equivalent name (parish, borough, independent city), without the trailing word County. Null when matched is false."

addedOutput schema / properties / results / items / properties / county_name / title
```
Added value: +"County name"
```
changedOutput schema / properties / results / items / properties / county_name / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / input_address / description

Previous value: -"The address string exactly as supplied, so results can be joined back to the source list."New value: +"The address string exactly as you supplied it, so results can be joined straight back to your source list. Rows come back in input order, one per address, including the ones that did not match."

addedOutput schema / properties / results / items / properties / input_address / title
```
Added value: +"Input address"
```
changedOutput schema / properties / results / items / properties / input_address / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / latitude / description

Previous value: -"Latitude in decimal degrees, interpolated along the matched TIGER street segment (street frontage, not rooftop). Null when matched is false."New value: +"Latitude in decimal degrees. Census interpolates the point along the matched TIGER street segment, so it lands on the street frontage rather than on the rooftop or the parcel centroid. Null when matched is false."

addedOutput schema / properties / results / items / properties / latitude / title
```
Added value: +"Latitude"
```
changedOutput schema / properties / results / items / properties / latitude / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / longitude / description

Previous value: -"Longitude in decimal degrees, same street-segment interpolation as latitude. Null when matched is false."New value: +"Longitude in decimal degrees, negative across the United States. Same street-segment interpolation as latitude. Null when matched is false."

addedOutput schema / properties / results / items / properties / longitude / title
```
Added value: +"Longitude"
```
changedOutput schema / properties / results / items / properties / longitude / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / match_count / description

Previous value: -"How many candidate addresses Census returned. 1 is a clean hit; more than 1 means the address was ambiguous and the row describes only the first candidate. 0 on unmatched rows."New value: +"How many candidate addresses Census returned for this input. 1 is a clean hit. Anything above 1 means the address was ambiguous and the row describes only the first candidate - '1 Main St, Springfield, MA' returns 3. 0 on rows that did not match. Use it to quarantine addresses a human should re-check."

addedOutput schema / properties / results / items / properties / match_count / title
```
Added value: +"Number of candidate matches"
```
changedOutput schema / properties / results / items / properties / match_count / type
```
Previous value: -"integer"New value: +[
+  "integer",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / matched / description

Previous value: -"True when the Census geocoder returned at least one candidate for the address. False rows carry every other field as null rather than being dropped."New value: +"True when the Census geocoder returned at least one candidate for the address. False rows are still written to the dataset, with every other field null, so a bad address is visibly different from a lost one."

addedOutput schema / properties / results / items / properties / matched / title
```
Added value: +"Match found"
```
changedOutput schema / properties / results / items / properties / matched / type
```
Previous value: -"boolean"New value: +[
+  "boolean",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / matched_address / description

Previous value: -"The address as Census standardised it: upper case, standardised street type, and the ZIP it actually resolved to. Null when matched is false."New value: +"The address as Census normalised it: upper case, standardised street type, and the ZIP it actually resolved to. Use this rather than your input when de-duplicating. Null when matched is false."

addedOutput schema / properties / results / items / properties / matched_address / title
```
Added value: +"Standardised address"
```
changedOutput schema / properties / results / items / properties / matched_address / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / metro_area_name / description

Previous value: -"Name of the Core Based Statistical Area (the actual metro or micro area) containing the address. Null outside any CBSA and when matched is false."New value: +"Name of the Core Based Statistical Area containing the address - the actual metro area, distinct from the broader cbsa_name column, which despite its name carries the Combined Statistical Area that can bundle several metros together. Rural addresses return their micropolitan area here instead. Null outside any CBSA and when matched is false."

addedOutput schema / properties / results / items / properties / metro_area_name / title
```
Added value: +"Metro or micro area (CBSA)"
```
changedOutput schema / properties / results / items / properties / metro_area_name / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / place_geoid / description

Previous value: -"Seven-digit place GEOID, the join key to Census place-level tables since place names repeat across states. Null when matched is false."New value: +"Seven-digit place GEOID: state (2) plus place (5). Join key to Census place-level tables. Place names repeat across states, so join on this rather than place_name. Null in unincorporated territory and when matched is false."

addedOutput schema / properties / results / items / properties / place_geoid / title
```
Added value: +"Incorporated place GEOID"
```
changedOutput schema / properties / results / items / properties / place_geoid / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / place_name / description

Previous value: -"Name of the incorporated place (city, town, village) containing the address. Null in unincorporated territory and when matched is false."New value: +"Name of the incorporated place (city, town, village) containing the address, from the Census Places layer. It can differ from the postal city, and it is null for addresses in unincorporated territory. Null when matched is false."

addedOutput schema / properties / results / items / properties / place_name / title
```
Added value: +"Incorporated place"
```
changedOutput schema / properties / results / items / properties / place_name / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / school_district_name / description

Previous value: -"Name of the school district containing the address; a unified district where one exists, otherwise the elementary or secondary district per school_district_type. Null when matched is false."New value: +"Name of the school district containing the address. Unified districts are reported where they exist; in states that split schooling, the elementary district is reported and school_district_type says which. The single strongest predictor in US residential property pricing, and normally only obtainable one state at a time. Null when matched is false."

addedOutput schema / properties / results / items / properties / school_district_name / title
```
Added value: +"School district"
```
changedOutput schema / properties / results / items / properties / school_district_name / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```
addedOutput schema / properties / results / items / properties / state / title
```
Added value: +"State"
```
changedOutput schema / properties / results / items / properties / state / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / state_fips / description

Previous value: -"Two-digit state FIPS code, the first component of every Census GEOID. Null when matched is false."New value: +"Two-digit state FIPS code, 11 for the District of Columbia and 36 for New York. It is the first component of every Census GEOID and the join key to state-level Census tables. Null when matched is false."

addedOutput schema / properties / results / items / properties / state_fips / title
```
Added value: +"State FIPS code"
```
changedOutput schema / properties / results / items / properties / state_fips / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / tract_geoid / description

Previous value: -"Eleven-digit census tract GEOID, the join key for American Community Survey tract tables. Null when matched is false."New value: +"Eleven-digit tract GEOID: state (2) plus county (3) plus tract (6). This is the join key for American Community Survey tract tables and for almost every tract-level demographic product. Null when matched is false."

addedOutput schema / properties / results / items / properties / tract_geoid / title
```
Added value: +"Census tract GEOID"
```
changedOutput schema / properties / results / items / properties / tract_geoid / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / urban_rural / description

Previous value: -"Census urban/rural classification of the containing block: U for urban, R for rural. Null when matched is false."New value: +"Census urban/rural classification of the containing block: U for urban, R for rural. This is the Bureau's own definition, not a population guess, and it is the standard filter for rural-eligibility programmes such as USDA lending. Null when matched is false."

addedOutput schema / properties / results / items / properties / urban_rural / title
```
Added value: +"Urban or rural"
```
changedOutput schema / properties / results / items / properties / urban_rural / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / vintage_name / description

Previous value: -"The geography vintage that actually answered, echoed back by the API on every row."New value: +"The geography vintage that actually answered, echoed back by the API. Tract and block boundaries are redrawn between vintages, so two rows with the same tract_geoid only describe the same ground when this column agrees."

addedOutput schema / properties / results / items / properties / vintage_name / title
```
Added value: +"Geography vintage used"
```
changedOutput schema / properties / results / items / properties / vintage_name / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / zcta / description

Previous value: -"Five-digit ZIP Code Tabulation Area containing the point, the only ZIP-shaped geography the Bureau actually publishes data for. Can differ from zip. Null when matched is false."New value: +"Five-digit ZCTA containing the point. A ZCTA is the Census areal approximation of a ZIP code and is the only ZIP-shaped geography the Bureau publishes data for; it often differs from the mailing zip, as the White House shows with ZIP 20500 inside ZCTA 20006. Join demographic data on this, mail on zip. Null when matched is false."

addedOutput schema / properties / results / items / properties / zcta / title
```
Added value: +"ZIP Code Tabulation Area"
```
changedOutput schema / properties / results / items / properties / zcta / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / results / items / properties / zip / description

Previous value: -"Five-digit ZIP code Census resolved the address to, kept as a string so leading zeros survive export. Null when matched is false."New value: +"Five-digit ZIP code Census resolved the address to, which is not always the ZIP you submitted. Kept as a string so leading zeros survive export to CSV or Excel. Null when matched is false."

addedOutput schema / properties / results / items / properties / zip / title
```
Added value: +"ZIP code"
```
changedOutput schema / properties / results / items / properties / zip / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / results / items / required

Removed value: -[
-  "input_address",
-  "matched",
-  "match_count"
-]

addedOutput schema / properties / run
```
Added value: +{
+  "type": "object"
+}
```

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "success",
+    "empty_unverified",
+    "partial",
+    "error"
+  ],
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "results"
-]New value: +[
+  "results",
+  "status"
+]

Addedv1.0.11Sep 13, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description includes a dedicated Behavioral Transparency section detailing execution (network call, Apify Actor), side effects (billed run, dataset creation), authentication (APIFY_TOKEN), latency/limits (5 addresses per batch, 60s timeout, 10-60s typical), and output behavior (one row per address). This significantly enriches the annotations (readOnlyHint, destructiveHint) by explaining billing, timeout, and output volume without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, behavioral transparency, usage guidelines). Every sentence serves a purpose: it starts with the core value proposition, then addresses operational details and routing. It is long but not verbose, with no filler or redundant statements.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (network call, billing, enums, latency), the description covers all essential aspects: what it does, when to use it, side effects, authentication, limits, and output behavior. The presence of an output schema means return format details are handled structurally, so the description is complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters with clear descriptions, including the enums and their meanings. The description reiterates key points about max_results and output volume, but adds no new information beyond what the schema provides. Per the rubric, a baseline of 3 is appropriate when the schema fully covers parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('geocode'), resource ('US street addresses'), and the exact output ('full Census Bureau geography... FIPS, GEOIDs, etc.'). It explicitly distinguishes from 'just a pin' and lists the specific geography attributes, making the tool's purpose unmistakable and clearly separate from any sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description contains explicit 'When to use' and 'When NOT to use' sections, with named alternatives ('us_business_entity_search' and 'us_contractor_license_search'). It also clarifies exclusions like interactive place search and non-US addresses, leaving no ambiguity about when to select this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.