{"title":"EPA eGRID ZIP Factor API Methodology","version":{"ID":"eGRID2023-Rev2","YEAR":"2023","RELEASE_DATE":"2025-06-12","RELEASE_LABEL":"June 2025","SHORT_NAME":"eGRID2023 Rev2","FULL_NAME":"eGRID2023 Rev2 (2025-06-12)","NEXT_PLANNED":"EPA has published no eGRID since 2023 Rev2. eGRID2024 from Cornerstone is available via year=2024; the default moves to it once Green-e publishes a residual mix built on eGRID2024 (decision revisited by 2027-02-01).","UPDATE_FREQUENCY":"Annual"},"description":"US electricity and fuel emission data by ZIP code: EPA eGRID emission factors, Green-e residual mix, GHG Emission Factors Hub fuel factors, EIA retail rates and hourly grid intensity.","scope":"Scope 2 location-based (EPA eGRID subregion output rates) and market-based (Green-e residual mix for electricity not covered by RECs/PPAs/green tariffs); Scope 1 stationary combustion (GHG Emission Factors Hub 2026 from Cornerstone, AR6 GWPs, by default; EPA Hub 2025 with AR5 via edition=2025). GHG Protocol Scope 2 Guidance dual reporting.","data_source":{"name":"EPA eGRID","edition":"eGRID2023 Rev2 (2025-06-12)","url":"https://www.epa.gov/egrid","summary_data":"https://www.epa.gov/egrid","download_links":{"summary_tables_pdf":"https://www.epa.gov/egrid","summary_tables_xlsx":"https://www.epa.gov/egrid"}},"mapping_methodology":{"description":"ZIP codes mapped to eGRID subregions using Census ZCTA centroids","zcta_note":"ZCTAs are Census approximations of USPS ZIP service areas. ZCTAs ≠ USPS ZIPs: ZCTAs are generalized areal representations of ZIP code service areas.","approximation_note":"EPA eGRID boundaries are representational/approximate and may not align perfectly with other geographic datasets.","census_guidance":"https://www.census.gov/programs-surveys/geography/guidance/geo-areas/zctas.html"},"endpoints":{"/api/lookup":"Emission factors (location-based + residual mix) for a ZIP code","/api/lookup/batch":"Up to 100 ZIP codes in one call","/api/lookup/by-coordinates":"Lat/lon to ZIP to emission factors","/api/calculate":"Scope 2 CO2e for ZIP + kWh, location- and market-based","/api/bulk":"CSV of ZIP codes enriched with factors and CO2e","/api/fuel-emissions":"Scope 1 stationary combustion CO2e (GHG Emission Factors Hub)","/api/compare":"Rank 2-25 sites on carbon, retail rate and cleanest window","/api/cleanest-hours":"Cleanest N-hour daily window from EIA-930","/api/intensity":"Hourly grid carbon intensity (EIA-930, up to ~1 day lag)","/api/rate":"State retail electricity rate by sector (EIA-861)","/api/utility-rate":"Utility tariffs (OpenEI URDB)","/api/plant-emissions":"Unit-level plant emissions (EPA CAMD, quarterly; latest published quarter)","/mcp":"MCP server (Streamable HTTP, 11 tools)","/openapi.json":"OpenAPI 3.0 specification","/health":"Service health check","/methodology":"This document"},"data_sources":[{"name":"EPA eGRID2023 Rev2","use":"Scope 2 location-based factors, generation mix","license":"US government work, public domain","url":"https://www.epa.gov/egrid"},{"name":"eGRID2024 (Cornerstone run of EPA eGRID code, 2026-03-12)","use":"?year=2024 factors","license":"CC-BY-4.0, attribution required","url":"https://cornerstonedata.org/blog/egrid2024"},{"name":"Green-e Residual Mix Emissions Rates, 2025 edition (2023 data)","use":"Scope 2 market-based residual mix. Green-e labels it lb CO2/MWh, but its system-mix column equals the eGRID2023 CO2e rate exactly, so it is used as CO2e","license":"Published by Center for Resource Solutions; cite the residual mix rates in your GHG accounting","url":"https://resource-solutions.org/2025-residual-mix/"},{"name":"GHG Emission Factors Hub 2026 (Cornerstone, successor to EPA's Hub)","use":"Scope 1 stationary combustion factors and GWPs (IPCC AR6), default","license":"CC-BY-4.0, attribution required","url":"https://doi.org/10.5281/zenodo.20403776"},{"name":"EPA GHG Emission Factors Hub 2025","use":"Scope 1 factors with IPCC AR5 GWPs (edition=2025)","license":"US government work, public domain","url":"https://www.epa.gov/climateleadership/ghg-emission-factors-hub"},{"name":"EIA Form 861 (monthly)","use":"State retail rates; EIA publishes with a ~2-3 month lag","license":"US government work, public domain","url":"https://www.eia.gov/electricity/data.php#sales"},{"name":"EIA-930 Hourly Electric Grid Monitor","use":"Hourly intensity and cleanest hours (up to ~1 day lag)","license":"US government work, public domain","url":"https://www.eia.gov/electricity/gridmonitor/"},{"name":"EPA CAMD (Clean Air Markets Program Data)","use":"Plant emissions (published quarterly, about 45+ days after quarter end)","license":"US government work, public domain","url":"https://campd.epa.gov/"},{"name":"OpenEI Utility Rate Database (NREL)","use":"Utility tariffs","license":"CC-BY-4.0, attribution required","url":"https://openei.org/wiki/Utility_Rate_Database"},{"name":"US Census 2020 ZCTA boundaries + EPA eGRID2023 subregion shapefile","use":"ZIP to eGRID subregion (ZCTA area centroid; scripts/build_zip_subregions.mjs)","license":"US government works, public domain","url":"https://www.epa.gov/egrid/egrid-mapping-files"},{"name":"US Census Geocoder","use":"lat/lon to ZIP (ZCTA)","license":"US government work, public domain","url":"https://geocoding.geo.census.gov/"},{"name":"GeoNames postal codes (via pgeocode)","use":"ZIP to state","license":"CC-BY-4.0, attribution required","url":"https://www.geonames.org/"},{"name":"OpenEI U.S. Electric Utility Companies and Rates: Look-up by Zipcode (2023, EIA-861 based)","use":"ZIP to serving utilities (EIA IDs) and utility average rates","license":"CC-BY-4.0, attribution required","url":"https://data.openei.org/submissions/6225"}],"units":{"source":"lb/MWh (EPA native)","api_default":"kg/kWh","conversion":"kg/kWh = lb/MWh × 0.45359237 / 1000"},"edition_policy":{"current":"eGRID2023 Rev2 (2025-06-12)","next_planned":"EPA has published no eGRID since 2023 Rev2. eGRID2024 from Cornerstone is available via year=2024; the default moves to it once Green-e publishes a residual mix built on eGRID2024 (decision revisited by 2027-02-01).","default_rationale":"Location-based factors use EPA eGRID2023 Rev2, the latest EPA edition, so they share a base year with the Green-e residual mix (market-based). eGRID2024 (Cornerstone's run of EPA's code, not an EPA release) is available with year=2024, location-based only; it differs from eGRID2023 by -10% to +12% by subregion (mean about -2%). eGRID CO2e uses IPCC AR5 GWPs (CH4 28, N2O 265); Scope 1 fuel results default to AR6 (Hub 2026).","revisit_by":"2027-02-01","update_frequency":"EPA published eGRID annually through eGRID2023; later editions come from Cornerstone (Watershed, Stanford, ERG) using EPA's open code","backwards_compatibility":"API maintains consistent response format across editions"},"attribution":"Data derived from EPA eGRID 2023 database"}