Tools

8 tools covering the full Census data workflow — from dataset discovery and variable search through geography resolution and ranked comparisons:

census_list_datasets

Browse available Census Bureau datasets.

• Returns dataset codes, names, descriptions, and available vintage years
• Covers ACS5, ACS5 Data Profiles, ACS5 Subject Tables, ACS1, ACS1 Data Profiles, Population Estimates, Decennial Redistricting (P.L. 94-171), Decennial DHC, County Business Patterns (cbp), Economic Census (ecnbasic), and Nonemployer Statistics (nonemp)
• Each description names the filter predicates the dataset requires and the geography levels it publishes — both vary by dataset
• Accepts an optional keyword filter
• Dataset codes (e.g., acs/acs5) are the values to pass to other tools
• available_years is exhaustive, not a sample: any other year fails with year_not_available before a request goes out, naming the years that do work. It is narrower than what the Census API hosts — pep/charv reaches its 2020-2022 estimates through the YEAR filter inside the 2023 vintage, and the cbp/nonemp vintages left out reject the NAME column every query here sends

census_search_variables

Search Census variables by keyword.

• Full-text search across label and concept fields with relevance scoring (exact concept match > label match > partial)
• On ACS datasets, returns estimate (E suffix) and margin-of-error (M suffix) codes together so both can be requested in one query — no other family publishes margins of error, and an E-final code there is an ordinary code
• Also surfaces the predicate codes a dataset filters on, such as NAICS2017 in cbp
• Configurable limit (default 20, max 100); total_matches indicates how many matched before the limit
• Cache-backed: variables.json is fetched once per dataset+year with a configurable TTL (default 24h)

census_list_predicate_values

List the codes a filter dimension accepts, so a predicates map can be written without guessing.

• Two routes, picked by where the answer lives: a dimension with a published value list is read from the dataset dictionary, one without is enumerated live by wildcarding it on the data endpoint. NAICS* and POPGROUP always publish one (thousands of codes — narrow them with query); on the current vintages EMPSZES, LFO, RCPSZES, TAXSTAT, and TYPOP publish none, so the live route is the only place their codes appear
• A dictionary value list is a classification shared across Census products, not a record of what one dataset serves — dec/ddhca declares 5,543 POPGROUP codes and publishes 2,996, cbp declares 6,694 NAICS2017 codes and publishes 2,003. The declared list is checked against the dataset's own published rows and the dead codes are dropped; source says whether that check ran and the notice says how many were withheld. A keyword that matched only withheld codes names them, so "total population" on dec/ddhca reports that 001 is declared and serves nothing rather than reading like a typo
• Keyword query matches code and label; results are sorted by code and a truncated list is disclosed rather than passed off as complete
• ecnbasic publishes TAXSTAT and TYPOP per industry, so within_naics scopes the enumeration — and the notice says the result is complete for that industry alone. A per-industry dimension is left unchecked for the same reason, since an unscoped check would withhold codes a scoped query does return
• Live enumerations are cached per dataset, year, dimension, industry scope, and probe measure

census_resolve_geography

Convert place names and addresses to Census FIPS identifiers.

• Named places (e.g., "King County, WA", "Seattle, WA", "California") resolved via TIGERweb MapServer
• Street addresses resolved to tract level via Census Geocoder
• Auto-detects the geography level — state for an abbreviation or spelled-out state name, county for "County"/"Borough"/"Parish", tract for "Tract", otherwise place falling back to county; geography_type overrides it
• Also resolves metropolitan/micropolitan statistical areas, combined statistical areas, and consolidated cities — never auto-detected, since their names overlap city names, so each needs an explicit geography_type. The value is the level's own Census API name, so it feeds geography_level unchanged
• Optional county_fips pins a tract name to one county, since a tract name is unique only inside its county. Only county and tract sit within a county, so it restricts resolution to those two levels rather than being dropped on a layer that cannot apply it
• Prefers an exactly-named match, so "Kansas City, MO" does not resolve to North Kansas City
• Never picks between matches: anything still matching more than one geography comes back as ambiguous_name, with every candidate carrying the code resolving it would have returned, plus the state that separates same-named places
• Returns state_fips (→ parent_fips) and fips_summary (→ geography_fips) ready to pass to other tools; a statistical area omits state_fips, since it can span several states and takes no parent

census_query_data

Query a Census dataset for one or more variables at a specific geography.