1. What is it?¶
Is an API developed by Climate Modeling Alliance (CliMA), to allow users to download weather files without the need to interact with the user interface
2. How to use it?¶
To begin interacting with the API, you need to build the URL to make the request.
2.1 Requirements¶
Required Modules¶
Run the cell below to import the necessary modules for this guide.
import os # used to interact with the OS
import requests # used to make the request to the server using the URL
!pip install windrose
from windrose import WindroseAxes # used for the example plot
import matplotlib.pyplot as plt # visualization of plot
import pandas as pd # used to read the data in the files
import numpy as np # used to set the frequencies
3. Base URL¶
The base URL for the EcoDesign API is
https://ecodesign.clima.caltech.edu/server/. Below, we assign this URL as a string to the variable
base_url.
base_url = "https://ecodesign.clima.caltech.edu/server/"
4. Design Conditions Statistics¶
4.1 Design Standards¶
The two design condition standards made available to users are American Society of Heating, Refrigerating and Air-Conditioning Engineers (ASHRAE) and Unified Facilities Criteria (UFC).
4.2 City Code¶
Below is the list of city codes available for design condition statistics generation:
- Chicago, IL, USA. City code: CHI.
- New York, NY, USA. City code: NYC.
- Cincinnati, OH, USA. City code: CIN.
- Atlanta, GA, USA. City code: ATL.
4.3 Time Period¶
We provide data for the period 1979-2022. These values are used as the start and end year values in the construction of the URL request.
4.4 Period Type¶
The two available options are observations (obs) and projections (proj). Observations refer to historical data, whereas projected refers to future projections made.
4.5 File Type¶
The two options are CSV and JSON.
Constructing the URL¶
The general format of the design condition URL request is as follows:
Now we can create an example URL below.
# Set design condition by using user input assigned to the descon variable
descon = input("Which design condition standard should we follow: ASHRAE or UFC?")
# set the city code by using user input assigned to the city_code variable
city_code = input("Which city are you interested in?")
# set the start year by using user input assigned to the start_year variable
start_year = input("What start year are you interested in?")
# set the end year by using user input assigned to the end_year variable
end_year = input("What end year are you interested in?")
# set the period type by using user input assigned to the period_type variable
period_type = input("Which period type should we generate: obs or proj?")
# set the file type by using user input assigned to the file_type variable
file_type = input("What file type are you interested in: csv or json?")
Formatting the URL¶
# Build the url using the base url and the user inputs
request_url = f"{base_url}{descon.lower()}/{city_code.upper()}/{start_year}/{end_year}/{period_type.lower()}/{file_type.lower()}"
Downloading the file¶
def download_file_from_url(url: str):
# Function that uses the url and makes the request using the request_url
try:
# Send GET request to the URL
response = requests.get(url)
# Check if the request was successful
if response.status_code == 200:
# Extract file name from the URL
file_extension = url.split("/")[-1]
filename = url.split("/")
constructed_filename = filename[4] + "_" + filename[5] + "_" + filename[6] + "-" + filename[7] + "_" + filename[8]
# Construct the file name
file_name = f"{constructed_filename}.{file_extension}"
print(file_name)
# Define the path to the downloads folder
downloads_folder = os.path.join(os.path.expanduser("~"), "Downloads")
# Save the file to the downloads folder
file_path = os.path.join(downloads_folder, file_name)
with open(file_path, "wb") as file:
file.write(response.content)
print(f"File downloaded successfully to: {file_path}")
else:
print("Failed to download file. HTTP status code:", response.status_code)
except RequestException as e:
print("An error occurred:", str(e))
No, using the function created, we can download the file to your device's Downloads folder
download_file_from_url(request_url)
ashrae_ATL_1979-1989_obs.csv File downloaded successfully to: /Users/testuser/Downloads/ashrae_ATL_1979-1989_obs.csv
5. Meteorological Year File¶
For the meteorological files, they use the same base URL as the design conditions statistics. The only difference is with some of the options passed. Below are the explanations on the differences.
5.1 Climate File Code¶
The respective codes are amy, tmy and ftmy for actual meteorological year, typical meteorological year and future typical meteorological year.
5.2 File Type Code¶
The filetype codes are csv, epw and json.
Constructing the URL¶
The general format of the Meteorological File URLs are as follows
# Set city code by using user input assigned to the met_city_code variable
met_city_code = input("Which city are you interested in?")
# Set climate file code by using user input assigned to the climate_file_code variable
climate_file_code = input("Which climate file code: amy/tmy/ftmy?")
# Set start year by using user input assigned to the met_start_year variable
met_start_year = input("What start year are you interested in?")
# Set end year by using user input assigned to the met_end_year variable
met_end_year = input("What end year are you interested in?")
# Set file type code by using user input assigned to the file_type_code variable
file_type_code = input("What file type are you interested in: epw/csv/json?")
Formatting the URL¶
met_request_url = f"{base_url}{met_city_code.upper()}/{climate_file_code.lower()}/{met_start_year}/{met_end_year}/{file_type_code.lower()}"
Downloading the Meteorological Year File¶
def download_met_file_from_url(url):
try:
# Send GET request to the URL
response = requests.get(url)
# Check if the request was successful
if response.status_code == 200:
# Extract file name from the URL
file_extension = url.split("/")[-1]
filename = url.split("/")
constructed_filename = filename[4] + "_" + filename[5] + "_" + filename[6] + "-" + filename[7]
# Construct the file name
file_name = f"{constructed_filename}.{file_extension}"
print(file_name)
# Define the path to the downloads folder
downloads_folder = os.path.join(os.path.expanduser("~"), "Downloads")
# Save the file to the downloads folder
file_path = os.path.join(downloads_folder, file_name)
with open(file_path, "wb") as file:
file.write(response.content)
print(f"File downloaded successfully to: {file_path}")
else:
print("Failed to download file. HTTP status code:", response.status_code)
except RequestException as e:
print("An error occurred:", str(e))
download_met_file_from_url(met_request_url)
ATL_tmy_1979-1989.epw File downloaded successfully to: /Users/testuser/Downloads/ATL_tmy_1979-1989.epw
6. Now what?¶
With data from the meteorological files, for example, we can begin to visualize the data with various plots. Below is an example of a wind rose chart, which represents wind speed and direction distribution at a specific location.
def create_windrose_from_epw(filepath: str):
"""Visualize wind rose chart using provided file path."""
# Load the wind data into a DataFrame, skipping the location data
df = pd.read_csv(filepath, skiprows=8, header=None)
# Create a new wind speed and direction DataFrame
wind_data = pd.DataFrame({
'speed': df[21], # wind speed is typically in column 21
'direction': df[20] # wind direction is typically in column 20
})
ax = WindroseAxes.from_ax()
ax.bar(wind_data.direction, wind_data.speed, bins=np.arange(0.01,8,1), normed=True, opening=0.8, edgecolor='white')
ax.set_legend()
plt.show()
create_windrose_from_epw("/Users/testuser/Downloads/ATL_tmy_1979-1989.epw")
