Tools (6)

get_acs_data
get_acs_profile
search_groups
get_group_variables
get_geography_codes
report_feedback

get_acs_data

Fetch American Community Survey 5-year data by variable codes and geography.

The ACS 5-year estimates cover the smallest geographies (down to block
groups) and are the most statistically reliable. Use search_groups() and
get_group_variables() to discover variable codes, or use get_acs_profile()
for pre-curated indicators.

Common variable codes:
- B01001_001E — Total population
- B19013_001E — Median household income
- B25077_001E — Median home value
- B01002_001E — Median age
- B17001_002E — Population below poverty level

Common FIPS codes:
- States: 06=California, 36=New York, 48=Texas
- Use get_geography_codes() to look up FIPS codes by name

Parameter	Type	Required	Description
`variables`	`list[string]`	required	ACS variable codes (e.g. ["B01001_001E", "B19013_001E"]).
`geography`	`string`	required	Geography type: us, state, county, place, tract, block_group, zip_code, metro_area, or congressional_district.
`code`	`string`	optional	FIPS code for the geography, or "" for all. Use get_geography_codes to look up codes. (default: "")
`within_state`	`any`	optional	State FIPS code to filter within (required for county, place, tract queries).
`within_county`	`any`	optional	County FIPS code to further filter within (for tract/block group queries).
`year`	`integer`	optional	ACS 5-year vintage year (2009-2022). Default 2022. (default: 2022)

Request Body

{
  "variables": [
    "example"
  ],
  "geography": "example"
}

get_acs_profile

Get curated demographic, economic, housing, or social profile data.

Returns pre-selected key indicators from ACS Data Profiles, so you don't
need to know individual variable codes. Great for quick community snapshots.

Profile types and sample indicators:
- demographic: population, age, sex, race/ethnicity
- economic: income, poverty, unemployment, employment
- housing: home values, rent, occupancy, vacancy
- social: education, language, internet access

Parameter	Type	Required	Description
`profile_type`	`string`	required	Profile type: demographic, economic, housing, or social.
`geography`	`string`	required	Geography type: us, state, county, place, etc.
`code`	`string`	optional	FIPS code for the geography, or "" for all. (default: "")
`within_state`	`any`	optional	State FIPS code to filter within.
`year`	`integer`	optional	ACS 5-year vintage year (2009-2022). Default 2022. (default: 2022)

Request Body

{
  "profile_type": "example",
  "geography": "example"
}

search_groups

Search available ACS table groups (data tables) by keyword.

ACS data is organized into groups (tables) like B01001 (Sex by Age),
B19013 (Median Household Income), etc. Use this to find the right table
and then get_group_variables() to see what variables it contains.

Parameter	Type	Required	Description
`query`	`string`	required	Search term for ACS table groups (e.g. "income", "education", "housing").
`year`	`integer`	optional	ACS 5-year vintage year. Default 2022. (default: 2022)
`limit`	`integer`	optional	Max results to return (1-100). Default 20. (default: 20)

Request Body

{
  "query": "example"
}

get_group_variables

List all variables in a specific ACS table group.

Returns variable IDs, labels, and concepts for the group. Use the
variable IDs with get_acs_data() to fetch actual data values.

Parameter	Type	Required	Description
`group`	`string`	required	ACS table group code (e.g. "B01001", "B19013", "DP05").
`year`	`integer`	optional	ACS 5-year vintage year. Default 2022. (default: 2022)

Request Body

{
  "group": "example"
}

get_geography_codes

Look up FIPS codes for geographies by name.

FIPS codes are opaque identifiers (e.g. California=06, New York=36).
This tool maps geographic names to their FIPS codes so you can use
them with get_acs_data() and get_acs_profile().

Parameter	Type	Required	Description
`geography_type`	`string`	required	Geography type: state, county, place, etc.
`state_code`	`any`	optional	State FIPS code (for county, place, tract lookups).
`year`	`integer`	optional	ACS 5-year vintage year. Default 2022. (default: 2022)

Request Body

{
  "geography_type": "example"
}

report_feedback

Report a bug, feature request, or general feedback for this data source.

Use this when something doesn't work as expected, when you'd like
a new feature, or when you have suggestions for improvement.

Args:
feedback: Describe the issue or suggestion.
feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	`string`	required
`feedback_type`	`string`	optional	(default: "general")

Request Body

{
  "feedback": "example"
}

Quick Start

Shell

curl -X POST "https://context.gnist.ai/rest/us-census/get_acs_data" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"variables": "...", "geography": "example"}'

Python

import httpx

resp = httpx.post(
    "https://context.gnist.ai/rest/us-census/get_acs_data",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={
  "variables": "...",
  "geography": "example"
},
)
print(resp.json())