Search Census Variables
census_search_variablesSearch Census variables by keyword across variable labels and concept groups, or look one up by its code. Returns variable codes with human-readable labels — use this to go from a concept like "median household income" to the variable code B19013_001E needed for data queries. A query that is one variable or table code, such as B19013_001E or B19013, returns that variable or the table's variables, in code order, ahead of any keyword matches; a code the dataset does not publish gets a notice naming the dataset that does, when one is confirmed. To retrieve every column of a table, pass its ID to census_query_data as group rather than listing its codes. On ACS datasets it returns both estimate (E suffix) and margin-of-error (M suffix) codes so you can request both; the ACS comparison profiles (acs/acs5/cprofile, acs/acs1/cprofile) and the other dataset families publish no margins of error. Also use it to find the predicate codes a dataset filters on, such as NAICS2017 in cbp. Adding a word narrows the results, since every word must match. Use offset to continue the same search beyond limit; nextOffset names the next page.
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": {
"query": "<query>"
},
"name": "census_search_variables"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Vintage year to search (default: latest available for the dataset). | |
| limit | No | Maximum results per page (default: 20, max: 100). Follow nextOffset to continue the same search. | |
| query | Yes | Keywords to search (e.g., "median household income", "poverty", "bachelor's degree"), or one variable or table code (e.g., "B19013_001E", "B19013"). Each word must match a whole word of the label or of the concept, ignoring case and punctuation, so "rate" does not match "separated". A column shared across tables, such as GEO_ID, is matched on its label only, and a margin of error on its estimate's label. When no variable contains every word, the results are the variables containing the most words, and the notice says how many that was. A single token that equals a variable code or a table ID, ignoring case and any quotes or punctuation around it, returns those variables first; that table ID is also what census_query_data takes as group to retrieve the whole table. A token with no digit or underscore, such as "state", is read as a code when no keyword matched; ahead of keyword matches only when typed in the code's own uppercase ("STATE"). | |
| offset | No | Matching variables to skip in the existing rank order (default: 0). Keep query, dataset, year and limit unchanged when following nextOffset. | |
| dataset | No | Dataset to search within (default: "acs/acs5"). Use census_list_datasets to discover options. 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, and the default year is that dataset's latest. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit that was applied. | |
| year | No | Vintage year that was searched. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of variables returned after the limit. | |
| notice | No | Guidance for no matches, partial-term matches, continuation, the final page or an offset past the end. For a code the dataset does not publish, names the confirmed sibling dataset or census_get_variable for an attribute column; for a table cut inside its code tier, names the last code shown and the next offset. | |
| dataset | No | Dataset that was searched. | |
| truncated | No | True when more matching variables remain after the current page. | |
| variables | No | Matching variables, best first: the variable whose code equals the query, or every variable of the table whose ID equals it, in code order; then a variable whose label's last !!-separated segment or whose whole concept equals the query, then the query as a phrase in both label and concept, in the label only, in the concept only, then every word present but not as a phrase; ties go to fewer !! segments in the label, then a shorter concept, then the code, which puts an E estimate before its M margin of error. On ACS datasets, codes ending in E are estimates and M are their margins of error, except on the comparison profiles, which publish no M codes; on other datasets the suffix carries no such meaning. | |
| nextOffset | No | Offset for the next page; absent when no matches remain after this page. | |
| totalMatches | No | Variables matched before the limit was applied: those matching the query as a code, plus those containing every query word — or, when none does and no code matched, the variables that contain the most words. | |
| effectiveQuery | No | Query as the server parsed it. |