diff --git a/.env.example b/.env.example index 8515248..293d40a 100644 --- a/.env.example +++ b/.env.example @@ -1,3 +1,6 @@ # Copy to .env (never commit .env). Used by scripts/, not by the app. # Create a key at https://aistudio.google.com/apikey and pick the project g311-communication-needs-map. GEMINI_API_KEY= + +# Free key, needed for scripts/census_api.py: https://api.census.gov/data/key_signup.html +CENSUS_API_KEY= diff --git a/README.md b/README.md index bae207f..4a4da03 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,19 @@ A blank [Streamlit](https://streamlit.io) app, plus the council district boundar | `scripts/gemini.py` | `client()` returns a Gemini client for writing summaries ahead of time. It reads `GEMINI_API_KEY` from `.env` (copy `.env.example`). | | `tests/` | [pytest](https://docs.pytest.org) tests. `test_app.py` checks the app starts without errors. | +### Census data: Census API + +`scripts/census_api.py` has `get()`, which makes one [Census Data API](https://www.census.gov/data/developers.html) call and returns a DataFrame. The API has the newest [American Community Survey](https://www.census.gov/programs-surveys/acs) 5-year estimates. Block group shapes to join with come from [TIGER/Line](https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html). + +```python +from census_api import COUNTY, STATE, get + +df = get( + "2024/acs/acs5", ["B01001_001E"], "block group:*", f"state:{STATE} county:{COUNTY}" +) +``` + +The API needs a key. Get a [free key](https://api.census.gov/data/key_signup.html) (it comes by email within minutes) and put it in `.env` as `CENSUS_API_KEY`. If Gemini replies "This model is currently experiencing high demand", change the model in `scripts/gemini.py` to an older Flash model such as `gemini-3.5-flash`. The newest model is the busiest on the free tier. The Census data source comes in a separate pull request: the BigQuery sandbox or the Census API. Merge one. diff --git a/pyproject.toml b/pyproject.toml index 5bb3194..cbf14ac 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,6 +15,7 @@ dev = [ "google-genai>=2.31.0", "pytest>=9.1.1", "python-dotenv>=1.2.4", + "requests>=2.34.2", "ruff>=0.17.1", ] diff --git a/scripts/census_api.py b/scripts/census_api.py new file mode 100644 index 0000000..04a291b --- /dev/null +++ b/scripts/census_api.py @@ -0,0 +1,38 @@ +"""The Census Data API (https://www.census.gov/data/developers.html). + +It needs a key: get a free one at https://api.census.gov/data/key_signup.html (it arrives by +email in a few minutes) and put it in .env as CENSUS_API_KEY. +Find variables at https://api.census.gov/data/2024/acs/acs5/variables.html. +""" + +import os + +import pandas as pd +import requests +from dotenv import load_dotenv + +# Cobb County, Georgia +STATE = "13" +COUNTY = "067" + + +def get( + dataset: str, variables: list[str], geography: str, within: str +) -> pd.DataFrame: + """One API call as a DataFrame. + + Example: get("2024/acs/acs5", ["B01001_001E"], "block group:*", f"state:{STATE} county:{COUNTY}") + """ + load_dotenv() + key = os.environ.get("CENSUS_API_KEY") + if not key: + raise SystemExit( + "Set CENSUS_API_KEY in .env (free key: https://api.census.gov/data/key_signup.html)" + ) + params = {"get": ",".join(variables), "for": geography, "in": within, "key": key} + response = requests.get( + f"https://api.census.gov/data/{dataset}", params=params, timeout=60 + ) + response.raise_for_status() + header, *rows = response.json() + return pd.DataFrame(rows, columns=header) diff --git a/uv.lock b/uv.lock index 42d3597..f63c908 100644 --- a/uv.lock +++ b/uv.lock @@ -316,6 +316,7 @@ dev = [ { name = "google-genai" }, { name = "pytest" }, { name = "python-dotenv" }, + { name = "requests" }, { name = "ruff" }, ] @@ -332,6 +333,7 @@ dev = [ { name = "google-genai", specifier = ">=2.31.0" }, { name = "pytest", specifier = ">=9.1.1" }, { name = "python-dotenv", specifier = ">=1.2.4" }, + { name = "requests", specifier = ">=2.34.2" }, { name = "ruff", specifier = ">=0.17.1" }, ]