import pandas as pd
import numpy as np
import xarray as xr
[docs]def get_airnow_forecast(token, date, zipcode=None, latlon=None, distance=25):
"""
This tool will get current or historical AQI values and categories for a
reporting area by either Zip code or Lat/Lon coordinate.
https://docs.airnowapi.org/
Parameters
----------
token : str
The access token for accesing the AirNowAPI web server
date : str
The date of the data to be acquired. Format is YYYY-MM-DD
zipcode : str
The zipcode of the location for the data request.
If zipcode is not defined then a latlon coordinate must be defined.
latlon : array
The latlon coordinate of the loaction for the data request.
If latlon is not defined then a zipcode must be defined.
distance : int
If no reporting are is associated with the specified zipcode or latlon,
return a forcast from a nearby reporting area with this distance (in miles).
Default is 25 miles
Returns
-------
ds : xarray.Dataset
Returns an Xarray dataset object
Example
-------
act.discovery.get_AirNow_forecast(token='XXXXXX', zipcode='60440', date='2012-05-31')
"""
# default beginning of the query url
query_url = 'https://www.airnowapi.org/aq/forecast/'
# checking is either a zipcode or latlon coordinate is defined
# if neither is defined then error is raised
if (zipcode is None) and (latlon is None):
raise NameError("Zipcode or latlon must be defined")
if zipcode:
url = query_url + (
'zipCode/?'
+ 'format=text/csv'
+ '&zipCode='
+ str(zipcode)
+ '&date='
+ str(date)
+ '&distance='
+ str(distance)
+ '&API_KEY='
+ str(token)
)
if latlon:
url = query_url + (
'latLong/?'
+ 'format=text/csv'
+ '&latitude='
+ str(latlon[0])
+ '&longitude='
+ str(latlon[1])
+ '&date='
+ str(date)
+ '&distance='
+ str(distance)
+ '&API_KEY='
+ str(token)
)
df = pd.read_csv(url)
# converting to xarray dataset object
ds = df.to_xarray()
return ds
[docs]def get_airnow_obs(token, date=None, zipcode=None, latlon=None, distance=25):
"""
This tool will get current or historical observed AQI values and categories for a
reporting area by either Zip code or Lat/Lon coordinate.
https://docs.airnowapi.org/
Parameters
----------
token : str
The access token for accesing the AirNowAPI web server
date : str
The date of the data to be acquired. Format is YYYY-MM-DD
Default is None which will pull most recent observations
zipcode : str
The zipcode of the location for the data request.
If zipcode is not defined then a latlon coordinate must be defined.
latlon : array
The latlon coordinate of the loaction for the data request.
If latlon is not defined then a zipcode must be defined.
distance : int
If no reporting are is associated with the specified zipcode or latlon,
return a forcast from a nearby reporting area with this distance (in miles).
Default is 25 miles
Returns
-------
ds : xarray.Dataset
Returns an xarray dataset object
Example
-------
act.discovery.get_AirNow_obs(token='XXXXXX', date='2021-12-01', zipcode='60440')
act.discovery.get_AirNow_obs(token='XXXXXX', latlon=[45,-87])
"""
# default beginning of the query url
query_url = 'https://www.airnowapi.org/aq/observation/'
# checking is either a zipcode or latlon coordinate is defined
# if neither is defined then error is raised
if (zipcode is None) and (latlon is None):
raise NameError("Zipcode or latlon must be defined")
# setting the observation type to either current or historical based on the date
if date is None:
obs_type = 'current'
if zipcode:
url = query_url + (
'zipCode/'
+ str(obs_type)
+ '/?'
+ 'format=text/csv'
+ '&zipCode='
+ str(zipcode)
+ '&distance='
+ str(distance)
+ '&API_KEY='
+ str(token)
)
if latlon:
url = query_url + (
'latLong/'
+ str(obs_type)
+ '/?'
+ 'format=text/csv'
+ '&latitude='
+ str(latlon[0])
+ '&longitude='
+ str(latlon[1])
+ '&distance='
+ str(distance)
+ '&API_KEY='
+ str(token)
)
else:
obs_type = 'historical'
if zipcode:
url = query_url + (
'zipCode/'
+ str(obs_type)
+ '/?'
+ 'format=text/csv'
+ '&zipCode='
+ str(zipcode)
+ '&date='
+ str(date)
+ 'T00-0000&distance='
+ str(distance)
+ '&API_KEY='
+ str(token)
)
if latlon:
url = query_url + (
'latLong/'
+ str(obs_type)
+ '/?'
+ 'format=text/csv'
+ '&latitude='
+ str(latlon[0])
+ '&longitude='
+ str(latlon[1])
+ '&date='
+ str(date)
+ 'T00-0000&distance='
+ str(distance)
+ '&API_KEY='
+ str(token)
)
df = pd.read_csv(url)
# converting to xarray
ds = df.to_xarray()
return ds
[docs]def get_airnow_bounded_obs(
token, start_date, end_date, latlon_bnds, parameters='OZONE,PM25', data_type='B', mon_type=0
):
"""
Get AQI values or data concentrations for a specific date and time range and set of
parameters within a geographic area of intrest
https://docs.airnowapi.org/
Parameters
----------
token : str
The access token for accesing the AirNowAPI web server
start_date : str
The start date and hour (in UTC) of the data request.
Format is YYYY-MM-DDTHH
end_date : str
The end date and hour (in UTC) of the data request.
Format is YYYY-MM-DDTHH
latlon_bnds : str
Lat/Lon bounding box of the area of intrest.
Format is 'minX,minY,maxX,maxY'
parameters : str
Parameters to return data for. Options are:
Ozone, PM25, PM10, CO, NO2, SO2
Format is 'PM25,PM10'
mon_type : int
The type of monitor to be returned. Default is 0
0-Permanent, 1-Mobile onlt, 2-Permanent & Mobile
data_type : char
The type of data to be returned.
A-AQI, C-Concentrations, B-AQI & Concentrations
Returns
-------
ds : xarray.Dataset
Returns an xarray dataset object
"""
verbose = 1
inc_raw_con = 1
url = (
'https://www.airnowapi.org/aq/data/?startDate='
+ str(start_date)
+ '&endDate='
+ str(end_date)
+ '¶meters='
+ str(parameters)
+ '&BBOX='
+ str(latlon_bnds)
+ '&dataType='
+ str(data_type)
+ '&format=text/csv'
+ '&verbose='
+ str(verbose)
+ '&monitorType='
+ str(mon_type)
+ '&includerawconcentrations='
+ str(inc_raw_con)
+ '&API_KEY='
+ str(token)
)
# Set Column names
names = [
'latitude',
'longitude',
'time',
'parameter',
'concentration',
'unit',
'raw_concentration',
'AQI',
'category',
'site_name',
'site_agency',
'aqs_id',
'full_aqs_id',
]
# Read data into CSV
df = pd.read_csv(url, names=names)
# Each line is a different time or site or variable so need to parse out
sites = df['site_name'].unique()
times = df['time'].unique()
variables = list(df['parameter'].unique()) + ['AQI', 'category', 'raw_concentration']
latitude = [list(df['latitude'].loc[df['site_name'] == s])[0] for s in sites]
longitude = [list(df['longitude'].loc[df['site_name'] == s])[0] for s in sites]
aqs_id = [list(df['aqs_id'].loc[df['site_name'] == s])[0] for s in sites]
# Set up the dataset ahead of time
ds = xr.Dataset(
data_vars={
'latitude': (['sites'], latitude),
'longitude': (['sites'], longitude),
'aqs_id': (['sites'], aqs_id),
},
coords={'time': (['time'], times), 'sites': (['sites'], sites)},
)
# Set up emtpy data with nans
data = np.empty((len(variables), len(times), len(sites)))
data[:] = np.nan
# For each variable, pull out the data from specific sites and times
for v in range(len(variables)):
for t in range(len(times)):
for s in range(len(sites)):
if variables[v] in ['AQI', 'category', 'raw_concentration']:
result = df.loc[(df['time'] == times[t]) & (df['site_name'] == sites[s])]
if len(result[variables[v]]) > 0:
data[v, t, s] = list(result[variables[v]])[0]
atts = {'units': ''}
else:
result = df.loc[
(df['time'] == times[t])
& (df['site_name'] == sites[s])
& (df['parameter'] == variables[v])
]
if len(result['concentration']) > 0:
data[v, t, s] = list(result['concentration'])[0]
atts = {'units': list(result['unit'])[0]}
# Add variables to the dataset
ds[variables[v]] = xr.DataArray(data=data[v, :, :], dims=['time', 'sites'], attrs=atts)
times = pd.to_datetime(times)
ds = ds.assign_coords({'time': times})
return ds