A tool that fetches data from the XWeather API and generates a full year AMY (Actual Meteorological Year) EnergyPlus Weather file (EPW).
The tool takes care of fetching the necessary data from the API, processing it, and formatting it into the EPW format. It's designed for fast and efficient data retrieval.
You need to have a XWeather API access. Note that at hourly frequency (which is used for EPW generation), each day of data costs 1 API request.
Clone the current repository and install the required dependencies using Poetry:
git clone https://github.com/airboxlab/xweather2epw.git
cd xweather2epw
poetry installExample usage:
# using poetry, execute in local repository
poetry run xweather2epw fetch --from '2025-01-01' --to '2025-12-31' --latitude 49.4 --longitude 0.1 --api-key YOUR_KEY --api-secret YOUR_SECRET
# specify a custom output file
poetry run xweather2epw fetch --from '2025-01-01' --to '2025-12-31' --latitude 49.4 --longitude 0.1 --api-key YOUR_KEY --api-secret YOUR_SECRET --output my_weather.epwUse --help to have a list of available options:
poetry run xweather2epw --help
poetry run xweather2epw fetch --helpTo run the test suite:
poetry run testThis will execute all unit tests with verbose output.
- Date Range Validation: Validates input parameters (latitude, longitude, date range)
- Smart Chunking: Automatically splits requests into 15-day chunks to comply with API limits
- Date Range Limits:
- Maximum duration: 1 year (365 days)
- Forecast limit: Up to 14 days in the future
- Missing Data Handling: Uses safe default values for missing weather data
- Unit Conversion: Automatically converts units to comply with EPW format (SI units)
- EPW Header Generation: Populates EPW headers with location information from API response
- Solar Radiation Data: Extracts solar radiation data from XWeather API's
solradfield (GHI, DNI, DHI) - Sequential Processing: Processes data chunks sequentially for reliability
- Ground/soil temperatures cannot be calculated from XWeather API data, so the
GROUND TEMPERATURESheader is set to0 - Some advanced EPW fields (like extraterrestrial radiation and illuminance) are not available from the XWeather conditions endpoint and are filled with missing data indicators
- Historical data availability depends on your XWeather API subscription