Skip to content

Support list of states in get_acs() state parameter #303

@chekos

Description

@chekos

Context

Currently get_acs() only accepts a single state as str | None for the state parameter. To query multiple states, users must loop:

states = ["CA", "TX", "FL", "NY"]
frames = []
for st in states:  # get_acs() accepts one state at a time
    df = pypums.get_acs(
        geography="state",
        variables="B01001_001",
        state=st,
    )
    frames.append(df)
trend = pd.concat(frames, ignore_index=True)

It would be more ergonomic to accept state: str | list[str] | None and handle the iteration internally, similar to how get_pums() already accepts a list for state:

# Desired API
df = pypums.get_acs(
    geography="state",
    variables="B01001_001",
    state=["CA", "TX", "FL", "NY"],
)

Scope

  • Update get_acs() signature to accept str | list[str] | None
  • Make separate API calls per state internally and concatenate
  • Consider applying the same pattern to get_decennial(), get_estimates(), and get_flows()
  • Update documentation examples (e.g., docs/guides/multi-year.md) to use the simpler syntax

References

  • get_pums() already accepts state: str | list[str] (see pypums/pums.py)
  • Multi-year guide workaround: docs/guides/multi-year.md:53-64

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions