# Data sources

Retrieval date for every file below: **2026-10-26** (box time, America/Los_Angeles). Each URL was fetched and returned HTTP 200 on that date.
Nothing here is endorsed by NOAA, EIA, EPA/ENERGY STAR or the Census Bureau. Derived files in `data/clean/` are our own computations; we release them under CC BY 4.0 (attribution: the site name and a link to the data page), and the upstream data are U.S. government works.

| # | Dataset | URL | Used for | Raw file (data/raw/) | Licence / terms |
|---|---|---|---|---|---|
| 1 | NOAA ISD-Lite hourly observations, 2015-2024 (122 US airport stations, ~10 files per station) | https://noaa-isd-pds.s3.amazonaws.com/isd-lite/data/{year}/{usaf}-{wban}-{year}.gz (AWS Open Data; product page https://www.ncei.noaa.gov/products/land-based-station/integrated-surface-database) | Hourly outdoor temperature -> 5 F bins, 99% / 99.6% design temperature, HDD65 | `isd/` (gitignored, ~1,220 .gz) | NOAA Open Data Dissemination: "open to the public and can be used as desired"; attribution requested; must not state or imply NOAA endorsement; modified data must not be presented as original (https://registry.opendata.aws/noaa-isd/) |
| 2 | NOAA ISD station history | https://www.ncei.noaa.gov/pub/data/noaa/isd-history.csv | Mapping ICAO -> USAF/WBAN id, lat/lon, elevation | `isd-history.csv` | NOAA, as above |
| 3 | EIA bulk ELEC (electricity), series ELEC.REV/SALES/PRICE.{ST}-RES.M | https://www.eia.gov/opendata/bulk/ELEC.zip | Residential price: trailing-12-month revenue / sales per state (cents/kWh), latest month | `ELEC.zip` (gitignored, 300 MB), `eia_elec_res_monthly_subset.jsonl` | EIA content is in the public domain; citation requested (https://www.eia.gov/about/copyrights_reuse.php). No API key needed for bulk files. |
| 4 | EIA SEDS (State Energy Data System) prices, file pr_all.csv, codes NGRCD (natural gas), DFRCD (distillate fuel oil), PQRCD (propane), ESRCD (electricity), 2024 | https://www.eia.gov/state/seds/sep_prices/total/csv/pr_all.csv | State residential fuel prices $/MMBtu, 2024 (latest SEDS year available on the pull date) | `seds_pr_all.csv`, `seds_codes.xlsx` | EIA public domain, as above |
| 5 | EIA bulk NG and PET | https://www.eia.gov/opendata/bulk/NG.zip, https://www.eia.gov/opendata/bulk/PET.zip | Downloaded and evaluated; **not used** (weekly propane/oil series were incomplete for many states; SEDS used instead) | `NG.zip`, `PET.zip` (gitignored) | EIA public domain |
| 6 | EPA ENERGY STAR Certified Mini-Split Heat Pumps (Socrata dataset akti-mt5s; 17,944 rows on the pull date; 14,941 have cold_climate = Yes) | https://data.energystar.gov/resource/akti-mt5s (CSV: .csv) | Capacity at 47/17/5 F, COP at 5 F, HSPF2, SEER2, refrigerant, AHRI reference, brand | `es_minisplit_hp.csv`, `es_catalog.json` | U.S. EPA open data on data.energystar.gov; no licence field is published for the dataset (API field is null); treated as U.S. government public information, attribution given |
| 7 | U.S. Census 2020 ZCTA gazetteer | https://www2.census.gov/geo/docs/maps-data/data/gazetteer/2020_Gazetteer/2020_Gaz_zcta_national.zip | ZIP (ZCTA) centroid lat/lon | `2020_Gaz_zcta_national.txt` | U.S. Census Bureau, public domain |
| 8 | U.S. Census 2020 ZCTA-to-county relationship | https://www2.census.gov/geo/docs/maps-data/data/rel2020/zcta520/tab20_zcta520_county20_natl.txt | State of each ZIP (largest land-area county overlap) | `tab20_zcta520_county20_natl.txt` | U.S. Census Bureau, public domain |
| 9 | IRS Energy Efficient Home Improvement Credit page | https://www.irs.gov/credits-deductions/energy-efficient-home-improvement-credit | Text on the incentives page (credit covers property placed in service through 2025-12-31; page reviewed 2026-04-28) | not downloaded; read on 2026-10-26 | U.S. government web page, cited not copied |
| 10 | ENERGY STAR federal tax credit page | https://www.energystar.gov/about/federal-tax-credits | Same | not downloaded | as above |

## Not available / failed (not worked around)

| Source | What happened on 2026-10-26 | Consequence |
|---|---|---|
| NEEP cold-climate ASHP list (https://neep.org) | No bulk download offered; terms-of-use page returned HTTP 500 | Not used. ENERGY STAR cold-climate flag used instead. Pages say so. |
| EIA monthly electricity HTML pages | HTTP 503 | Bulk ELEC.zip used instead (worked) |
| DOE home-energy-rebates pages | HTTP 404 on the URLs tried | No rebate table |
| DSIRE (https://www.dsireusa.org) API | HTTP 403 to automated requests | No rebate table; linked as a place to look |
| ASHRAE climatic design conditions | Licensed | Replaced by our own 99% percentile from ISD-Lite (milder 10-year window) |
| Mini-split / DIY kit price history and installed cost | No public bulk source exists | Price tracker is an empty placeholder; payback calculator uses the visitor's own quotes |
| NOAA 1991-2020 normals | Not needed | ISD-Lite hourly used |

## Cleaning (scripts/)

- `fetch_isd.py` resolves 122 ICAO airports to ISD ids (latest END date, CTRY US) and downloads 2015-2024 ISD-Lite files; every download is asserted to be gzip (the old NCEI path redirects to an HTML explorer).
- `build_climate.py` -> `clean/stations_climate.csv`, `clean/station_bins_5f.json`. Missing values (-9999) dropped. Stations with <85% hourly coverage excluded (Marquette, MI was 5.5% and was removed; lowest kept: Minneapolis 87.5%).
- `build_energy.py` -> `clean/energy_prices_by_state.csv`.
- `build_products.py` -> `clean/cold_climate_systems.csv` (cold_climate = Yes, valid numbers), `clean/cold_climate_brands.csv` (brand spellings merged by slug).
- `build_reference.py` -> `clean/reference_unit.json` (medians over all cold-climate systems).
- `build_zip.py` -> `public/data/zip-index.bin` (ZIP -> nearest station, state).