CensusForge

[!IMPORTANT]
Project development has moved to Codeberg

[!WARNING]
This project is still in development and may change very quickly. I will add more functionality in the future but this contains the bare minimum to support the needs of the project.

CensusForge is a Python toolkit for retrieving data from the U.S. Census API while also leveraging a local SQLite metadata database for fast lookups, the SQLite database creation repo can be found in this link in GitHub. It simplifies working with Census datasets by providing a unified interface for:

• Downloading and caching geographic files
• Querying the Census API
• Looking up dataset, variable, year, and geography metadata
• Returning results as Polars or GeoPandas objects

CensusForge consists of two main classes:

• DataPull – Handles local metadata queries and file downloads
• CensusAPI – Extends DataPull and adds direct Census API querying

Installation

pip install CensusForge

Quick Start Example

The following example shows how to query the Census API using the CensusAPI class.

from CensusForge import CensusAPI

def main():
    ca = CensusAPI()
    print(
        ca.query(
            dataset="acs-acs1-pumspr",
            year=2019,
            params_list=["AGEP", "SCH", "SCHL", "HINCP", "PWGTP", "PUMA"],
        )
    )

if __name__ == "__main__":
    main()

Running the above will:

1. Look up the dataset in the local metadata database
2. Construct the correct Census API URL
3. Fetch the API response
4. Convert it to a Polars DataFrame

Project Structure

CensusForge/
│
├── CensusAPI.py       # CensusAPI and DataPull classes
├── database.db        # Local SQLite metadata database
├── jp_tools/          # Utility functions (e.g., file download helper)
│
├── data/              # Output directory for downloaded/cached files
└── README.md          # Project documentation

API Overview

CensusAPI

query(dataset, params_list, year, extra="") → pl.DataFrame

Query a Census dataset using any set of variables or geography parameters.

Example

ca.query(
    dataset="acs-acs1-pumspr",
    year=2019,
    params_list=["AGEP", "HINCP", "PUMA"],
    extra="&for=state:*"
)

Metadata Helpers (inherited from DataPull)

Geospatial Tools

pull_geos(url, filename) → gpd.GeoDataFrame

Downloads a geographic file (if missing), caches it as Parquet, and returns a GeoDataFrame.

Requirements

• Python 3.9+
• DuckDB
• GeoPandas
• Polars
• Requests
• jp_tools (for download helper)

Install dependencies:

pip install -r requirements.txt

Development

To run tests or modify the project:

git clone https://github.com/yourusername/CensusForge.git
cd CensusForge
pip install -e .

Cite

@software{ouslan2026censusforge,
    author       = {Ouslan, Alejandro},
    title        = {CensusForge},
    month        = jan,
    year         = 2026,
    publisher    = {Zenodo},
    version      = {0.5.0},
    doi          = {10.5281/zenodo.18121581},
    url          = {https://doi.org/10.5281/zenodo.18121581}
}

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You may copy, modify, and distribute this software only under the terms of the GPL-3.0 license.

Full license text: https://www.gnu.org/licenses/gpl-3.0.en.html