EPWForge API
Programmatic access to EPW file generation, future climate morphing, design day data, station catalog, and per-model ensembles.
Prefer AI-agent integration? See the MCP server → for Claude / Cursor / any MCP-aware client.
Quick Start
Most endpoints require a Bearer token in the Authorization header. API keys are free on any tier — generate one from your account page. Generation endpoints charge credits per call (1 for single EPW/DDY, 10 for ensemble); free signup includes 5 welcome credits. All endpoints are idempotent GET requests.
https://api.guzzlabs.com
All endpoints are relative to this base URL. Two public read endpoints (/stations and /guzzstations/{path}) work without auth.
Machine-readable spec available for Postman, SDK generation, and agent/tool integrations: https://api.guzzlabs.com/openapi.yaml (OpenAPI 3.1).
Endpoints at a glance
Five endpoints — three generate, two are public read paths. They share the same parameter set wherever it makes sense (lat/lon, ssp/year/percentile, uhi, events, etc.).
- /epwforge — single EPW file with any combination of options (1 credit)
- /design-day — derived ASHRAE design conditions (DDY) using the same options (1 credit)
- /ensemble-epw — per-model CMIP6 ensemble (~20 EPWs in one call) (10 credits)
- /stations — search the 17,000-station GuzzStations catalog (no auth, free)
- /guzzstations/{path}.epw — fetch a published EPW or DDY by path (no auth, free)
Authentication & Credits
API keys are free on any tier (including Free). The constraint isn't access — it's credits, which generation endpoints consume per call.
| Plan | Monthly credits | Rate limit | $/credit |
|---|---|---|---|
| Free | 0 (+ 5 lifetime welcome) | 2 / min | — |
| Starter — $49/mo | 10 | 5 / min | $4.90 |
| Pro — $149/mo | 50 | 10 / min | $2.98 |
| Pro+ — $249/mo | 100 | 30 / min | $2.49 |
Credit cost per call: 1 for single EPW / DDY (unmodified TMY is free), 10 for ensemble. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and (on 429) Retry-After. Pricing →
Endpoints
GET /epwforge
The primary endpoint for all weather file downloads. Returns a ready-to-use EPW file with any combination of options: TMYx or AMY basis, future climate morphing (SSP scenarios), UHI adjustment, and extreme weather event injection. All parameters are optional except lat and lon.
Parameter dependencies: year requires ssp; percentile applies only when ssp is provided; amy_year applies only when basis=amy. When multiple events are provided, they are applied sequentially to the running EPW result.
Most requests return within 1–2 seconds depending on parameters and location.
| Parameter | Type | Default | Description |
|---|---|---|---|
| lat | number | — | Latitude (-90 to 90), required |
| lon | number | — | Longitude (-180 to 180), required |
| basis | string | tmy | "tmy" or "amy" |
| amy_year | integer | current | Year for AMY basis |
| tmy_period | string | 2011-2025 | Synthesized TMYx vintage when basis=tmy. One of: full (1950-2025), 2011-2025 (default — recent 15yr, captures post-2010 warming), 2009-2023, 2007-2021 (matches OneBuilding TMYx 2007-2021 standard for direct comparison), 2004-2018. |
| ssp | string | — | ssp126, ssp245, ssp370 (ssp585 deprecated per CMIP7 — use ssp370) |
| year | integer | — | 2030, 2050, 2070, 2090 (with ssp) |
| percentile | integer | 50 | 5, 10, 25, 50, 75, 90, 95 |
| uhi | string | none | suburban, urban, dense_urban |
| events | string | — | heatwave, coldsnap, hothumid, coldwindy (comma-separated) |
| include_ddy | boolean | false | Include DDY in JSON response |
| format | string | epw | "epw" → binary file download; "json" → metadata + base64-encoded EPW content |
GET /design-day
Generate ASHRAE design day (DDY) files for EnergyPlus. Accepts the same morphing, UHI, and event options as /epwforge. Without SSP parameters, returns baseline design conditions.
GET /ensemble-epw 10 credits
Generate a per-model CMIP6 ensemble — one morphed EPW per climate model (up to ~20 files). Each file uses that model's physically consistent delta set, enabling true inter-model uncertainty analysis. Returns JSON with base64-encoded EPW files.
Ensemble responses can be 10–15 MB and take 30–60 seconds. Bump your client timeout to ≥ 90s.
GET /stations no auth · free
Search the 17,000-station GuzzStations catalog (our self-hosted mirror of the OneBuilding TMYx library). No API key required.
Query params: q (city/state search), lat+lon (proximity sort), country (ISO 3-letter filter), limit (default 50, max 500). Each station returns an epw_url ready to fetch.
GET /guzzstations/{path}.epw no auth · free
Fetch a published EPW or DDY file from the GuzzStations library by relative path. Theepw_url returned by /stations points here. Light IP rate limit (60/min); 24-hour CDN cache.
Response Formats
By default, weather endpoints return the EPW file directly as a binary download (Content-Type: application/octet-stream, Content-Disposition: attachment) — ready to drop into EnergyPlus, IES, eQUEST (via a third-party BIN converter), or any building energy simulation tool.
Pass format=json to receive JSON with metadata and base64-encoded EPW content (Content-Type: application/json), useful when your workflow needs to inspect parameters before saving.
Error Codes
All errors return JSON with a single error field describing what went wrong:
| Code | Meaning |
|---|---|
| 400 | Invalid or missing parameters |
| 401 | Missing or invalid API key |
| 402 | Insufficient credits — buy more at /pricing or wait for next monthly refresh |
| 429 | Rate limit exceeded — check Retry-After |
| 500 | Server error — try again or contact support |