Preview

API Documentation

This is a preview of our API documentation. Full docs with authentication, rate limits, and complete endpoint reference coming soon.

Overview

The CensusAPI provides semantic access to U.S. Census and American Community Survey (ACS) data. Instead of raw variable codes, you request named metrics and receive computed, documented values with optional time-series trends.

RESTful

Clean, predictable URL patterns

Semantic

Human-readable metric names

Fast

Pre-computed, edge-cached

Authentication

Authenticate requests using an API key in the header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.censusapi.dev/v1/geo/zcta/60004/metrics/median_household_income

Note: API keys will be issued during early access. Free tier includes 1,000 requests/month.

Base URL

https://api.censusapi.dev/v1

GET

Get Metric

Retrieve a single metric value for a specific geography. Returns the latest available data (typically the most recent ACS 5-year release).

Endpoint

GET /v1/geo/{geo_type}/{geo_id}/metrics/{metric_name}

Path Parameters

Parameter	Type	Description
geo_type	string	One of: `state`, `county`, `tract`, `zcta`
geo_id	string	FIPS code or ZCTA code (e.g., "17" for Illinois, "17031" for Cook County, "60004" for ZCTA)
metric_name	string	Semantic metric name (e.g., `median_household_income`, `pct_worked_from_home`)

Example Request

Request

GET /v1/geo/zcta/60004/metrics/median_household_income

Example Response

Response

{
  "metric": "median_household_income",
  "label": "Median Household Income",
  "geo_type": "zcta",
  "geo_id": "60004",
  "geo_name": "ZCTA 60004 (Arlington Heights, IL area)",
  "year": 2023,
  "value": 112500,
  "unit": "USD",
  "moe": 4200,
  "moe_pct": 3.7,
  "confidence": "high",
  "source": {
    "dataset": "ACS 5-Year Estimates",
    "table": "B19013",
    "variable": "B19013_001E",
    "vintage": "2023"
  },
  "retrieved_at": "2026-01-26T12:00:00Z"
}

GET

Get Metric with Trend

Same endpoint, add the trend query parameter to include historical values and computed changes.

Query Parameters

Parameter	Type	Description
trend	string	One of: `5y`, `10y`. Includes prior period values and change calculations.

Example Request

Request

GET /v1/geo/zcta/60004/metrics/pct_worked_from_home?trend=10y

Example Response

Response

{
  "metric": "pct_worked_from_home",
  "label": "Percent Worked From Home",
  "geo_type": "zcta",
  "geo_id": "60004",
  "geo_name": "ZCTA 60004 (Arlington Heights, IL area)",
  "year": 2023,
  "value": 0.133,
  "unit": "ratio",
  "display_value": "13.3%",
  "moe": 0.012,
  "confidence": "high",
  "trend": {
    "period": "10y",
    "prior_5y": {
      "year": 2018,
      "value": 0.092,
      "display_value": "9.2%"
    },
    "prior_10y": {
      "year": 2013,
      "value": 0.056,
      "display_value": "5.6%"
    },
    "change_5y_pp": 0.041,
    "change_10y_pp": 0.077,
    "change_5y_pct": 44.6,
    "change_10y_pct": 137.5
  },
  "source": {
    "dataset": "ACS 5-Year Estimates",
    "table": "B08301",
    "variables": ["B08301_001E", "B08301_021E"],
    "formula": "B08301_021E / B08301_001E",
    "vintage": "2023"
  },
  "notes": "ZCTA boundary stable across comparison period",
  "retrieved_at": "2026-01-26T12:00:00Z"
}

GET

List Available Metrics

Discover all available metrics and their definitions.

Example Request

Request

GET /v1/metrics

Example Response (truncated)

Response

{
  "metrics": [
    {
      "name": "median_household_income",
      "label": "Median Household Income",
      "category": "affordability",
      "unit": "USD",
      "description": "Median income for all households in the geography",
      "source_table": "B19013"
    },
    {
      "name": "pct_worked_from_home",
      "label": "Percent Worked From Home",
      "category": "commuting",
      "unit": "ratio",
      "description": "Share of workers 16+ who work from home",
      "source_table": "B08301"
    },
    {
      "name": "median_home_value",
      "label": "Median Home Value",
      "category": "housing",
      "unit": "USD",
      "description": "Median value for owner-occupied housing units",
      "source_table": "B25077"
    }
  ],
  "total": 52
}

GET

Batch Metrics

Request multiple metrics for a geography in a single call.

Example Request

Request

GET /v1/geo/county/17031/metrics?include=median_household_income,pct_worked_from_home,vacancy_rate

Example Response

Response

{
  "geo_type": "county",
  "geo_id": "17031",
  "geo_name": "Cook County, IL",
  "year": 2023,
  "metrics": {
    "median_household_income": {
      "value": 72500,
      "unit": "USD",
      "moe": 850,
      "confidence": "high"
    },
    "pct_worked_from_home": {
      "value": 0.187,
      "unit": "ratio",
      "display_value": "18.7%",
      "moe": 0.004,
      "confidence": "high"
    },
    "vacancy_rate": {
      "value": 0.098,
      "unit": "ratio",
      "display_value": "9.8%",
      "moe": 0.005,
      "confidence": "high"
    }
  },
  "retrieved_at": "2026-01-26T12:00:00Z"
}

Supported Geographies

Type	Code Format	Example	Count
state	2-digit FIPS	`17` (Illinois)	52
county	5-digit FIPS	`17031` (Cook County)	~3,200
tract	11-digit FIPS	`17031081700`	~85,000
zcta	5-digit ZCTA	`60004`	~33,000

Note: ZCTAs (ZIP Code Tabulation Areas) are Census-defined approximations of USPS ZIP codes. You can query using ZIP codes and we'll map to the corresponding ZCTA.

Error Codes

Code	Meaning
400	Bad request (invalid parameters)
401	Unauthorized (missing or invalid API key)
404	Geography or metric not found
429	Rate limit exceeded
500	Internal server error

Ready to try it?

Request early access to get your API key and start building.

Request Early Access