Skip to main content

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

Project description

☁ Synoptic API for Python (unofficial)

PyPI Conda Version DOI

License Ruff Tests (Python) Documentation Status Python Conda Recipe Conda Downloads Conda Platforms

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

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

📘 SynopticPy Documentation

📈 SynopticPy Web App

SynopticPy is a Python package that helps you get mesonet data from the Synoptic API and load the data into Pandas Dataframes. The SynopticPy web app lets you plot station data from Synoptic in your browser powered by pyscript!

SynopticPy

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.

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

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

Install with conda

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

conda install -c conda-forge synopticpy

Install with pip

Install the last published version from PyPI.

# Install latest release
pip install SynopticPy
# Install latest main branch
pip install git+https://github.com/blaylockbk/SynopticPy.git
# Install latest main branch, editable (for development)
git clone https://github.com/blaylockbk/SynopticPy.git
cd SynopticPy
pip install -e .

Optional Dependencies

It's optional, but you will likely want cartopy too. You may also want https://github.com/blaylockbk/carpenter_workshop.git

🔨 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

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. (2023). SynopticPy: Synoptic API for Python (Version 2023.3.0) [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)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

synopticpy-2024.9.0.tar.gz (1.4 MB view hashes)

Uploaded Source

Built Distribution

SynopticPy-2024.9.0-py3-none-any.whl (23.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page