A previous release had provenance metadata, but this release does not. View details.
EPW.tools
Every weather file you'll ever need.
A web application + API for generating high-quality weather files for building energy simulation, solar design, climate research, agriculture, insurance and more.
What it does
EPW.tools fuses measured station observations with global reanalysis and satellite-derived solar data to produce dense, internally consistent weather files in over a dozen formats.
| Layer | Source |
|---|---|
| Backbone | ERA5 (ECMWF) and MERRA-2 (NASA) reanalysis |
| Stations | NOAA ISD via Meteostat (~3 500 curated stations worldwide) |
| Solar | NREL NSRDB (GOES Aggregated v4) where available, Zhang–Huang fallback |
| Future climate | NASA NEX-GDDP-CMIP6 with Belcher 2005 morphing |
| Design conditions | ASHRAE Handbook of Fundamentals |
Measured station data takes priority; small gaps are interpolated; longer gaps are filled from reanalysis. Every file is run through a battery of physical-plausibility checks; the results are shown with the download.
See RESOURCES.md for the full source list and references.
Python SDK
The epwtools Python package provides a typed client for the REST API plus a
weatherproof CLI:
pip install epwtools
Quick start
from epwtools import EPWClient
client = EPWClient(api_key="your-key-here") # or set EPWTOOLS_API_KEY
# Single-year AMY
epw = client.generate(lat=40.71, lon=-74.01, year=2023, name="NewYork")
# Typical Meteorological Year
epw = client.tmy(lat=51.50, lon=-0.12, start=2005, end=2024, name="London")
# Future climate (CMIP6, SSP2-4.5, 2050)
epw = client.future(lat=48.85, lon=2.35, scenario="ssp245", horizon=2050)
# Multi-GCM ensemble (one EPW per CMIP6 model — for uncertainty bands)
epws = client.ensemble(lat=48.85, lon=2.35, scenario="ssp245", horizon=2050)
# Climate stress-test for a portfolio (no credits consumed)
table = client.portfolio_stress_test(
[{"lat": 40.71, "lon": -74.01, "label": "NYC"},
{"lat": 51.50, "lon": -0.12, "label": "London"}],
scenario="ssp245", horizon=2050,
)
Real-time progress (SSE)
resp = client._post("/generate/individual", json={...})
for ev in client.stream(resp["job_id"]):
if ev["type"] == "log":
print(" ", ev["line"])
elif ev["type"] == "status" and ev["status"] == "complete":
break
Endpoint namespaces
The client exposes every API endpoint under five thin namespaces — use them when you want to reach a specific endpoint that isn't covered by the high-level generation methods:
client.tools.uhi_adjust("base.epw", ucz="UCZ-2")
client.tools.koppen("file.epw") # → {"koppen": "Cfa", ...}
client.tools.solar_calibrate("file.epw") # PSM3 blend (US)
client.tools.gap_fill("partial.epw")
client.tools.epw_diff("a.epw", "b.epw") # → hourly delta stats
client.epw.wind_rose(job_id, "out.epw") # 16 dirs × 6 speed bins
client.epw.heatmap(job_id, "out.epw", variable="dry_bulb")
client.epw.psychro(job_id, "out.epw")
client.reports.solar("file.epw")
client.reports.viticulture("file.epw") # GDD, Huglin, Winkler
client.reports.datacenter("file.epw") # free-cooling hours
client.reports.insurance("file.epw", heat_threshold=38)
client.data.cities() # ~3,000 curated cities
client.data.stations_isd(40.7, -74.0) # NOAA ISD nearby
client.data.cmip6_models() # available GCMs
client.data.design_conditions(40.7, -74.0) # ASHRAE for nearest station
client.jobs.get(job_id)
client.jobs.cancel(job_id)
client.jobs.csv(job_id, "out.epw") # download CSV alt
Async client (for portfolio workloads)
pip install 'epwtools[aio]'
import asyncio
from epwtools import AsyncEPWClient
async def main():
async with AsyncEPWClient(api_key="...", max_concurrency=8) as client:
paths = await asyncio.gather(*[
client.generate(lat=lat, lon=lon, year=2023, name=label)
for (lat, lon, label) in PORTFOLIO
])
return paths
asyncio.run(main())
CLI
weatherproof generate --lat 39.74 --lon -104.98 --year 2022 --name Denver
weatherproof tmy --lat 40.71 --lon -74.01 --start 2005 --end 2024
weatherproof future --lat 48.85 --lon 2.35 --scenario ssp245 --horizon 2050
weatherproof export myfile.epw --format xlsx
The CLI honours EPWTOOLS_API_KEY and EPWTOOLS_API_URL env vars (or pass
--api-url). Self-hosted backends work too — just point EPWTOOLS_API_URL
at your instance.
AI assistants (MCP server)
EPW.tools ships a Model Context Protocol
server, so AI assistants (Claude Desktop, Cursor, and other MCP-capable agents)
can generate weather files directly — no browser. Tools exposed: generate_epw,
generate_tmy, generate_future_climate, generate_forecast,
get_design_conditions, get_nearest_stations, get_job_result.
Every generate_* tool takes an optional save_to folder: the EPW, DDY and STAT are
saved there under one base name, ready for EnergyPlus or OpenStudio.
get_design_conditions returns heating and cooling design conditions in one of two
modes that are never mixed: ashrae_method (the ASHRAE Handbook method, replicated
and validated) or enhanced (values at the site, for the coming decade, with 90 %
ranges). Values are free and need no key; the ASHRAE-method DDY is free and the Enhanced
DDY costs 1 credit.
Add this to your MCP client config (one line, nothing to clone — it uses uv to run on demand):
{
"mcpServers": {
"epw-tools": {
"command": "uvx",
"args": ["--from", "epwtools[mcp]", "epw-tools-mcp"],
"env": { "EPWTOOLS_API_KEY": "epw_your_key_here" }
}
}
}
Prefer pip? pip install 'epwtools[mcp]', then set the command to
epw-tools-mcp. The API base defaults to the public backend
(https://epw.tools/api); override with EPWTOOLS_API_BASE for a self-hosted
instance. Get an API key at epw.tools — most generated files
use one credit (a future-climate file uses three), and new accounts start with
free credits.
With OpenStudio-MCP (natural-language energy modelling)
OpenStudio-MCP lets an AI assistant build and simulate EnergyPlus models, but it needs a weather file on disk. Run both servers and EPW.tools supplies the weather for any location, year or future climate:
{
"mcpServers": {
"epw-tools": {
"command": "uvx",
"args": ["--from", "epwtools[mcp]", "epw-tools-mcp"],
"env": { "EPWTOOLS_API_KEY": "epw_your_key_here" }
},
"openstudio-mcp": {
"command": "docker",
"args": ["run", "--rm", "-i",
"-v", "/path/to/weather:/inputs:ro", "-v", "/path/to/runs:/runs",
"nrel/openstudio-mcp:v1.2.1", "openstudio-mcp"]
}
}
}
Then ask, for example:
- "Get a 2023 weather file for Lugano, save it to /path/to/weather, and simulate a
small office there." The assistant calls
generate_epw(..., save_to="/path/to/weather"), then OpenStudio-MCP'screate_new_building(weather_file="/inputs/Lugano_2023.epw"). - "Same office in the 2050 climate (SSP2-4.5)."
generate_future_climate(..., save_to=...). - "Size it with EPW.tools Enhanced design days."
get_design_conditions(mode="enhanced", save_to="/path/to/weather", ddy_name="Lugano_2023")replaces the DDY before the location is set.
Features
Generate
- Single-year and multi-year EPW files for any lat/lon
- Composite-year files that blend multiple seasons
- TMY selection via Sandia / Finkelstein–Schafer
- Future-climate morphing through 2100 from CMIP6 scenarios
- Ensemble runs across GCMs
- Batch processing from a CSV of locations
Modify
- Altitude / micro-climate correction (lapse rate, barometric, wind log-law)
- Monthly solar calibration against reference data
- Urban heat-island morphing
- Wildfire smoke / atmospheric attenuation overlay
Inspect
- Visualise any EPW (psychrometric, hourly, monthly)
- Validate against ASHRAE / EnergyPlus range checks
- Köppen–Geiger and ASHRAE / IECC climate-zone classification
- Heating, cooling and billing degree-day reports
- Independent solar sanity check (Zhang–Huang 2002)
Output formats
EPW, DDY, STAT, WEA (Radiance), CLM (ESP-r), PVSyst .met, CSV, JSON,
Excel, Parquet, NetCDF (CF-1.8), and a one-click .zip bundle.
Project structure
epw.tools/
├── backend/ # FastAPI + pandas + xarray
│ ├── app.py # API routes + job management
│ ├── methods.py # Core methods
│ ├── ssl_utils.py
│ ├── resources/ # Static lookup data (design conditions, etc.)
│ ├── outputs/ # Generated files (auto-created)
│ └── requirements.txt
├── frontend/ # React + Vite + Tailwind
│ ├── src/
│ │ ├── App.jsx
│ │ ├── api/client.js
│ │ ├── hooks/
│ │ └── components/
│ └── package.json
├── run_backend.py # Convenience entry point
├── RESOURCES.md # Data sources & methodology
└── README.md
Setup
Quick start (5 minutes)
Generate a single-year EPW for any lat/lon from the command line:
git clone https://github.com/your-org/epwtools.git
cd epwtools
python3 -m venv .venv && source .venv/bin/activate
pip install -r backend/requirements.txt
python run_backend.py & # backend on :8000
sleep 3
# Submit a job: New York City, 2022, with default fusion + QC
curl -X POST http://localhost:8000/api/generate/individual \
-H "Content-Type: application/json" \
-d '{"lat":40.7,"lon":-74.0,"year":2022,"location_name":"NYC"}'
# → returns {"job_id":"abc-..."}
# Poll until status=="completed", then download:
curl -s http://localhost:8000/api/jobs/abc-.../download/NYC_2022.epw -o nyc.epw
The full UI is at http://localhost:5173 after cd frontend && npm install && npm run dev.
Compare two EPWs (e.g. baseline vs UHI-morphed):
python tools/epw_diff.py base.epw morphed.epw --summary
# {"row_count":8760,"max_dT_dry_bulb":4.0,"mean_dT_dry_bulb":1.85,...}
Backend
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r backend/requirements.txt
python run_backend.py # → http://localhost:8000
Frontend
cd frontend
npm install
npm run dev # → http://localhost:5173
The Vite dev server proxies /api requests to the backend automatically.
API overview
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/generate/individual |
Single-year EPW job |
POST |
/api/generate/multi-year |
Multi-year EPW job |
POST |
/api/generate/composite |
Composite-year EPW |
POST |
/api/generate/tmy |
TMY (Sandia / Finkelstein–Schafer) |
POST |
/api/generate/future |
Future-climate (CMIP6 morphing) |
POST |
/api/generate/ensemble |
Multi-GCM ensemble |
POST |
/api/generate/metered |
Raw measured-data download |
POST |
/api/generate/csv-batch |
Bulk job from CSV |
POST |
/api/tools/altitude-correct |
Apply lapse / pressure / wind correction |
POST |
/api/tools/solar-calibrate |
Monthly solar calibration |
POST |
/api/tools/billing-dd |
Heating / cooling / billing DD |
POST |
/api/tools/koppen |
Köppen–Geiger classification |
POST |
/api/tools/solar-check |
Zhang–Huang solar cross-check |
POST |
/api/tools/export-format/{fmt} |
Export EPW to alternative format |
GET |
/api/jobs/{job_id} |
Poll job status / logs / result |
GET |
/api/jobs/{job_id}/stream |
SSE stream for real-time logs |
GET |
/api/jobs/{job_id}/download/{filename} |
Download generated file |
License
Proprietary. All rights reserved.
Metadata
Release files for epwtools 0.5.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Loss of provenance
These files do not have provenance metadata, despite files in a prior release including this data.
We recommend further investigation before installing these files. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| epwtools-0.5.4.tar.gz | 39.8 kB | Without provenance | Details for epwtools-0.5.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| epwtools-0.5.4-py3-none-any.whl | Python 3 | none | any | Details for epwtools-0.5.4-py3-none-any.whl |
Total release size: 82.2 kB
Release files / epwtools-0.5.4.tar.gz
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | epwtools-0.5.4.tar.gz |
|---|---|
| Size | 39.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dc032fed29bd495bac85de87a99dedbe43feb1e1b729c739f9c2e6673e8f5d03
|
|
BLAKE2b-256 checksum How to use checksums |
748fc39fca5df90bdf3648988edf4e64c18e476c30f5209b52cf54b5b8f2ee1f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.5.31
|
Release files / epwtools-0.5.4-py3-none-any.whl
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | epwtools-0.5.4-py3-none-any.whl |
|---|---|
| Size | 42.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9d98ba5ace616af70a508e6fbeadc85bf72766e166f32d8d316d9b5e6dace705
|
|
BLAKE2b-256 checksum How to use checksums |
d4bbed1ea4372a840580f0500543966cde3d492ba80f83c623028d0fd200bca3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.5.31
|
Security for epwtools 0.5.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Loss of provenance
A previous release of these files had provenance metadata, but this release does not.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Release comparison
- Removed 0.5.3 2 files With provenance
- Added 0.5.4 2 files Without provenance
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.