Core Concepts

Before you write your first query, here's the mental model that makes the rest of the API make sense.

What Is ACS Data?

The American Community Survey (ACS) is a continuous survey run by the U.S. Census Bureau that collects detailed demographic, economic, and housing information. PrairieCloud serves two ACS products:

ACS 5-Year Estimates aggregate responses over a rolling 5-year window — for example, the 2024 vintage covers survey years 2020–2024. This pooling gives the data statistical reliability at small geographies (counties, metros) where a single year's sample would be too thin to trust. The tradeoff: ACS 5-Year data is not a snapshot of a single moment. It reflects conditions across the entire collection window, smoothed over time. For most analytical use cases — market sizing, site selection, policy research — this is the right dataset.

ACS 1-Year Estimates provide single-year snapshots for geographies with populations of 65,000 or more. These are more current but cover fewer areas. Use acs1 when you need the most recent year's data for states, large counties, or metros.

What PrairieCloud Does Differently

The raw Census API is powerful but rough. Variables are named things like B01001_001E. Geographies require FIPS codes buried in separate lookup tables. Error handling is inconsistent.

PrairieCloud is a translation layer on top of the Census Bureau's data. We normalize variable names to human-readable api_name identifiers (pop_total), standardize geography inputs into a single {type}:{fips} format, and return clean JSON with consistent error shapes. You get the same authoritative Census data without the archaeology. For a side-by-side code comparison, see how PrairieCloud compares to the raw Census Bureau API.

The Four Key Concepts

Datasets

A dataset identifies the Census product you're querying:

Dataset Key	Name	Geographies	Best For
acs5	ACS 5-Year Estimates	392,435 (7 geo levels)	Most reliable estimates, small-area data
acs1	ACS 1-Year Estimates	~1,700–1,900 (65K+ population)	Most current single-year data

Vintages

A vintage is the release year of the data. PrairieCloud serves extensive historical coverage:

Dataset	Vintages Available
acs5	2009–2024 (16 vintages)
acs1	2005–2024 (19 vintages, no 2020)

For ACS 5-Year, each vintage corresponds to a rolling 5-year collection window (e.g., vintage 2024 = survey years 2020–2024). When no vintage is specified, the API defaults to the most recent available.

Variable coverage varies by vintage

Not all 392 variables are available in every vintage. The Census Bureau restructures its tables between releases, so older vintages have fewer variables. See the Data Guide for the full coverage matrix.

Geographies

Geographies identify the place you're asking about. They follow the format {type}:{fips}:

• state:48 — Texas
• county:48201 — Harris County, TX
• tract:48201231400 — a specific census tract in Harris County

Use GET /v1/geographies to browse and search available geography types and FIPS codes.

Variables

Variables are the data fields you want — population counts, income figures, housing stats. PrairieCloud uses api_name identifiers instead of raw Census codes:

• pop_total
• income_median_household
• tenure_owner_occupied

Use GET /v1/variables to search the full catalog by keyword, topic, or dataset.

How They Fit Together

Every API call follows the same pattern: pick a dataset and vintage → specify one or more geographies → request variables.

GET /v1/data
  ?variables=pop_total,income_median_household
  &geo=state:48
  &vintage=2024
  &dataset=acs5

A Note on Margin of Error and Suppression

ACS estimates come with margins of error (MOE) — the API returns these alongside each estimate when available. For small geographies or small subpopulations, the Census Bureau sometimes suppresses values entirely when the estimate would be unreliable. Suppressed values appear as null in API responses, not as zeros.

---

Next Steps

• Quickstart — Make your first API call in 5 minutes
• Data Guide — Deep dive into datasets, vintages, geography types, and FIPS codes
• API Keys — Learn about API key management and security best practices
• Python Examples — See full code examples in Python
• JavaScript Examples — See full code examples in JavaScript