Get mesonet data from the Synoptic API services and return data as a Pandas.DataFrame. Requires a Synoptic API token
Tip
Before you get started, please become familiar with the Synoptic API developers documentation.
The fundamental method for specifying the data you query is done with station selector arguments. Below are some of the more common paramaters. Read Station Selectors in the API documents for all options and capabilities.
stidstr or listSpecify which stations you want to get data for by Station ID. May be a single ID or list of IDs. ['KSLC', 'UKBKB', 'KMRY'] or 'KSLC' statestr or listString or list of abbreviated state strings, i.e. ['UT','CA'] radiusstrOnly return stations within a great-circle distance from a specified lat/lon point or station (by STID). May be in form "lat,lon,miles" or "stid,miles" varsstr or listFilter stations by the variables they report. i.e., ['air_temp', 'wind_speed', 'wind_direction', etc.] Look at the docs for more variables. varsoperator{‘and’, ‘or’}Define how vars is understood. Default 'or' means any station with any variable is used. However, 'and' means a station must report every variable to be listed. network - intNetwork ID number. See network API service for more information. limitintSpecify how many of the closest stations you want to receive. limit=1 will only return the nearest station. bbox[lonmin, latmin, lonmax, lonmin]Get stations within a bounding box.
Specify which stations you want to get data for by Station ID. May be a single ID or list of IDs. ['KSLC', 'UKBKB', 'KMRY'] or 'KSLC'
['KSLC', 'UKBKB', 'KMRY']
'KSLC'
String or list of abbreviated state strings, i.e. ['UT','CA']
['UT','CA']
Only return stations within a great-circle distance from a specified lat/lon point or station (by STID). May be in form "lat,lon,miles" or "stid,miles"
"lat,lon,miles"
"stid,miles"
Filter stations by the variables they report. i.e., ['air_temp', 'wind_speed', 'wind_direction', etc.] Look at the docs for more variables.
['air_temp', 'wind_speed', 'wind_direction', etc.]
Define how vars is understood. Default 'or' means any station with any variable is used. However, 'and' means a station must report every variable to be listed.
vars
'or'
'and'
Network ID number. See network API service for more information.
Specify how many of the closest stations you want to receive. limit=1 will only return the nearest station.
limit=1
Get stations within a bounding box.
units{‘metric’, ‘english’}See documentation for more details on custom units selection. An example of a custom unit is units='temp|F' to set just the temperature to degrees Fahrenheit. For units='temp|K,pres|mb',temperatures to Kelvin and pressures will be in hecto Pascals (mb, or hPa). obtimezone{‘UTC’, ‘local’}Specify the time to be UTC or the station’s local time. status{‘active’, ‘inactive’}Specify if the statation is active or inactive.
See documentation for more details on custom units selection. An example of a custom unit is units='temp|F' to set just the temperature to degrees Fahrenheit. For units='temp|K,pres|mb',temperatures to Kelvin and pressures will be in hecto Pascals (mb, or hPa).
units='temp|F'
units='temp|K,pres|mb'
Specify the time to be UTC or the station’s local time.
Specify if the statation is active or inactive.
Note
These Datetimes have timezone information. When plotting, I haven’t had issues with Pandas 1.1.0 and matplotlib 3.3.0, but for earlier version, matplotlib doesn’t like the DatetimeIndex with timezone information. In that case, you can remove the datetime information with something like this:
df.index.tz_localize(None)
Functions:
auth([helpme, verbose])
auth
Return a DataFrame of authentication controls.
networks([verbose])
networks
Return a DataFrame of available Networks and their metadata
networktypes([verbose])
networktypes
Get a DataFrame of network types
qctypes([verbose])
qctypes
Return a DataFrame of available quality control (QC) types
spddir_to_uv(wspd, wdir)
spddir_to_uv
Calculate the u and v wind components from wind speed and direction.
stations_latest([verbose, rename_value_1])
stations_latest
Get the latest station data.
stations_metadata([verbose])
stations_metadata
Get station metadata for stations as a Pandas DataFrame.
stations_nearesttime([verbose, rename_value_1])
stations_nearesttime
Get station data nearest a datetime.
stations_precipitation([verbose])
stations_precipitation
Get the precipitation data.
stations_timeseries([verbose, rename_set_1])
stations_timeseries
Get station data for time series.
synoptic_api(service[, verbose])
synoptic_api
Request data from the Synoptic API.
variables([verbose])
variables
Return a DataFrame of available station variables
synoptic.services.
https://developers.synopticdata.com/mesonet/v2/auth/ https://developers.synopticdata.com/settings/
helpme (bool) – True - It might be easier to deal with generating new tokens and listing tokens on the web settings, so just return the URL to help you make these changes via web. False - Access the auth API service.
**param (keyword arguments) –
include the following (Some) –
disableToken (str) –
list ({1, 0}) –
expire (datetime) –
Examples
List all tokens
auth(helpme=False, apikey='YOUR_API_KEY', list=1)
Create new token (tokens are disabled after 10 years)
auth(helpme=False, apikey='YOUR_API_KEY')
Create new token with expiration date
auth(helpme=False, apikey='YOUR_API_KEY', expire=datetime(2021,1,1))
Disable a token (not sure why this doesn’t do anything)
auth(helpme=False, apikey='YOUR_API_KEY', disable='TOKEN')
https://developers.synopticdata.com/mesonet/v2/networks/ https://developers.synopticdata.com/about/station-network-type/
id (int or list of int) – Filter by network number.
shortname (str or list of str) – Network shortname, i.e. ‘NWS/FAA’, ‘RAWS’, ‘UTAH DOT’,
https://developers.synopticdata.com/mesonet/v2/networktypes/ https://developers.synopticdata.com/about/station-network-type/
**params (keyword arguments) –
id (int) – Select just the network type you want
https://developers.synopticdata.com/mesonet/v2/qctypes/ https://developers.synopticdata.com/about/qc/
**param (keyword arguments) – Available parameters include id and shortname
id
shortname
wspd (array_like) – Arrays of wind speed and wind direction (in degrees)
wdir (array_like) – Arrays of wind speed and wind direction (in degrees)
u and v wind components
Get the latest station data. (Very similar to the nearesttime service.)
https://developers.synopticdata.com/mesonet/v2/stations/latest/
rename_value_1 (bool) –
Option to rename the DataFrame index to not include the value_1 or value_1d in the name. I prefer that the column names strips this part of the string to more easily key in on the variables I want. For situations where there are both value_1 and value_1d for a variable, only the most recent value will be renamed.
value_1
value_1d
True: Strip value_1 from the column variable names.
False: Perserve the original index names.
**params (keyword arguments) – Synoptic API arguments used to specify the data request. Must include within.
within
within (int) – Number of minutes to consider.
params include obtimezone (Other) –
units –
any Station (and) –
parameter. (Selector) –
stations_nearesttime(attime=datetime(2020,1,1), within=60, stid='WBB')
https://developers.synopticdata.com/mesonet/v2/stations/metadata/
**params (keyword arguments) – Synoptic API arguments used to specify the data request. e.g., sensorvars, obrange, obtimezone, etc.
Others (STATION SELECTION PARAMETERS) –
https (//developers.synopticdata.com/mesonet/v2/station-selectors/) –
Get station data nearest a datetime. (Very similar to the latest service.)
https://developers.synopticdata.com/mesonet/v2/stations/nearesttime/
True: Rename the DataFrame index to not include the value_1 or value_1d in the name. I prefer these names to more easily key in on the variables I want. Where there are both value_1 and value_1d for a variable, only the most recent value will be renamed.
**params (keyword arguments) – Synoptic API arguments used to specify the data request. Must include attime and within
attime
attime (datetime) – Datetime you want to the the nearest observations for.
within (int) – How long ago is the oldest observation you want to receive, in minutes.
https://developers.synopticdata.com/mesonet/v2/stations/precipitation/
**params (keyword arguments) – Synoptic API arguments used to specify the data request. Requires start and end or recent.
https://developers.synopticdata.com/mesonet/v2/stations/timeseries/
rename_set_1 (bool) –
True: Rename the DataFrame columns to not include the set_1 or set_1d in the name. I prefer these names to more easily key in on the variables I want. Where there are both set_1 and set_1d for a variable, only the column with the most non-NaN values will be renamed.
False: Perserve the original column names.
Observations returned from the Synoptic API are returned with set numbers (“air_temp_set_1”, “air_temp_set_2”, “dew_point_temperature_set_1d”, etc.). The set number refers to a different observing method (maybe a station has two temperature sensors or two heights). The ‘d’ means the variable was derived from other data.
In my general use, I don’t usually care which variables are derived, and just want the variable that provides the most data. Almost always, I want to use set_1.
The DataFrame attribute ‘RENAMED’ is provided to show how the columns were renamed. You may also look at the ‘SENSOR_VARIABLES’ attribute for more specific information, like how each set is derived.
**params (keyword arguments) – Synoptic API arguments used to specify the data request. Must include start and end argument or recent.
start
end
recent
start (datetime) – Start and end of time series
end (datetime) – Start and end of time series
recent (int or timedelta) – If int, given as minutes for recent observations. Or, give a timedelta. For example: recent=timedelta(day=2)` or ``recent=pd.to_timedelta('1D')
recent=timedelta(day=2)` or ``recent=pd.to_timedelta('1D')
stations_timeseries(stid='WBB', recent=100) stations_timeseries(radius='UKBKB,10', vars='air_temp', recent=100) stations_timeseries(stid='KMRY', recent=60, vars='air_temp', obtimezone='Local', units='temp|F')
import matplotlib.pyplot as plt from matplotlib.dates import DateFormatter df = stations_timeseries(stid='WBB', recent=300) plt.plot(df['air_temp']) plt.plot(df['dew_point_temperature']) plt.gca().xaxis.set_major_formatter(DateFormatter('%b %d %H:%M')) plt.legend()
Request data from the Synoptic API. Returns a requests object.
References
https://developers.synopticdata.com/mesonet/v2/
https://developers.synopticdata.com/mesonet/explorer/
service (str) – API service to use, including {‘auth’, ‘latest’, ‘metadata’, ‘nearesttime’, ‘networks’, ‘networktypes’, ‘precipitation’, ‘qctypes’, ‘timeseries’, ‘variables’}
verbose ({True, False, 'HIDE', 'hide'}) – Print extra details to the screen. If ‘HIDE’, then details will be printed, but the token will be hidden.
**params (keyword arguments) – API request parameters (arguments). Lists will be converted to a comma-separated string. Datetimes (datetime or pandas) will be parsed by f-string to YYYYmmddHHMM.
A requests.models.Response object from requests.get(URL, params)
requests.models.Response
requests.get(URL, params)
To read the json data for metadata for a station
synoptic_api('metadata', stid='WBB').json()
synoptic_api('metadata', stid=['WBB', 'KSLC']).json()
https://developers.synopticdata.com/mesonet/v2/variables/ https://developers.synopticdata.com/mesonet/v2/api-variables/
**param (keyword arguments) – There are none for the ‘variables’ service.
Quick plots from the Synoptic API
map_metadata([data, verbose, ax, scale, …])
map_metadata
Plot a map of station locations returned from a stations_metadata.
map_timeseries([data, verbose, ax, scale, …])
map_timeseries
Plot a map of station locations returned from a stations_timeseries.
plot_timeseries([data, cmap, plot_kwargs, …])
plot_timeseries
Plot timeseries from multiple stations on a single plot for each variable.
plot_timeseries_wind([data, figsize])
plot_timeseries_wind
3-panel plot showing wind timeseries (wind speed/gust, direction, quiver)
synoptic.plots.
Use this to plot the locations of your requested stations on a map, but if you just need the map.
data (output from stations_metadata or None.) – The returned data from stations_metadata. If None, then the user must supply param keywords to make the API request for stations_timeseries here.
params (keyword arguments for stations_timeseries) – Parameters for stations_metadata API request. Required if data=None.
data=None
Use this to plot the locations of your requested stations on a map, but if you just need the map, don’t bother getting the timeseries data, too. Use the map_metadata function instead.
data (output from stations_timeseries or None.) – The returned data from stations_timeseries. If None, then the user must supply param keywords to make the API request for stations_timeseries here.
params (keyword arguments for stations_timeseries) – Parameters for stations_timeseries API request. Required if data=None.
cmap (str) – A matplotlib named colormap to cycle colors (e.g. ‘Spectral’, ‘Blues’). If None, use the default color cycle.
plot_kwargs (dict) – kwargs for the plotted lines
params (keyword arguments) – Same as for stations_timeseries
Consider resampling the data to smooth it out and so times with no data is not shown in the plot.
df.resample('30min').mean() df.resample('1H').mean()
SynopticPy needs to know your public Synoptic API token. You likely wont need to do anything with these functions. The first time you import a synoptic.services function, it will ask you for your API token and store that information in ~/.config/SynopticPy/config.cfg. You may edit that config file if you need. Please refer to the User Guide. for more info.
synoptic.services
~/.config/SynopticPy/config.cfg
config_token([new_token])
config_token
Update the config.cfg file with your Synoptic API token
test_token([verbose, configure_on_fail])
test_token
Test that the token can get data from Synoptic.
synoptic.get_token.
new_token (None or str) – If None, the user will be asked to input the token (default). Else, the config file will be updated with new_token.
A valid API token, if it passes test_token. Else, None.
If the test fails, the user is prompted with instructions to acquire a valid token. The user will be asked what the token is, and will save that info into the config file located at ~/.config/SynopticPy/config.cfg.
configure_on_fail (bool) –
True: Help the user update the config file with config_token
False: Do not update (prevents infinant loop if user keeps adding an invalid token).
verbose (bool) –
True: Print details as this function runs.
False: Do not print anything if the token check passes.
A valid API token