Skip to main content
POST
geo.census.acs.query

Authorizations

Authorization
string
header
required

API key: sk_live_…. The approvals routes and GET /v1/members/me also take a member token: an OAuth access token an app gets when its member signs in to Pramaan and allows pramaan:approve (see the approvals guide).

Headers

Idempotency-Key
string

Optional. A retry with the same key returns the stored result.

Maximum string length: 255
Pramaan-Max-Price-Micro
string

Optional. The most this request may be priced at, in micro-USD (a whole number above 0). It replaces the capability's own price ceiling for this request, lower or higher. Sources that could cost more are left out; when none is left the answer is 400 with the lowest limit that would work.

Pattern: ^[1-9]\d{0,14}$

Body

application/json
variables
string[]
required

One to 20 detailed-table variables, e.g. B01001_001E (total population), B19013_001E (median household income). An E variable is the estimate and an M variable its margin of error.

Required array length: 1 - 20 elements
Pattern: ^[BC]\d{5}[A-I]?_\d{3}[EM]$
level
enum<string>
required

The kind of area to return: the whole country, states, counties, places (cities and towns), census tracts or ZIP code areas.

Available options:
us,
state,
county,
place,
tract,
zcta
year
integer
default:2023

The survey's data year. Default 2023.

Required range: 2010 <= x <= 2035
dataset
enum<string>
default:acs5

acs5: 5-year estimates, every area down to tracts. acs1: 1-year, areas of 65,000+ people. Default acs5.

Available options:
acs5,
acs1
state
string

Two-digit state FIPS code. Needed for place and tract; limits county to one state.

Pattern: ^\d{2}$
county
string

Three-digit county FIPS code, within the state. Needed for tract.

Pattern: ^\d{3}$
code
string

The code of one area at the chosen level (a state, county, place, tract or ZIP code area). Default: every area that fits.

Pattern: ^\d{1,7}$

Response

The result

year
number
required

The data year.

dataset
enum<string>
required

Which estimate was read.

Available options:
acs5,
acs1
rows
object[]
required

One row per area. An empty list means the survey has no data there.

truncated
boolean

True when more than 5,000 areas matched and the rest were left out.