Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -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=
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]

Expand Down
38 changes: 38 additions & 0 deletions scripts/census_api.py
Original file line number Diff line number Diff line change
@@ -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)
2 changes: 2 additions & 0 deletions uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading