List Census Predicate Values
census_list_predicate_valuesList the codes a Census filter dimension accepts, so a predicates map can be written without guessing. Answers the question left open when census_query_data or census_compare_geographies reports that a dimension was left unset. Which route a dimension takes depends on the vintage: NAICS and POPGROUP always publish a value list in the dataset dictionary, and on the current vintages EMPSZES, LFO, RCPSZES, TAXSTAT, and TYPOP publish none and are enumerated here against the live data endpoint instead, which needs the server's Census API key. A dictionary value list is a classification shared across Census products rather than a list of what one dataset serves, and roughly half of its codes typically return no rows anywhere — those are checked against the dataset's own published rows and dropped, a check that also reads the data endpoint and so needs the key; without a working key the dictionary list comes back unchecked, and the response source field says whether that check ran. The dictionary lists run to thousands of codes and are best narrowed with query. Pass the returned code as the dimension's value in predicates.
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": {
"predicate": "<predicate>",
"dataset": "<dataset>"
},
"name": "census_list_predicate_values"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Vintage year (default: latest available for the dataset). | |
| limit | No | Maximum codes per page (default: 50, max: 500). totalCount counts matches before offset and limit; nextOffset continues the list. | |
| query | No | Keyword to narrow the list, matched case-insensitively against each code and label (e.g., "software" against NAICS2017, "exempt" against TAXSTAT). Omit to list from the start. NAICS and POPGROUP run to thousands of codes, so a keyword is the practical way to use them. | |
| offset | No | Matching codes to skip in code order (default: 0). Follow nextOffset with the same predicate, dataset, year, query, geography_level and within_naics. | |
| dataset | Yes | Dataset the dimension belongs to (e.g., "cbp", "nonemp", "ecnbasic", "dec/ddhca", "dec/ddhcb", "pep/charv", "acs/acs1/spp"). Use census_list_datasets to discover valid values. Case is ignored, and a two-part code can be given by its last part alone — "ddhca" is dec/ddhca, "charv" is pep/charv. Three-part codes such as acs/acs1/spp must be given in full. The response echoes the resolved code. Dimension codes are vintage-specific, so the dataset and year must match the query the values are for. | |
| predicate | Yes | Filter dimension code to enumerate (e.g., "EMPSZES", "LFO", "POPGROUP", "NAICS2017"). Trimmed and uppercased, and the response echoes that spelling. The response notice of census_query_data names the dimensions a dataset declares, and census_search_variables finds them by keyword. | |
| within_naics | No | Industry code to scope the enumeration by, for dimensions the Census publishes per industry. On ecnbasic, TAXSTAT and TYPOP return only the all-establishments row until a NAICS sector is named — pass a sector code such as "62" (Health Care) or "42" (Wholesale Trade) and the result is complete for that industry alone. Ignored for dimensions with a published value list. Get sector codes by calling this tool on the dataset's own NAICS dimension. Blank is treated as omitted. | |
| geography_level | No | Geography level for live enumeration (default: "us"). Codes can differ by level. Only levels whose dataset/year geography metadata permits a wildcard without concrete parents are supported, such as "county" on cbp. Dictionary lists remain dataset-wide and do not validate publication at this level. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Vintage year queried. | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance when the list was truncated, when query matched no published code, when codes from the dataset dictionary could not be checked against its published rows, or when the codes returned are complete only for a named industry rather than for the dimension as a whole. | |
| source | No | Where the codes came from. "live_query" is a wildcard group-by against the data endpoint, which returns only codes the dataset publishes. "dataset_dictionary_verified" is the dataset's published value map with the codes it serves no rows for removed. Plain "dataset_dictionary" is that map unchecked — every code in it is declared by the dataset, but some of them return nothing at any geography, and the notice says why the check did not run. | |
| values | No | Codes the dimension accepts, sorted by code. | |
| dataset | No | Dataset queried. | |
| predicate | No | Filter dimension enumerated. | |
| truncated | No | True when matching codes remain after the current page. | |
| nextOffset | No | Offset for the next page; absent when no matching codes remain after this page. | |
| totalCount | No | Codes matched before the limit was applied. | |
| geography_level | No | Effective live enumeration level. Absent for a dictionary list, which does not validate geography-specific publication. | |
| predicate_label | No | Label of the dimension itself (e.g., "Employment size of establishments code"). |