Future Weather Logo
View on PyPI Sign Up · 5 Free Credits
Integrations
Python package

Generate future weather files from any Python environment

No browser, no manual downloads, just pip install and five lines of code. Generate climate-adjusted EPW, DDY, and STAT weather files from notebooks, scripts, CI pipelines, and simulation workflows.

Learn More Sign Up · 5 Free Credits
Uses the same FutureWeather API as the web app. Jobs typically finish in under a minute.
quickstart.py 
import futureweather

paths = futureweather.generate(
    api_key="fw_your_key_here",
    epw="path/to/historical.epw",
    year=2050,
    scenario="ssp585",
    output_dir="./future_weather/",
)
Zero dependencies Python 3.8+ Batch generation Blocking or async workflows

Overview

The futureweather Python package is a lightweight API client that lets you generate future-adjusted EPW, DDY, and STAT weather files directly from Python. It works anywhere Python runs, including Jupyter notebooks, OpenStudio scripting workflows, Grasshopper CPython components, CI/CD pipelines, and standalone scripts.

Under the hood, it calls the same FutureWeather API that powers the web app, using your Personal Access Token for authentication. For most workflows, you can submit a job, wait for completion automatically, and download the output files to disk in a single function call.

Simple by default

Use futureweather.generate() when you want one call that uploads, polls, and downloads results automatically.

Flexible when needed

Drop down to submit, check status, and download steps separately when you need non-blocking or custom orchestration.

Zero dependencies using only the Python standard library
Python 3.8+ support
Single-job and batch generation across multiple years and scenarios
Blocking workflows with automatic polling
Non-blocking workflows for advanced integrations

How it works

1. Install the package

Install with pip. No extra dependencies or environment setup required.

pip install futureweather

2. Create a FutureWeather account

If you do not already have one, sign up at app.futureweather.co.

3. Generate an API key

Sign in, open API Docs, go to the API Keys tab, click Create New Key, and copy the token that starts with fw_.

4. Generate your first file

Call futureweather.generate(). The function blocks while the job runs, then downloads the result files to your output directory.

API key steps

1. Sign in to app.futureweather.co
2. In the left sidebar, click API Docs
3. Open the API Keys tab
4. Click Create New Key
5. Name the key and click Create
6. Copy the key and store it somewhere safe. You will not be able to see it again after closing the dialog.
first-run.py 
import futureweather

paths = futureweather.generate(
    api_key="fw_your_key_here",
    epw="path/to/historical.epw",
    year=2050,
    scenario="ssp585",
    output_dir="./future_weather/",
)

print(paths)
# ['./future_weather/historical_2050_ssp585.epw',
#  './future_weather/historical_2050_ssp585.stat']

Examples

Generate a single future EPW

single_epw.py 
import futureweather

paths = futureweather.generate(
    api_key="fw_your_key_here",
    epw="Chicago_OHare.epw",
    year=2050,
    scenario="ssp585",
    output_dir="./future/",
)

Generate a future EPW + DDY

Provide a historical DDY file to also generate a future-adjusted design day file for HVAC sizing.

epw_and_ddy.py 
paths = futureweather.generate(
    api_key="fw_your_key_here",
    epw="Chicago_OHare.epw",
    ddy="Chicago_OHare.ddy",
    year=2050,
    scenario="ssp585",
    output_dir="./future/",
)
# Returns EPW + DDY + STAT files

Batch generation

Generate every combination of years and scenarios in a single call.

batch.py 
results = futureweather.batch(
    api_key="fw_your_key_here",
    epw="Chicago_OHare.epw",
    years=[2050, 2080],
    scenarios=["ssp245", "ssp585"],
    output_dir="./future_weather/",
)

print(results["summary"])  # "4/4 completed"
directory-structure.txt 
future_weather/
├── 2050_ssp245/
│   ├── Chicago_OHare.epw
│   └── Chicago_OHare.stat
├── 2050_ssp585/
│   ├── Chicago_OHare.epw
│   └── Chicago_OHare.stat
├── 2080_ssp245/
│   └── ...
└── 2080_ssp585/
    └── ...

Check your credit balance

credits.py 
me = futureweather.authenticate("fw_your_key_here")
print(f"Credits remaining: {me['credits']}")

Advanced: non-blocking workflow

advanced_async.py 
import futureweather

# Submit the job (returns immediately)
result = futureweather.submit_job(
    "fw_your_key_here", "Chicago_OHare.epw", 2050, scenario="ssp585"
)
job_id = result["jobs"][0]["id"]
print(f"Job submitted: {job_id}")

# Check status (poll as needed)
status = futureweather.check_status("fw_your_key_here", job_id)
print(status["status"])  # PENDING, RUNNING, SUCCESS, FAILED

# When status is SUCCESS, download the files
paths = futureweather.download_results("fw_your_key_here", job_id, "./output/")

Parameter reference

futureweather.generate()

Parameter Required Type Description
api_key Yes string Your Personal Access Token, which starts with fw_.
epw Yes string Path to a historical EPW file.
year Yes int Target future year from 2035 to 2090. A standard 30-year window (±15 years) is used around the target year to reduce statistical noise.
output_dir Yes string Directory where result files will be saved.
scenario No string CMIP6 climate scenario. Default: ssp126. Options: ssp126, ssp245, ssp370, ssp585.
ddy No string Path to a historical DDY file. If provided, a future-adjusted DDY is also generated.
models No list List of CMIP6 model IDs. By default, the package uses all 23 available models as an ensemble mean.
job_name No string Optional label for the job, visible in the web dashboard.
timeout No int Maximum seconds to wait for completion. Default: 300.

futureweather.batch()

The batch function uses the same core parameters as generate(), with years and scenarios replacing year and scenario.

Parameter Required Type Description
years Yes list of int Target future years, for example [2050, 2080].
scenarios Yes list of string Climate scenarios, for example ["ssp245", "ssp585"].
timeout No int Default: 600, which is longer to accommodate batch jobs.

futureweather.batch() returns a dict with files, credits_used, and summary.

Climate scenarios

Scenario Description Approx. warming by 2100
ssp126 Low emissions with strong mitigation ~1.8C
ssp245 Moderate emissions, roughly current trajectory ~2.7C
ssp370 High emissions with limited mitigation ~3.6C
ssp585 Very high emissions, fossil-fuel intensive ~4.4C

Target years range from 2035 to 2090.

Use cases

OpenStudio / EnergyPlus workflows

Generate a future EPW before running your simulation, then point OpenStudio or EnergyPlus at the output file to evaluate building performance under future climate conditions.

Jupyter notebooks

Run parametric climate studies interactively. Generate EPWs for multiple scenarios, then analyze and visualize the results in the same notebook.

Grasshopper / CPython

Call futureweather.generate() from a GhPython or CPython component to fetch future weather data directly inside a Grasshopper definition.

Automated pipelines

Integrate future weather generation into CI/CD jobs or batch processing scripts. The batch function makes it straightforward to generate files for an entire building portfolio.

Pricing

Each credit covers one full run: EPW + STAT report, with an optional DDY if you provide a historical one.

Credits Total Cost Per Credit Example
1 $50 $50 Single output, for example EPW + DDY for 2080 under SSP5-8.5
4 $100 $25 Forecast bundle, such as 2050 and 2075 under SSP2-4.5 and SSP5-8.5
8 $160 $20 Multi-scenario study, for example 4 years x 2 scenarios
10+ from $170 $17 Larger studies and multi-scenario portfolios

Enterprise & Partners

Running larger studies, team workflows, or partner integrations? We offer volume discounts, organization-wide purchasing, and support for enterprise and implementation partners.

Frequently Asked Questions