Using the Census Data API

Three ways into the Census Bureau, and what the catalog reveals about who the data is for

Democracy’s Data

Last updated September 15, 2026 at 4:42p EDT

The Census Bureau publishes its data free, to everyone. That is the standard boast about federal statistics, and it is true. It is also unfinished, because published is not the same as reachable, and reachable depends on which of three doors you walk through.

Door What it is Needs a key Can you automate it
data.census.gov the website: search, click, download no not really
www2.census.gov the published files, exactly as released no yes, if you can parse the format
the API a URL that returns data yes yes — that is the point

All three doors return the same published counts, and which one you use decides what you can do. Only one door is built for a program: the API, short for application programming interface — an address a program can ask for a table at, instead of a person clicking through a website, and which answers with the numbers themselves rather than a page to read. It is also the only door that asks who you are. Since 2026, asking it for a number without a registered key — a free, password-like code the Bureau issues to anyone who gives a name and an email address — returns nothing.

The gate matters because some questions cannot be asked by hand. A person can click through fifty counties on the website. Nobody can click through eight million census blocks, the smallest areas the Bureau publishes counts for, often a single city block — and blocks are the unit district maps are drawn from. So the practical capacity to check a redistricting plan lives behind the door that wants a name and an email address.

That raises the question this brief answers. The Bureau publishes everything, so who is the publication actually built for — the curious citizen, or somebody else? The answer turns out to be readable from an unlikely piece of evidence: the API’s own table of contents, the half of the service that still answers anybody.

The test

The evidence is the two catalog files the Bureau publishes about the API itself — it calls them metadata, data about the data — at open addresses listed at api.census.gov, as they stood in August 2026. One lists every variable, meaning every published column, of the 2020 census redistricting release. The other lists every geographic level the service will answer for. Neither needs a key, and neither is a sample: a catalog either lists a column or it does not, so the count of what the census measures is settled outright.

Why this product, out of everything the Bureau serves? Because the redistricting release is the census at its most obligatory. A 1975 law, Public Law 94-171, requires the Bureau to hand every state the small-area counts it needs to redraw its districts, on a deadline.1 Nothing requires the Bureau to run an API at all; that is a service it chose to build and could withdraw. So the catalog is a voluntary description of a compulsory product, and reading it closely reads the law rather than the agency’s taste. What a census can and cannot do introduces the census itself; this brief reads its table of contents.

A catalog is also the right instrument for a question about who the data is for. If the columns exist out of curiosity, the list should read like an encyclopedia. If they exist out of obligation, the obligations should be visible in its shape.

The data

api_variables.csv holds one row for each of the 338 columns the 2020 redistricting release publishes. Three columns are kept from the Bureau’s file: variable (the code a query would name), label (where the column sits inside its table), and concept (the table’s full name). api_geography.csv holds one row for each of the 96 geographic levels the same service will serve those columns at, with a numeric level code and a name.

Both come from the Bureau’s open catalog addresses, which need no key, and the Bureau’s files are kept beside the two CSVs (comma-separated values: plain-text tables any spreadsheet opens) exactly as published, so anyone can compare. Nothing was dropped and nothing was renamed. No population count was requested, and no key exists anywhere in this brief.

Two construction decisions are worth knowing about. The label field arrives as a table position flattened into one line of text, with !! marking the levels, and it is kept exactly as sent; everything below about hierarchy is recovered by splitting that line. And each geography row lost one field on the way to CSV — the one saying what a query at that level requires you to name first. For how far down the hierarchy goes, which is this brief’s question, the loss is harmless. For anybody actually requesting eight million blocks it was the field that mattered, and it is still waiting in the raw file.

Before you read on, commit to two numbers. Once the geographic identifiers are set aside, six tables carry the 301 substantive variables the 2020 census published — the counts of people and housing. How many of those 301 do you think are a table published a second time, rather than a distinct fact about anybody? Write down a count, or a share of 301. Then a second guess: of the 96 rows in the geography file, how many name a genuinely different level of geography?

What it says about democracy

The name of the thing is not the thing

The catalog’s first lesson fits in a single row.

Variable What it counts Which table it belongs to
P1_003N > Total: > Population of one race: > White alone RACE

The !! are nesting. P1_003N is Total > Population of one race > White alone — the number you would casually call “the white population.” It sits three levels down a hierarchy and excludes everyone who ticked two boxes. The name of the thing is not the thing, and no column announces the difference. A researcher who writes down P1_003N as “white population” has made a substantive claim about multiracial Americans without noticing.

Figure 1. Table P1 as a tree, 4 levels deep and 63 bottom-level categories wide. The label strings are a hierarchy flattened for transport, so the honest way to draw them is to unflatten them. Each block is one published column, and a block’s width is the number of bottom-level categories beneath it. The red block is P1_003N, “White alone,” 3 levels down — one single-race category under a branch that excludes everyone who ticked two boxes, and the orange branch beside it is where those people went.

Nearly half the substantive file is one statute

At first reading the catalog looks enormous: 338 variables, served at 96 geographic levels. But 37 of those rows are not data at all — they are the names of geographies you may filter on, plus the API’s own query keywords. Strip them and the whole 2020 census fits in six tables.

Table Variables What it holds
P2 73 Hispanic origin crossed with race
P4 73 Hispanic origin crossed with race, adults only
P1 71 race
P3 71 race, adults only
P5 10 group quarters
H1 3 occupied and vacant housing units

Two of those tables are copies, and the claim can be checked directly. Count how many label strings each pair of tables has in common:

Figure 2. Two tables in six are the same table. Each cell counts the label strings two tables share, because identical wording is the test of a republished table. Off the diagonal almost every pair shares exactly one, the row called “Total,” which every table has. The two red cells are the exceptions: P1 and P3 share 71 labels, and P2 and P4 share 73 — every row of both tables, down to the wording.

Quantity Value
Substantive variables 301
of which restricted to the population 18 years and over 144
Share of the substantive file that is an adults-only twin 48%

Most readers put the duplication somewhere around a tenth, on the reasonable assumption that a statistical agency does not publish the same table twice. 144 of the 301 substantive variables are duplicates, or 48%. P3 is P1 restricted to adults, and P4 is P2 restricted to adults. Nobody was asked a second time; the Bureau ran the same cross-tabulations — the same counts of race by Hispanic origin — twice, once for everybody and once for adults, and published both.

That is not redundancy. The Voting Rights Act is about voters, and voters are adults. A vote-dilution claim under the Act’s Section 22 — a claim that a district map, without barring anyone from the polls, still leaves a minority group unable to elect anyone — turns on whether that group is numerous enough to form a majority in a district, and the population that matters is voting-age.3 Without P3 and P4, the central quantity in American voting-rights litigation could not be computed from the census at all. Nearly half the substantive file exists because of a law, and you can read the law off the column list.

The geography file is mostly bookkeeping, and partly the states

The same move works on the geography file.

Quantity Value
Rows in the geography file 96
Rows that are ‘(or part)’ fragments of a level already listed 67
Distinct geographic levels 29
of which sit below the county 7

96 rows collapse to 29 distinct levels. The other 67 are the same levels again, sliced by whatever larger unit they happen to straddle, as “county (or part)”, because most American boundaries refuse to nest inside each other. 7 of the 29 levels sit below the county, and one of them is voting district: a precinct, the small area whose voters all report to the same polling place.

That row is the point of the whole file. The Bureau publishes population inside precinct lines, which is exactly the join a voting-rights analysis needs. The government publishes the data required to challenge the maps that governments draw, and a statute arranged it that way on purpose.

With one qualification, and it is the most surprising fact here. The Bureau does not know where a precinct is unless a state tells it, because precinct lines are state and county creations. Before each census the states are invited to submit their voting districts for inclusion in the file, and the submission is voluntary.4 A state that took part gets population totals inside its precincts. A state that did not, does not. So parts of this compulsory product were supplied voluntarily, by the same states whose maps the file is used to challenge.

What the catalog is made of

Hover a bar for the exact count.

Figure 3. Every row of the variables file, in three groups. One bar per group, because the only question is how big each group is. 37 rows are geographic identifiers and query keywords, not counts of anybody, and 144 are the adults-only twins of tables already published. The remaining 157 are the census itself: race, Hispanic origin, group quarters and housing occupancy, for everyone. The middle bar is the finding. A catalog that looks like an inventory of curiosity is, by row count, closer to an inventory of legal obligation.

The open half answers anybody; the locked half answers politely

Ask the API what exists, at the two addresses under Sources, and it answers instantly, to anyone. Ask it for an actual number without a key and, since 2026, the answer is a web page reading Missing Key. So the information about how American democracy is measured is entirely public, while the measurements themselves sit behind a registration.

The way the door is locked deserves a sentence of its own. A keyless request does not get an error code or broken data; it gets a valid page, which a program will happily read and carry along. The failure is silent and surfaces later, in a table of blanks nobody questions. A locked door that answers politely is worse than one that says no, and answering with a proper error instead would cost the Bureau nothing.

A key is free and arrives by email in about a minute. It is also a password: it identifies you, and it does not belong in any file you share. That is not hypothetical — a live Census API key once sat in plain text in a teaching handout for a year, and had to be flagged for revocation.

Should public data require registration at all? The Bureau’s answer is operational: a key lets it cap how many requests one user can make in a day and trace anyone abusing the service,5 and the catalog stays open precisely so discovery is unimpeded. The objection is that the gate falls on the automatable door and leaves casual lookup untouched. So it burdens exactly the systematic checking the file exists to make possible: the redistricting plan, the lending pattern. Both descriptions are accurate. What the catalog adds is a fact about who carries the burden: the gated door is the only one that can reach the blocks and precincts.

What this brief cannot tell you

A catalog is not data. Nothing above establishes a single population count, and no live query was run, so nothing here describes what the gated half returns. The numbers behind these column names are themselves processed before release: rounded, withheld and, since 2020, deliberately noised.

It cannot measure who is shut out by the key. That would take the request logs, which nobody publishes, or a survey of the people who gave up, which nobody has run. This brief reads an architecture and argues from it, and that is a weaker kind of claim than a measurement.

It describes a day. The catalog is as the Bureau published it in August 2026, and the key requirement itself is recent. The 2030 release will list different columns: a 2024 federal revision merges the race and Hispanic-origin questions into one,6 which will change the shape of P1 through P4 and every trend computed across them.

And the columns are the closest measurable thing, not the thing the law asks for. For many voting-rights claims the right denominator (the bottom number of the fraction, the population you divide by) is citizens of voting age. The census does not publish that. It comes from the American Community Survey instead, with a margin of error attached: a stated range for how far off each estimate could be.

What you should have learned

Extensions

Every question below can be answered by sorting or grouping the two tables handed over under The data itself.

Two stretch extensions, beyond the spreadsheet:

Sources

Data

Statute and literature

The data itself

Every figure above is drawn from these tables. They are plain CSV, they open in a spreadsheet, and they are yours to take further.

api_geography.csv, api_variables.csv

  1. Now 13 U.S.C. § 141(c): https://www.law.cornell.edu/uscode/text/13/141.↩︎

  2. 52 U.S.C. § 10301: https://www.law.cornell.edu/uscode/text/52/10301.↩︎

  3. The Supreme Court set out that test in Thornburg v. Gingles, 478 U.S. 30 (1986): https://www.law.cornell.edu/supremecourt/text/478/30.↩︎

  4. The Bureau’s Redistricting Data Program, through which states submit their voting districts: https://www.census.gov/programs-surveys/decennial-census/about/rdo/program-management.html. The National Conference of State Legislatures’ Redistricting Law 2020 says plainly that taking part is optional: https://www.ncsl.org/redistricting-and-census/redistricting-law-2020.↩︎

  5. The Bureau’s user guide sets out the key and the daily limit: https://www.census.gov/data/developers/guidance/api-user-guide.html.↩︎

  6. Office of Management and Budget, revisions to Statistical Policy Directive No. 15, Federal Register, 29 March 2024: https://www.federalregister.gov/documents/2024/03/29/2024-06469/revisions-to-ombs-statistical-policy-directive-no-15-standards-for-maintaining-collecting-and-presenting-federal-data-on-race-and-ethnicity.↩︎