Compare Census Geographies
census_compare_geographiesCompare one or more variables across multiple geographies at the same level — all counties in a state, all states nationally, or a named set of specific geographies — ranked on the value of one of them. Covers queries like "compare median income across WA counties" or "which states have the most people below the poverty line." A count ranks geographies by size, not by rate, so to rank a rate, rank a published percentage: S1701_C03_001E (percent below the poverty level, dataset acs/acs5/subject), DP03_0128PE (the same percentage, acs/acs5/profile), or DP04_0047PE (percent of occupied housing units that are renter-occupied, acs/acs5/profile). Profile and subject tables reach tracts but not block groups. Omit within to compare all geographies nationally at the level. Suppressed values are decoded to human-readable labels rather than passed through as raw negative sentinels. On the business datasets (cbp, ecnbasic, nonemp), pep/charv, dec/ddhca, dec/ddhcb, and acs/acs1/spp, use predicates to rank within one industry, size class, or population group — a comparison that omits one ranks on a default the Census API picks, which is an all-categories total on some dimensions and a single category on others. Each row names the defaults that were applied in applied_filters, and census_list_predicate_values enumerates the codes a dimension accepts. Some dec/ddhca and dec/ddhcb tables split the population groups between them, publishing each group at a geography in only one table of the family, so a ranking on one of them leaves out the geographies whose group sits in a sibling table — the notice names those tables. A dataset that publishes several records per geography cannot be ranked until one is pinned: pep/charv publishes an April estimates base and a July estimate, so a comparison that pins neither fails with ambiguous_rows rather than giving every geography two ranks — pass predicates {"MONTH": "7"} for the July estimate.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"variables": "<variables>",
"geography_level": "<geography_level>"
},
"name": "census_compare_geographies"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Vintage year (default: latest available for the dataset). | |
| limit | No | Maximum geographies per page (default: 50, max: 500). totalCount counts the matched set before paging; nextOffset reaches the next page. | |
| offset | No | Rows to skip in the sorted matched set (default: 0), not a rank. Equal numeric estimates share competition ranks and are ordered by GEOID. An offset at or past totalCount returns no rows. | |
| within | No | State FIPS to constrain results (e.g., "53" to compare counties or tracts within WA only). Omit to compare all geographies at the level nationally. Use census_resolve_geography to get state_fips. Pass "*" to span every state on the levels whose hierarchy lets "*" stand in for the state, such as county and place; tract, block group, and county subdivision need one state. Blank is treated as omitted. | |
| dataset | No | Dataset to query (default: "acs/acs5"). Use census_list_datasets for valid values. Case is ignored, and a two-part code can be given by its last part alone — "acs5" is acs/acs5, "pl" is dec/pl. Three-part codes such as acs/acs5/profile must be given in full. The response echoes the resolved code. | |
| sort_by | No | Variable code to rank on (default: the first code in variables), matched regardless of case like the variables. Must be one of the requested codes, or the call fails with sort_by_not_requested. Geographies rank on that code's own value, so a count ranks by size and only a published percentage such as S1701_C03_001E or DP03_0128PE ranks by rate. | |
| sort_dir | No | Sort direction (default: "desc" — highest value first). | |
| variables | Yes | Variable codes to compare (e.g., ["B19013_001E", "B19013_001M"]); the ranking is on one of them, set by sort_by. Codes are matched regardless of case and sent in the dataset's own spelling, which keys each row — uppercase everywhere except the comparison profiles' significance columns (CP03_2024to2019_062SS). A code the dataset does not list is sent uppercased. At most 49 per call: the Census API accepts 50 columns per request and every query also sends NAME. On datasets where a label column is added for each filter dimension left unset, or record columns are added (cbp, ecnbasic, nonemp, pep/charv, dec/ddhca, dec/ddhcb, acs/acs1/spp), the maximum is lower, and too_many_variables states the exact number for the comparison. On ACS datasets, add the margin-of-error counterpart of a code (same code, E suffix swapped for M) for reliability context. The ACS comparison profiles (acs/acs5/cprofile, acs/acs1/cprofile) and the other dataset families (pep, dec, cbp, ecnbasic, nonemp, geoinfo) publish no margins of error. | |
| predicates | No | Filter values keyed by variable code, applied to every geography in the comparison — e.g. {"NAICS2017": "5112"} to rank counties by their software-publisher establishment count in cbp. The business datasets (cbp, ecnbasic, nonemp), pep/charv, dec/ddhca, dec/ddhcb, and acs/acs1/spp declare filter dimensions such as industry (NAICS2017/NAICS2022), legal form (LFO), size class (EMPSZES/RCPSZES), tax status (TAXSTAT), operation type (TYPOP), sex (SEX), age (AGE), and population group (POPGROUP). Leaving one unset is not an error: the Census API substitutes its own default, which is the all-categories total on cbp NAICS2017 but a single population group on dec/ddhca and dec/ddhcb POPGROUP and a single sector on ecnbasic NAICS2022 — so a ranking can read like an overall one without being it. Every unset dimension is named in the response notice and its applied default is echoed per row in applied_filters. Keys are matched case-insensitively, and a blank value is treated as omitted. A value of "*" returns every geography once per category of that dimension, which a ranking cannot hold, so it fails with ambiguous_rows naming the dimension to pin — use census_query_data for a per-category breakdown. Code names vary by dataset and vintage — cbp 2023 uses NAICS2017 while nonemp 2023 uses NAICS2022 — so read them from the notice or from census_search_variables. Call census_list_predicate_values for the codes a dimension accepts; NAICS values are standard North American Industry Classification System codes at any depth (51 information, 5112 software publishers). | |
| geographies | No | Optional list of specific geographies to include; only these are returned. Prefer full GEOIDs — the level concatenated with its parents, e.g. "53033" for King County WA and "06037" for Los Angeles County CA — which are nationally unique and so work across states. Bare level codes ("033") are also accepted but match that code in every state unless within scopes them to one. A GEOID is easiest taken from the geography_geoid field of a census_query_data or census_compare_geographies row; from census_resolve_geography, concatenate state_fips, then county_fips when it is present, then fips_summary. Entries that match nothing, and bare codes that match more than one state, are named in the response notice. | |
| within_county | No | County FIPS to constrain tract or block-group comparisons to a single county within the state specified by within (e.g., "033" for King County). Required when geography_level is "tract" or "block group" and you want county-scoped results. census_resolve_geography returns this as county_fips. Pass "*" to span every county in the state, which is the only way a block-group comparison reaches a whole state; "*" works on the levels whose hierarchy lets it stand in for the county, such as tract and block group. Blank is treated as omitted. | |
| geography_level | Yes | The level to compare across (e.g., "state", "county", "tract"). Use census_list_geographies to see valid values for the dataset. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | No | Geographies sorted by the requested variable. Suppressed values are labeled. | |
| year | No | Vintage year queried. | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance when results were truncated, when the sort column holds no number on any row (so the rows are in the order the Census returned them rather than ranked), when geographies entries matched no row, when a bare level code matched more than one state, or when the dataset declares filter dimensions the comparison left unset — how to narrow scope, raise the limit, correct the FIPS codes, or add the predicates that pin what the ranking covers. Unmatched geographies include applicable ACS publication coverage guidance and variable rediscovery when switching datasets, and, for a tract or block group entry on a vintage before 2020 or a Connecticut county in the other county scheme, which boundaries that vintage publishes. For an unset dimension it also quotes the label of the default the Census API applied, which is what says whether the ranking is on a total or on one category. On dec/ddhca and dec/ddhcb tables that split the population groups between them, it names the sibling tables a geography left out of the ranking may sit in. Also names any variable codes whose flags could not be checked because the request had no room left under the Census 50-column limit — a withheld value there reads as 0 and ranks as one. | |
| dataset | No | Dataset queried. | |
| truncated | No | True only when more matched rows remain after this page. | |
| nextOffset | No | Row offset for the next page, present only when truncated is true. An offset counts rows rather than competition ranks. | |
| scopeCount | No | Number of fetched geographies before the nonempty geographies filter; the denominator for scope_rank. Absent without that filter. | |
| totalCount | No | Total geographies matched after the geographies filter, before offset and limit. | |
| sortVariable | No | Variable code the rows are ranked on, in the dataset's spelling, as it keys each row's variables. | |
| variable_labels | No | Map of variable code to its label from the Census data dictionary (e.g. {"B19013_001E": "Estimate!!Median household income in the past 12 months (in 2024 inflation-adjusted dollars)"}), stated once for the response rather than on every row. Keys follow the order the rows key variables. Built from the request, so every page of one comparison carries the same map, a page past the end included. A code the dictionary gives no label, such as an annotation or flag column (B19013_001EA, EMP_F), has no entry. |