SynopticPy 2023.3.0

Load mesonet weather and environmental data from the Synoptic API into a Pandas Dataframe.

☁ Synoptic API for Python (unofficial)

The Synoptic Mesonet API (formerly MesoWest) gives you access to real-time and historical surface-based weather and environmental observations for thousands of stations.

📔 SynopticPy Documentation

Synoptic data access is free for open-access data. More data and enhances services are available through a paid tier (available through Synoptic, not me).

🌐 Register for a free account at the Synoptic API Webpage

https://developers.synopticdata.com

You will need to obtain an API token before using this python package.

I wrote these functions to conveniently access data from the Synoptic API and convert the JSON data to a Pandas DataFrame. This may be helpful to others who are getting started with the Synoptic API and Python. The idea is loosely based on the obsolete MesoPy python wrapper, but returning the data as a Pandas DataFrame instead of a simple dictionary, making the retrieved data more ready-to-use.

• 👨🏻‍🏭 Contributing Guidelines and Disclaimer
• 💬 Discussions
• 🐛 Issues

If you have stumbled across this package, I hope it is useful to you or at least gives you some ideas.

Best of Luck 🍀
-Brian

---

🐍 Installation

Option 1: conda (recommended)

If conda environments are new to you, I suggest you become familiar with managing conda environments.

I have provided a sample Anaconda environment.yml file that lists the minimum packages required plus some extras that might be useful when working with other types of weather data. Look at the bottom lines of that yaml file...there are two ways to install SynopticPy with pip. Comment out the line you don't want.

- pip:
    - git+https://github.com/blaylockbk/SynopticPy.git # for latest updates
    #- SynopticPy  # for latest release

First, create the virtual environment with

wget https://raw.githubusercontent.com/blaylockbk/SynopticPy/main/environment.yml
conda env create -f environment.yml

Then, activate the synoptic environment. Don't confuse this environment name with the package name.

conda activate synoptic

Occasionally, you might want to update all the packages in the environment.

conda env update -f environment.yml

Option 2: pip

Install the last published version from PyPI. It's optional, but you will likely want cartopy too.

pip install SynopticPy

🔨 Setup

After following the setup instructions in the documentation, you should either have an environmental variable named SYNOPTIC_TOKEN or a file at ~/.config/SynopticPy/config.toml that looks something like this:

[default]
verbose = true
hide_token = true
rename_value_1 = true
rename_set_1 = true
token = "1234567890abcdefghijklmnopqrstuvwxyz"

If you don't do this step, don't worry. When you import synoptic.services, a quick check will make sure the token in the config file is valid. If not, you will be prompted to update the token in the config file.

Quick Examples

• User Guide Examples
• Reference Guide
• Jupyter Notebooks

TODO: Move these notebooks to the docs.

# Import all functions
import synoptic.services as ss

or

# Import a single function (prefered)
from synoptic.services import stations_timeseries

Get a timeseries of air temperature and wind speed at the station WBB for the last 10 hours:

from datetime import timedelta
from synoptic.services import stations_timeseries

df = stations_timeseries(
    stid='WBB',
    vars=['air_temp', 'wind_speed'],
    recent=timedelta(hours=10)
)

Get the latest air temperature and wind speed data for WBB (University of Utah) and KRMY (Monterey, CA airport) within one hour (with windin given as an interger in minutes, this may also be a timedelta object instead).

from synoptic.services import stations_latest

df = stations_latest(
    stid=['WBB', 'KMRY'],
    vars=['air_temp', 'wind_speed'],
    within=60
)

Get the air temperature and wind speed for WBB and KMRY nearest 00:00 UTC Jan 1, 2020 within one hour...

from datetime import datetime
from synoptic.services import stations_nearesttime

df = stations_latest(
    stid=['WBB', 'KMRY'],
    vars=['air_temp', 'wind_speed'],
    attime=datetime(2020,1,1),
    within=60
)

How to Cite and Acknowledge

If SynopticPy played an important role in your work, please tell me about it! Also, consider including a citation or acknowledgement in your article or product.

Suggested Citation

Blaylock, B. K. (2021). SynopticPy: Synoptic API for Python (Version 0.0.7) [Computer software]. https://github.com/blaylockbk/SynopticPy

Suggested Acknowledgment

A portion of this work used code generously provided by Brian Blaylock's SynopticPy python package (https://github.com/blaylockbk/SynopticPy)