{"openapi":"3.0.3","info":{"title":"Gnist Context — US Census Bureau","description":"US Census Bureau data — American Community Survey demographics, income, housing, and social characteristics for states, counties, cities, and tracts.\n\n- **MCP endpoint:** `https://context.gnist.ai/mcp/us-census/`\n- **Toolkit page:** `/toolkits/us-census`\n- **Full API spec:** `/api/openapi.json`\n- **Get an API key:** `/signup`","version":"1.0.0","contact":{"name":"GnistAI","url":"https://gnist.ai"}},"servers":[{"url":"https://context.gnist.ai","description":"Production"}],"paths":{"/rest/us-census/get_acs_data":{"post":{"tags":["Economics"],"summary":"get_acs_data","description":"Fetch American Community Survey 5-year data by variable codes and geography.\n\nThe ACS 5-year estimates cover the smallest geographies (down to block\ngroups) and are the most statistically reliable. Use search_groups() and\nget_group_variables() to discover variable codes, or use get_acs_profile()\nfor pre-curated indicators.\n\nCommon variable codes:\n- B01001_001E — Total population\n- B19013_001E — Median household income\n- B25077_001E — Median home value\n- B01002_001E — Median age\n- B17001_002E — Population below poverty level\n\nCommon FIPS codes:\n- States: 06=California, 36=New York, 48=Texas\n- Use get_geography_codes() to look up FIPS codes by name","operationId":"us_census_get_acs_data","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"variables":{"description":"ACS variable codes (e.g. [\"B01001_001E\", \"B19013_001E\"]).","items":{"type":"string"},"type":"array"},"geography":{"description":"Geography type: us, state, county, place, tract, block_group, zip_code, metro_area, or congressional_district.","type":"string"},"code":{"default":"*","description":"FIPS code for the geography, or \"*\" for all. Use get_geography_codes to look up codes.","type":"string"},"within_state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"State FIPS code to filter within (required for county, place, tract queries)."},"within_county":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"County FIPS code to further filter within (for tract/block group queries)."},"year":{"default":2022,"description":"ACS 5-year vintage year (2009-2022). Default 2022.","type":"integer"}},"required":["variables","geography"],"type":"object"}}}}}},"/rest/us-census/get_acs_profile":{"post":{"tags":["Economics"],"summary":"get_acs_profile","description":"Get curated demographic, economic, housing, or social profile data.\n\nReturns pre-selected key indicators from ACS Data Profiles, so you don't\nneed to know individual variable codes. Great for quick community snapshots.\n\nProfile types and sample indicators:\n- demographic: population, age, sex, race/ethnicity\n- economic: income, poverty, unemployment, employment\n- housing: home values, rent, occupancy, vacancy\n- social: education, language, internet access","operationId":"us_census_get_acs_profile","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"profile_type":{"description":"Profile type: demographic, economic, housing, or social.","type":"string"},"geography":{"description":"Geography type: us, state, county, place, etc.","type":"string"},"code":{"default":"*","description":"FIPS code for the geography, or \"*\" for all.","type":"string"},"within_state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"State FIPS code to filter within."},"year":{"default":2022,"description":"ACS 5-year vintage year (2009-2022). Default 2022.","type":"integer"}},"required":["profile_type","geography"],"type":"object"}}}}}},"/rest/us-census/search_groups":{"post":{"tags":["Economics"],"summary":"search_groups","description":"Search available ACS table groups (data tables) by keyword.\n\nACS data is organized into groups (tables) like B01001 (Sex by Age),\nB19013 (Median Household Income), etc. Use this to find the right table\nand then get_group_variables() to see what variables it contains.","operationId":"us_census_search_groups","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"query":{"description":"Search term for ACS table groups (e.g. \"income\", \"education\", \"housing\").","type":"string"},"year":{"default":2022,"description":"ACS 5-year vintage year. Default 2022.","type":"integer"},"limit":{"default":20,"description":"Max results to return (1-100). Default 20.","type":"integer"}},"required":["query"],"type":"object"}}}}}},"/rest/us-census/get_group_variables":{"post":{"tags":["Economics"],"summary":"get_group_variables","description":"List all variables in a specific ACS table group.\n\nReturns variable IDs, labels, and concepts for the group. Use the\nvariable IDs with get_acs_data() to fetch actual data values.","operationId":"us_census_get_group_variables","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"group":{"description":"ACS table group code (e.g. \"B01001\", \"B19013\", \"DP05\").","type":"string"},"year":{"default":2022,"description":"ACS 5-year vintage year. Default 2022.","type":"integer"}},"required":["group"],"type":"object"}}}}}},"/rest/us-census/get_geography_codes":{"post":{"tags":["Economics"],"summary":"get_geography_codes","description":"Look up FIPS codes for geographies by name.\n\nFIPS codes are opaque identifiers (e.g. California=06, New York=36).\nThis tool maps geographic names to their FIPS codes so you can use\nthem with get_acs_data() and get_acs_profile().","operationId":"us_census_get_geography_codes","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"geography_type":{"description":"Geography type: state, county, place, etc.","type":"string"},"state_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"State FIPS code (for county, place, tract lookups)."},"year":{"default":2022,"description":"ACS 5-year vintage year. Default 2022.","type":"integer"}},"required":["geography_type"],"type":"object"}}}}}},"/rest/us-census/report_feedback":{"post":{"tags":["Economics"],"summary":"report_feedback","description":"Report a bug, feature request, or general feedback for this data source.\n\nUse this when something doesn't work as expected, when you'd like\na new feature, or when you have suggestions for improvement.\n\nArgs:\n    feedback: Describe the issue or suggestion.\n    feedback_type: One of 'bug', 'feature_request', or 'general'.","operationId":"us_census_report_feedback","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"feedback":{"type":"string"},"feedback_type":{"default":"general","type":"string"}},"required":["feedback"],"type":"object"}}}}}}},"tags":[{"name":"Economics","description":"Data sources: Economics"}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"gnist-api-key","description":"API key passed via request header."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"gnist_api_key","description":"API key passed via query parameter."}}}}