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. 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.

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])

Return a DataFrame of authentication controls.

networks([verbose])

Return a DataFrame of available Networks and their metadata

networktypes([verbose])

Get a DataFrame of network types

qctypes([verbose])

Return a DataFrame of available quality control (QC) types

spddir_to_uv(wspd, wdir)

Calculate the u and v wind components from wind speed and direction.

stations_latest([verbose, rename_value_1])

Get the latest station data.

stations_metadata([verbose])

Get station metadata for stations as a Pandas DataFrame.

stations_nearesttime([verbose, rename_value_1])

Get station data nearest a datetime.

stations_precipitation([verbose])

Get the precipitation data.

stations_timeseries([verbose, rename_set_1])

Get station data for time series.

synoptic_api(service[, verbose])

Request data from the Synoptic API.

variables([verbose])

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 and shortname

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 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.

    • 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) – Number of minutes to consider.

  • 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 and within

  • 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.

  • 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 and end argument or 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')

  • 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, **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, '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.

Returns

Return type

A requests.models.Response object from requests.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:

map_metadata([data, verbose, ax, scale, …])

Plot a map of station locations returned from a stations_metadata.

map_timeseries([data, verbose, ax, scale, …])

Plot a map of station locations returned from a stations_timeseries.

plot_timeseries([data, cmap, plot_kwargs, …])

Plot timeseries from multiple stations on a single plot for each variable.

plot_timeseries_wind([data, figsize])

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:

config_token([new_token])

Update the config.cfg file with your Synoptic API token

test_token([verbose, configure_on_fail])

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