Hi, It’s Me Again…

I didn’t expect to be back here so soon, but I realized something was missing from cendat–the ability to get geography names. It didn’t seem like it was missing, after all you can just include it in set_names()… right? Well, it turns out that you can’t do that because NAME is a special keyword understood by the by the API but that is not included in variables.json, which is the basis for the selections you can make in set_names().

Thankfully the fix for this is very simple: there is a new include_names parameter in get_data() (boolean, defaults to False) that we can use to include geography name in our queries. Like this:

import os
from cendat import CenDatHelper
from dotenv import load_dotenv

load_dotenv()

c = CenDatHelper(key=os.getenv("CENSUS_API_KEY"))

c.list_products(2023, r"acs/acs1\)")
c.set_products()
c.set_variables("B01001_001E")
c.set_geos("160")

response = c.get_data(include_names=True)

response.tabulate("NAME", where="B01001_001E > 1_000_000", weight_var="B01001_001E")

✅ API key loaded successfully.
✅ Product set: 'ACS 1-Year Detailed Tables (2023/acs/acs1)' (Vintage: [2023])
✅ Variables set:
  - Product: ACS 1-Year Detailed Tables (2023/acs/acs1) (Vintage: [2023])
    Variables: B01001_001E
✅ Geographies set: 'place' (requires `within` for: state)
✅ Parameters created for 1 geo-variable combinations.
✅ Found 1 combinations. Building API queries...
ℹ️ Making 1 API call(s)...
shape: (9, 5)
┌─────────────────────────────────┬───────────┬──────┬────────────┬────────┐
│                            NAME ┆         n ┆  pct ┆       cumn ┆ cumpct │
╞═════════════════════════════════╪═══════════╪══════╪════════════╪════════╡
│          Chicago city, Illinois ┆ 2,664,454 ┆ 10.9 ┆  2,664,454 ┆   10.9 │
│              Dallas city, Texas ┆ 1,302,859 ┆  5.3 ┆  3,967,313 ┆   16.2 │
│             Houston city, Texas ┆ 2,311,461 ┆  9.5 ┆  6,278,774 ┆   25.7 │
│    Los Angeles city, California ┆ 3,820,963 ┆ 15.6 ┆ 10,099,737 ┆   41.3 │
│         New York city, New York ┆ 8,258,035 ┆ 33.8 ┆ 18,357,772 ┆   75.1 │
│ Philadelphia city, Pennsylvani… ┆ 1,550,542 ┆  6.3 ┆ 19,908,314 ┆   81.5 │
│           Phoenix city, Arizona ┆ 1,650,051 ┆  6.8 ┆ 21,558,365 ┆   88.2 │
│         San Antonio city, Texas ┆ 1,495,312 ┆  6.1 ┆ 23,053,677 ┆   94.3 │
│      San Diego city, California ┆ 1,388,312 ┆  5.7 ┆ 24,441,989 ┆  100.0 │
└─────────────────────────────────┴───────────┴──────┴────────────┴────────┘

Here we tabulate the cities with populations of 1M+ using the 2023 ACS 1-year estimates. Note that we don’t include NAME in set_variables()–it’s carried through because of include_names=True, and we can reference it in tabulate() and it will be included in our output data via the to_* methods.

Citation

BibTeX citation:

@online{couzens2025,
  author = {Couzens, Lance},
  title = {Cendat Ver 0.4.5},
  date = {2025-08-27},
  url = {https://mostlyunoriginal.github.io/posts/2025-08-27-now-with-names/},
  langid = {en}
}

For attribution, please cite this work as:

Couzens, Lance. 2025. “Cendat Ver 0.4.5.” August 27, 2025. https://mostlyunoriginal.github.io/posts/2025-08-27-now-with-names/.