Reference Guide¶
👨🏻💻 Services¶
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.
Station Selector Parameters¶
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 list
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'
- statestr or list
String or list of abbreviated state strings, i.e.
['UT','CA']
- radiusstr
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"
- varsstr or list
Filter 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 - int
Network ID number. See network API service for more information.
- limitint
Specify 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.
Other Common Parameters¶
- 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. Forunits='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.
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:
|
Return a DataFrame of authentication controls. |
|
Return a DataFrame of available Networks and their metadata |
|
Get a DataFrame of network types |
|
Return a DataFrame of available quality control (QC) types |
|
Calculate the u and v wind components from wind speed and direction. |
|
Get the latest station data. |
|
Get station metadata for stations as a Pandas DataFrame. |
|
Get station data nearest a datetime. |
|
Get the precipitation data. |
|
Get station data for time series. |
|
Request data from the Synoptic API. |
|
Return a DataFrame of available station variables |
- synoptic.services.auth(helpme=True, verbose=True, **params)¶
Return a DataFrame of authentication controls.
https://developers.synopticdata.com/mesonet/v2/auth/ https://developers.synopticdata.com/settings/
- Parameters
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')
- synoptic.services.networks(verbose=True, **params)¶
Return a DataFrame of available Networks and their metadata
https://developers.synopticdata.com/mesonet/v2/networks/ https://developers.synopticdata.com/about/station-network-type/
- Parameters
**param (keyword arguments) –
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’,
- synoptic.services.networktypes(verbose=True, **params)¶
Get a DataFrame of network types
https://developers.synopticdata.com/mesonet/v2/networktypes/ https://developers.synopticdata.com/about/station-network-type/
- Parameters
**params (keyword arguments) –
id (int) – Select just the network type you want
- synoptic.services.qctypes(verbose=True, **params)¶
Return a DataFrame of available quality control (QC) types
https://developers.synopticdata.com/mesonet/v2/qctypes/ https://developers.synopticdata.com/about/qc/
- Parameters
**param (keyword arguments) – Available parameters include
id
andshortname
- synoptic.services.spddir_to_uv(wspd, wdir)¶
Calculate the u and v wind components from wind speed and direction.
- Parameters
wspd (array_like) – Arrays of wind speed and wind direction (in degrees)
wdir (array_like) – Arrays of wind speed and wind direction (in degrees)
- Returns
- Return type
u and v wind components
- synoptic.services.stations_latest(verbose=True, rename_value_1=True, **params)¶
Get the latest station data. (Very similar to the nearesttime service.)
https://developers.synopticdata.com/mesonet/v2/stations/latest/
- Parameters
rename_value_1 (bool) –
Option to rename the DataFrame index to not include the
value_1
orvalue_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 bothvalue_1
andvalue_1d
for a variable, only the most recent value will be renamed.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 (int, timedelta, or Pandas Timedelta) – If int, given as minutes for recent observations. Or, give a timedelta or pandas timedelta
recent=timedelta(day=2)` and ``recent=pd.to_timedelta('1D')
. Or, give a pandas-recognized timedelta-string, like ‘1W’ for one week, ‘1h’ for one hour, etc.recent='1D'
for one day. See https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_timedelta.html for additional units.params include obtimezone (Other) –
units –
any Station (and) –
parameter. (Selector) –
Examples
stations_nearesttime(attime=datetime(2020,1,1), within=60, stid='WBB')
- synoptic.services.stations_metadata(verbose=True, **params)¶
Get station metadata for stations as a Pandas DataFrame.
https://developers.synopticdata.com/mesonet/v2/stations/metadata/
- Parameters
**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/) –
- synoptic.services.stations_nearesttime(verbose=True, rename_value_1=True, **params)¶
Get station data nearest a datetime. (Very similar to the latest service.)
https://developers.synopticdata.com/mesonet/v2/stations/nearesttime/
- Parameters
rename_value_1 (bool) –
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.
False: Perserve the original index names.
**params (keyword arguments) – Synoptic API arguments used to specify the data request. Must include
attime
andwithin
attime (datetime, pandas Timestamp, or pandas.to_datetime-parsable str) – Datetime you want to the the nearest observations for.
within (int, timedelta, or Pandas Timedelta) – How long ago is the oldest observation you want to receive? If int, given as minutes for recent observations. Or, give a timedelta or pandas timedelta
recent=timedelta(day=2)` and ``recent=pd.to_timedelta('1D')
. Or, give a pandas-recognized timedelta-string, like ‘1W’ for one week, ‘1h’ for one hour, etc.recent='1D'
for one day. See https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_timedelta.html for additional units.params include obtimezone (Other) –
units –
any Station (and) –
parameter. (Selector) –
Examples
stations_nearesttime(attime=datetime(2020,1,1), within=60, stid='WBB')
- synoptic.services.stations_precipitation(verbose=True, **params)¶
Get the precipitation data.
https://developers.synopticdata.com/mesonet/v2/stations/precipitation/
- Parameters
**params (keyword arguments) – Synoptic API arguments used to specify the data request. Requires start and end or recent.
params include obtimezone (Other) –
units –
any Station (and) –
parameter. (Selector) –
- synoptic.services.stations_timeseries(verbose=True, rename_set_1=True, **params)¶
Get station data for time series.
https://developers.synopticdata.com/mesonet/v2/stations/timeseries/
- Parameters
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.
Note
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.
Note
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
andend
argument orrecent
.start (datetime, pandas Timestamp, or pandas.to_datetime-parsable str) – Start and end of time series
end (datetime, pandas Timestamp, or pandas.to_datetime-parsable str) – Start and end of time series
recent (int, timedelta, or Pandas Timedelta) – If int, given as minutes for recent observations. Or, give a timedelta or pandas timedelta
recent=timedelta(day=2)` and ``recent=pd.to_timedelta('1D')
. Or, give a pandas-recognized timedelta-string, like ‘1W’ for one week, ‘1h’ for one hour, etc.recent='1D'
for one day. See https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_timedelta.html for additional units.params include obtimezone (Other) –
units –
any Station (and) –
parameter. (Selector) –
Examples
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()
- synoptic.services.synoptic_api(service, verbose=True, hide_token=True, **params)¶
Request data from the Synoptic API. Returns a requests object.
References
- Parameters
service (str) – API service to use, including {‘auth’, ‘latest’, ‘metadata’, ‘nearesttime’, ‘networks’, ‘networktypes’, ‘precipitation’, ‘qctypes’, ‘timeseries’, ‘variables’}
verbose ({True, False}) – Print extra details to the screen.
hide_token (bool) – If True, the token will be hidden when API URL is printed.
**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.
- Returns
- Return type
A
requests.models.Response
object fromrequests.get(URL, params)
Examples
To read the json data for metadata for a station
synoptic_api('metadata', stid='WBB').json()
synoptic_api('metadata', stid=['WBB', 'KSLC']).json()
- synoptic.services.variables(verbose=True, **params)¶
Return a DataFrame of available station variables
https://developers.synopticdata.com/mesonet/v2/variables/ https://developers.synopticdata.com/mesonet/v2/api-variables/
- Parameters
**param (keyword arguments) – There are none for the ‘variables’ service.
📈 Plots¶
Quick plots from the Synoptic API
Functions:
|
Plot a map of station locations returned from a |
|
Plot a map of station locations returned from a |
|
Plot timeseries from multiple stations on a single plot for each variable. |
|
3-panel plot showing wind timeseries (wind speed/gust, direction, quiver) |
- synoptic.plots.map_metadata(data=None, *, verbose=True, ax=None, scale='10m', scatter_kwargs={}, text=True, text_kwargs={}, **params)¶
Plot a map of station locations returned from a
stations_metadata
.Use this to plot the locations of your requested stations on a map, but if you just need the map.
- Parameters
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
.
- synoptic.plots.map_timeseries(data=None, *, verbose=True, ax=None, scale='10m', scatter_kwargs={}, text=True, text_kwargs={}, **params)¶
Plot a map of station locations returned from a
stations_timeseries
.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.
- Parameters
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
.
- synoptic.plots.plot_timeseries(data=None, cmap=None, plot_kwargs={'marker': '.', 'markersize': 3}, figsize=(10, 5), verbose=True, **params)¶
Plot timeseries from multiple stations on a single plot for each variable.
- Parameters
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.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
- synoptic.plots.plot_timeseries_wind(data=None, figsize=(10, 5), **params)¶
3-panel plot showing wind timeseries (wind speed/gust, direction, quiver)
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()
🎫 Synoptic API Token¶
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.
Functions:
|
Update the config.cfg file with your Synoptic API token |
|
Test that the token can get data from Synoptic. |
- synoptic.get_token.config_token(new_token=None)¶
Update the config.cfg file with your Synoptic API token
- Parameters
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.
- Returns
- Return type
A valid API token, if it passes
test_token
. Else, None.
- synoptic.get_token.test_token(verbose=True, configure_on_fail=True)¶
Test that the token can get data from Synoptic.
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
.- Parameters
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.
- Returns
- Return type
A valid API token