# ZIP Code Demographics: Census Income, Age, Home Value by ZIP (`transparent_meteorite/zip-code-demographics-acs`) Actor

Census ACS 5-year demographics for any US ZIP code list, state or radius: income, age, education, home value, rent, race, jobs, commute, internet. Adds US percentiles, an affluence index and state/US comparison. One row per ZIP.

- **URL**: https://apify.com/transparent_meteorite/zip-code-demographics-acs.md
- **Developed by:** [Detroit Web Agent - Open Data](https://apify.com/transparent_meteorite) (community)
- **Categories:** Real estate, Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.47 / 1,000 zip profile delivereds

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

## ZIP Code Demographics: Census Income, Age, Home Value by ZIP

### What does this actor do?

It turns US ZIP codes into clean, analysis-ready demographic profiles built from the U.S. Census Bureau's **American Community Survey (ACS) 5-year estimates**, the most detailed small-area data the Census publishes. Give it a list of ZIP codes, one or more whole states, or a radius around a ZIP, and you get **one row per ZIP** with population, age, income, poverty, education, housing, home values, rent, race and ethnicity, jobs, commute and internet access.

Each row also gets context that raw Census tables do not give you:

- **US percentiles**: where the ZIP ranks among all ~31,500 US ZIP areas with 100+ residents, for income, per-capita income, home value, education, poverty, population and density.
- **Affluence index (0-100)** and a tier (very high to very low), so you can rank and filter ZIPs with one number.
- **State and US comparison**: the same key metrics for the ZIP's state and the whole country, plus a simple index (100 = equal).
- **Place, county and state names**, the internal point (lat/lon), land area and density.
- **Margins of error** for the headline medians and a **dataReliability** flag, so small ZIPs are not over-trusted.

No Census API key or Census know-how is needed: variable codes, the 50-variable-per-call limit, suppressed values and top codes are handled for you.

### Features

- Three ways to pick ZIPs: a list (ZIP+4 accepted), whole states (or ALL for every US ZIP, about 33,000 rows), or every ZIP within N miles of a center ZIP.
- Latest ACS 5-year release found automatically (currently 2024, the 2020-2024 estimates), or pick a release from 2020 on.
- Variable groups (population, income, education, housing, race and ethnicity, employment, internet) to keep rows focused.
- Census sentinel values (like -666666666) become null; top-coded medians (for example $250,001+ income) are listed in `topCodedFields`.
- ZIPs with no Census data (PO-box or single-business ZIPs) are listed in the run summary and never charged.

### Use cases

- **Local marketing and franchising**: score every ZIP within 25 miles of a location by income, home value, owner-occupied share and affluence, then target mailers, door hangers and ads at the top ZIPs.
- **Real-estate screening**: pull median rent, home value, vacancy and renter share for a state's ZIPs and join them to listing or permit data by ZIP.
- **Lead and CRM enrichment**: add ZIP-level income, education, age and internet access to a customer list so segments and lead scores reflect the neighborhood.
- **Site selection and market sizing**: count households with $100k+ income around candidate sites and compare each ZIP with its state and the US.
- **Automation**: call it from n8n, Make, Zapier or the Apify API whenever a new lead arrives with a ZIP code.

### Input

| Field | What it does |
|---|---|
| `zipCodes` | List of 5-digit ZIP codes (ZIP+4 is fine). |
| `states` | Two-letter codes (MI, TX, PR) for every ZIP in those states, or ALL. |
| `radiusCenterZip` + `radiusMiles` | Every ZIP whose center lies within the radius (default 10 miles). |
| `acsYear` | latest (default) or a release year from 2020 on. |
| `variableGroups` | Topics to include; empty = all. |
| `compareToStateAndUs` | Add the state and US comparison object (default on). |
| `usPercentiles` | Add US percentiles and the affluence index (default on). |
| `minPopulation` | Skip ZIPs below this population (default 1). |
| `sortBy` | input, zip, population, affluenceIndex, medianHouseholdIncome or distance. |
| `maxZips` | Cap on rows delivered and charged. |
| `censusApiKey` | Optional, your own free Census key; otherwise the built-in key is used. |

Selectors combine as a union. Example input:

```json
{
  "radiusCenterZip": "48226",
  "radiusMiles": 15,
  "sortBy": "distance",
  "compareToStateAndUs": true
}
```

### Output

One dataset row per ZIP with 72 fields. Table views: **ZIP profiles**, **Market sizing and affluence**, **Housing**, and **People, jobs and internet**. Export as JSON, CSV, Excel or via the API. A run summary (ACS release used, ZIPs not found, rows skipped, percentile basis) is saved as the `OUTPUT` record.

#### Sample output (shortened, real 2020-2024 data for downtown Detroit)

```json
{
  "zip": "48226",
  "place": "Detroit",
  "county": "Wayne County",
  "state": "Michigan",
  "stateCode": "MI",
  "population": 6831,
  "populationMoe": 669,
  "medianAge": 34,
  "households": 4350,
  "medianHouseholdIncome": 64860,
  "medianHouseholdIncomeMoe": 11143,
  "perCapitaIncome": 74154,
  "povertyRatePct": 17.2,
  "bachelorsOrHigherPct": 52.1,
  "ownerOccupiedPct": 6.3,
  "vacancyRatePct": 21.3,
  "medianHomeValue": 324500,
  "medianGrossRent": 1743,
  "unemploymentRatePct": 3,
  "meanCommuteMinutes": 18.3,
  "internetAccessPct": 93.5,
  "affluenceIndex": 63.3,
  "affluenceTier": "high",
  "medianHouseholdIncomeUsPercentile": 37.9,
  "bachelorsOrHigherUsPercentile": 89.1,
  "dataReliability": "good",
  "comparison": {
    "state": { "medianHouseholdIncome": 72875, "medianGrossRent": 1129 },
    "us": { "medianHouseholdIncome": 80734, "medianGrossRent": 1413 },
    "zipVsStateIndex": { "medianHouseholdIncome": 89, "medianGrossRent": 154 }
  },
  "acsYear": 2024,
  "acsVintage": "2020-2024",
  "dataset": "American Community Survey 5-Year Estimates, detailed tables (acs/acs5)",
  "source": "U.S. Census Bureau",
  "censusProfileUrl": "https://data.census.gov/profile/ZCTA5_48226?g=860XX00US48226"
}
```

### Pricing and cost

Pay per event: **$0.00047 per ZIP profile delivered**, plus a tiny actor start fee. 100 ZIPs cost about $0.05; every US ZIP (about 33,000 rows) costs about $15.51. ZIPs that are not found, have no data or fall below `minPopulation` are never charged, and a run that matches no ZIPs stops before calling the Census API. Set `maxZips` or a spending limit on the run to cap cost.

### Use with the API, n8n, Make, Zapier or AI agents

**API** (one call, returns the rows as JSON):

```bash
curl -X POST "https://api.apify.com/v2/acts/transparent_meteorite~zip-code-demographics-acs/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zipCodes":["48201","48226","48009","10001","10021","11211","90210","90011","94110","60614","60621","78701","77002","33139","30303","98109","02116","19104","85004","80202","37203","70116","55401","97209","20001","84101","96815","99501"],"compareToStateAndUs":true,"usPercentiles":true,"sortBy":"input"}'
```

The call waits up to 5 minutes. For bigger inputs, start the run with `/runs` instead and read the dataset when it finishes.

**Python**

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("transparent_meteorite/zip-code-demographics-acs").call(run_input={"zipCodes": ["48201", "48226", "48009", "10001", "10021", "11211", "90210", "90011", "94110", "60614", "60621", "78701", "77002", "33139", "30303", "98109", "02116", "19104", "85004", "80202", "37203", "70116", "55401", "97209", "20001", "84101", "96815", "99501"], "compareToStateAndUs": True, "usPercentiles": True, "sortBy": "input"})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row)
```

- **n8n, Make, Zapier:** use the Apify app's "Run Actor" step with actor `transparent_meteorite/zip-code-demographics-acs`, paste the input JSON, then map the dataset items to your sheet or CRM.
- **Clay:** add an HTTP API column that calls the run-sync endpoint above.
- **Schedules:** in Apify Console, Schedules, run it daily or weekly with the same input for a steady feed.
- **AI agents (MCP):** connect the Apify MCP server at `https://mcp.apify.com?tools=transparent_meteorite/zip-code-demographics-acs` to Claude, Cursor or any MCP client, and your agent can run ZIP Code Demographics (ACS 5-Year) on request.

### FAQ

**Are these real ZIP codes?** The Census publishes data for ZIP Code Tabulation Areas (ZCTAs), which approximate USPS ZIP delivery areas. Almost every residential ZIP has one; PO-box-only and single-business ZIPs do not and are reported as not found.

**How current is the data?** ACS 5-year estimates pool five years of survey responses. The 2024 release covers 2020-2024. Dollar values are in that release's final-year dollars.

**How are state, county and city assigned?** From the Census 2020 ZCTA relationship files: the county holding the largest share of the ZIP's land, and the place covering the largest share (if at least 5%). ZIPs that cross lines report `countiesOverlapped`.

**What does the affluence index mean?** It is the mean of the ZIP's US percentiles for median household income, per-capita income, median home value and bachelor's-or-higher share, plus the inverse of its poverty percentile. 50 is a typical US ZIP.

**Can I use my own Census key?** Yes, put it in `censusApiKey`. It is stored encrypted and never logged.

### Limits

- Small ZIPs have wide margins of error; check `populationMoe`, the `*Moe` fields and `dataReliability` before drawing conclusions.
- ACS covers the 50 states, DC and Puerto Rico; other territories are not included.
- Medians at the ACS top code (for example $250,001 income or $2,000,001 home value) mean "at or above" and are listed in `topCodedFields`.
- Releases before 2020 use older ZCTA definitions and are not offered.

### Related actors

- Find businesses in the ZIPs you rank with [Local Business Leads](https://apify.com/transparent_meteorite/local-business-leads).
- Track new construction and renovation demand by area with [Building Permits Leads](https://apify.com/transparent_meteorite/building-permits-leads).
- Spot newly registered companies with [New Business Filings](https://apify.com/transparent_meteorite/new-business-filings).

### Data source and notice

Data: U.S. Census Bureau, American Community Survey 5-Year Estimates, via the Census Data API, and Census 2020 ZCTA relationship and Gazetteer files. This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.

Questions or a missing field? Open an issue on the actor's Issues tab.

# Actor input Schema

## `zipCodes` (type: `array`):

5-digit US ZIP codes (ZIP+4 is fine, the first 5 digits are used). Each becomes one row. ZIPs with no Census ZIP Code Tabulation Area (PO-box or single-business ZIPs) are listed in the run summary and never charged.

## `states` (type: `array`):

Two-letter state codes (MI, TX, PR ...). Every ZIP Code Tabulation Area in each state is returned (assigned by the county holding most of its land). Use ALL for every ZIP in the US (about 33,000 rows). Combined with the other selectors as a union.

## `radiusCenterZip` (type: `string`):

Return every ZIP whose Census center point lies within radiusMiles of this ZIP's center point. Rows get a distanceMiles field and are sorted nearest first.

## `radiusMiles` (type: `number`):

Radius in miles around radiusCenterZip (0.1 to 250). Ignored without a center ZIP.

## `acsYear` (type: `string`):

latest = the newest 5-year release the Census API serves (found automatically at run time; 2024 = the 2020-2024 estimates). Or pick a release year from 2020 on.

## `variableGroups` (type: `array`):

Topics to include. Population is always included. Leave empty for all. Fields of excluded groups are returned as null. The affluence index needs income, housing and education.

## `compareToStateAndUs` (type: `boolean`):

Add a comparison object with the same key metrics for the ZIP's state and the whole US, plus an index (100 = equal to the state or US value).

## `usPercentiles` (type: `boolean`):

Rank each ZIP against all US ZIP Code Tabulation Areas with 100+ residents (income, per-capita income, home value, education, poverty, population, density) and compute the 0-100 affluence index.

## `minPopulation` (type: `integer`):

Skip ZIPs with fewer residents than this (they are not charged). The default 1 skips uninhabited ZIP areas that have no data.

## `sortBy` (type: `string`):

Row order. input keeps your ZIP list order (radius-only runs default to distance).

## `maxZips` (type: `integer`):

Upper limit on rows delivered (and charged) in this run.

## `censusApiKey` (type: `string`):

Optional: your own free key from api.census.gov/data/key_signup.html. Leave empty to use the actor's built-in key. Stored encrypted and never logged.

## Actor input object example

```json
{
  "zipCodes": [
    "48201",
    "10001",
    "90210",
    "60614",
    "78701"
  ],
  "radiusMiles": 10,
  "acsYear": "latest",
  "compareToStateAndUs": true,
  "usPercentiles": true,
  "minPopulation": 1,
  "sortBy": "input",
  "maxZips": 50000
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `market` (type: `string`):

No description

## `allFields` (type: `string`):

No description

## `summary` (type: `string`):

No description

# 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 = {
    "zipCodes": [
        "48201",
        "10001",
        "90210",
        "60614",
        "78701"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("transparent_meteorite/zip-code-demographics-acs").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 = { "zipCodes": [
        "48201",
        "10001",
        "90210",
        "60614",
        "78701",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("transparent_meteorite/zip-code-demographics-acs").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 '{
  "zipCodes": [
    "48201",
    "10001",
    "90210",
    "60614",
    "78701"
  ]
}' |
apify call transparent_meteorite/zip-code-demographics-acs --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,transparent_meteorite/zip-code-demographics-acs"
        }
    }
}
```

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/Z6c88M4AUqnCb17tf/builds/BPY1sULgR3oCfXi6n/openapi.json
