Tutorial: US Census Bureau

Economics

Data source: US Census Bureau API

Overview

US Census Bureau wraps US Census Bureau API, handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-us-census": {
      "url": "https://context.gnist.ai/mcp/us-census/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`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`)

curl -X POST "https://context.gnist.ai/mcp/us-census/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_acs_data", "arguments": {"variables": "[\"B01001_001E\"", "geography": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-census/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'geography': 'example',
                          'variables': '["B01001_001E"'},
            'name': 'get_acs_data'}},
)
print(resp.json())

`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`)

curl -X POST "https://context.gnist.ai/mcp/us-census/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_acs_profile", "arguments": {"profile_type": "example", "geography": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-census/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'geography': 'example', 'profile_type': 'example'},
            'name': 'get_acs_profile'}},
)
print(resp.json())

`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`)

curl -X POST "https://context.gnist.ai/mcp/us-census/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_groups", "arguments": {"query": "income"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-census/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'income'}, 'name': 'search_groups'}},
)
print(resp.json())

`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`)

curl -X POST "https://context.gnist.ai/mcp/us-census/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_group_variables", "arguments": {"group": "B01001"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-census/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'group': 'B01001'}, 'name': 'get_group_variables'}},
)
print(resp.json())

`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`)

curl -X POST "https://context.gnist.ai/mcp/us-census/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_geography_codes", "arguments": {"geography_type": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-census/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'geography_type': 'example'},
            'name': 'get_geography_codes'}},
)
print(resp.json())

`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`)

curl -X POST "https://context.gnist.ai/mcp/us-census/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/us-census/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_groups to find items, then get_acs_data to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does US Census Bureau provide?

US Census Bureau data — American Community Survey demographics, income, housing, and social characteristics for states, counties, cities, and tracts. It exposes 6 tools: get_acs_data, get_acs_profile, search_groups, get_group_variables, get_geography_codes, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the US Census Bureau API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.