<div
align='center'
>
<img src="https://raw.githubusercontent.com/blaylockbk/SynopticPy/main/images/SynopticPy_logo.png" width=50%>
# ☁ Synoptic API for Python (_unofficial_)
<!-- Badges -->
[](https://pypi.python.org/pypi/SynopticPy/)
[](https://zenodo.org/badge/latestdoi/288617886)
[](https://github.com/psf/black)
[](https://synopticpy.readthedocs.io/?badge=latest)
[](https://pypi.org/project/SynopticPy/)
</div>
The [Synoptic Mesonet API](https://synopticdata.com/mesonet-api) (formerly MesoWest) gives you access to real-time and historical surface-based weather and environmental observations for thousands of stations.
# 📔 [SynopticPy Documentation](https://synopticpy.readthedocs.io/)
Synoptic data access is [_free_](https://synopticdata.com/news/2022/3/15/synoptic-data-pbc-launches-new-open-access-weather-data-service) for open-access data. More data and enhances services are available through a [paid tier](https://synopticdata.com/pricing) (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](https://pandas.pydata.org/docs/)**. 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](https://github.com/mesowx/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](https://synopticpy.readthedocs.io/en/latest/user_guide/contribute.html)
- [💬 Discussions](https://github.com/blaylockbk/SynopticPy/discussions)
- [🐛 Issues](https://github.com/blaylockbk/SynopticPy/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
---
<br><br><br>
# 🐍 Installation
## Option 1: conda (recommended)
If conda environments are new to you, I suggest you become familiar with [managing conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
I have provided a sample Anaconda [environment.yml](https://github.com/blaylockbk/SynopticPy/blob/main/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.
```yaml
- pip:
- git+https://github.com/blaylockbk/SynopticPy.git # for latest updates
#- SynopticPy # for latest release
```
First, create the virtual environment with
```bash
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.
```bash
conda activate synoptic
```
Occasionally, you might want to update all the packages in the environment.
```bash
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.
```bash
pip install SynopticPy
```
# 🔨 Setup
After following the setup instructions in the [documentation](https://synopticpy.readthedocs.io/en/latest/user_guide/setup.html), 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](https://synopticpy.readthedocs.io/en/latest/user_guide/examples.html)
- [Reference Guide](https://synopticpy.readthedocs.io/en/latest/reference_guide/index.html)
- [Jupyter Notebooks](https://github.com/blaylockbk/SynopticPy/tree/main/notebooks)
> TODO: Move these notebooks to the docs.
```python
# Import all functions
import synoptic.services as ss
```
or
```python
# 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:
```python
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).
```python
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...
```python
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](https://github.com/blaylockbk/SynopticPY/discussions/categories/show-and-tell)! 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)
Raw data
{
"_id": null,
"home_page": "https://github.com/blaylockbk/SynopticPy",
"name": "SynopticPy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "meteorology,weather,mesonet",
"author": "Brian K. Blaylock",
"author_email": "blaylockbk@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c2/9a/97baf4f3761af8446e1f6e0725704f29eae585c3be24c74734c5d0c4a5e9/SynopticPy-2023.3.0.tar.gz",
"platform": "any",
"description": "<div\r\n align='center'\r\n>\r\n\r\n<img src=\"https://raw.githubusercontent.com/blaylockbk/SynopticPy/main/images/SynopticPy_logo.png\" width=50%>\r\n\r\n# \u2601 Synoptic API for Python (_unofficial_)\r\n\r\n<!-- Badges -->\r\n\r\n[](https://pypi.python.org/pypi/SynopticPy/)\r\n\r\n[](https://zenodo.org/badge/latestdoi/288617886)\r\n\r\n\r\n[](https://github.com/psf/black)\r\n[](https://synopticpy.readthedocs.io/?badge=latest)\r\n[](https://pypi.org/project/SynopticPy/)\r\n\r\n</div>\r\n\r\nThe [Synoptic Mesonet API](https://synopticdata.com/mesonet-api) (formerly MesoWest) gives you access to real-time and historical surface-based weather and environmental observations for thousands of stations.\r\n\r\n# \ud83d\udcd4 [SynopticPy Documentation](https://synopticpy.readthedocs.io/)\r\n\r\nSynoptic data access is [_free_](https://synopticdata.com/news/2022/3/15/synoptic-data-pbc-launches-new-open-access-weather-data-service) for open-access data. More data and enhances services are available through a [paid tier](https://synopticdata.com/pricing) (available through Synoptic, not me).\r\n\r\n> ### \ud83c\udf10 Register for a free account at the Synoptic API Webpage\r\n>\r\n> > https://developers.synopticdata.com\r\n>\r\n> You will need to obtain an API token before using this python package.\r\n\r\nI wrote these functions to conveniently access data from the Synoptic API and convert the JSON data to a **[Pandas DataFrame](https://pandas.pydata.org/docs/)**. 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](https://github.com/mesowx/MesoPy) python wrapper, but returning the data as a Pandas DataFrame instead of a simple dictionary, making the retrieved data more _ready-to-use_.\r\n\r\n- [\ud83d\udc68\ud83c\udffb\u200d\ud83c\udfed Contributing Guidelines and Disclaimer](https://synopticpy.readthedocs.io/en/latest/user_guide/contribute.html)\r\n- [\ud83d\udcac Discussions](https://github.com/blaylockbk/SynopticPy/discussions)\r\n- [\ud83d\udc1b Issues](https://github.com/blaylockbk/SynopticPy/issues)\r\n\r\nIf you have stumbled across this package, I hope it is useful to you or at least gives you some ideas.\r\n\r\n**Best of Luck \ud83c\udf40** \r\n-Brian\r\n\r\n---\r\n\r\n<br><br><br>\r\n\r\n# \ud83d\udc0d Installation\r\n\r\n## Option 1: conda (recommended)\r\n\r\nIf conda environments are new to you, I suggest you become familiar with [managing conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).\r\n\r\nI have provided a sample Anaconda [environment.yml](https://github.com/blaylockbk/SynopticPy/blob/main/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.\r\n\r\n```yaml\r\n- pip:\r\n - git+https://github.com/blaylockbk/SynopticPy.git # for latest updates\r\n #- SynopticPy # for latest release\r\n```\r\n\r\nFirst, create the virtual environment with\r\n\r\n```bash\r\nwget https://raw.githubusercontent.com/blaylockbk/SynopticPy/main/environment.yml\r\nconda env create -f environment.yml\r\n```\r\n\r\nThen, activate the `synoptic` environment. Don't confuse this _environment_ name with the _package_ name.\r\n\r\n```bash\r\nconda activate synoptic\r\n```\r\n\r\nOccasionally, you might want to update all the packages in the environment.\r\n\r\n```bash\r\nconda env update -f environment.yml\r\n```\r\n\r\n## Option 2: pip\r\n\r\nInstall the last published version from PyPI. It's optional, but you will likely want `cartopy` too.\r\n\r\n```bash\r\npip install SynopticPy\r\n```\r\n\r\n# \ud83d\udd28 Setup\r\n\r\nAfter following the setup instructions in the [documentation](https://synopticpy.readthedocs.io/en/latest/user_guide/setup.html), you should either have an environmental variable named `SYNOPTIC_TOKEN` or a file at `~/.config/SynopticPy/config.toml` that looks something like this:\r\n\r\n```\r\n[default]\r\nverbose = true\r\nhide_token = true\r\nrename_value_1 = true\r\nrename_set_1 = true\r\ntoken = \"1234567890abcdefghijklmnopqrstuvwxyz\"\r\n```\r\n\r\nIf you don't do this step, don't worry. When you import `synoptic.services`,\r\na quick check will make sure the token in the config file is valid. If not,\r\nyou will be prompted to update the token in the config file.\r\n\r\n# Quick Examples\r\n\r\n- [User Guide Examples](https://synopticpy.readthedocs.io/en/latest/user_guide/examples.html)\r\n- [Reference Guide](https://synopticpy.readthedocs.io/en/latest/reference_guide/index.html)\r\n- [Jupyter Notebooks](https://github.com/blaylockbk/SynopticPy/tree/main/notebooks)\r\n\r\n> TODO: Move these notebooks to the docs.\r\n\r\n```python\r\n# Import all functions\r\nimport synoptic.services as ss\r\n```\r\n\r\nor\r\n\r\n```python\r\n# Import a single function (prefered)\r\nfrom synoptic.services import stations_timeseries\r\n```\r\n\r\nGet a timeseries of air temperature and wind speed at the station WBB for the last 10 hours:\r\n\r\n```python\r\nfrom datetime import timedelta\r\nfrom synoptic.services import stations_timeseries\r\n\r\ndf = stations_timeseries(\r\n stid='WBB',\r\n vars=['air_temp', 'wind_speed'],\r\n recent=timedelta(hours=10)\r\n)\r\n```\r\n\r\n\r\n\r\nGet 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).\r\n\r\n```python\r\nfrom synoptic.services import stations_latest\r\n\r\ndf = stations_latest(\r\n stid=['WBB', 'KMRY'],\r\n vars=['air_temp', 'wind_speed'],\r\n within=60\r\n)\r\n```\r\n\r\n\r\n\r\nGet the air temperature and wind speed for WBB and KMRY nearest 00:00 UTC Jan 1, 2020 within one hour...\r\n\r\n```python\r\nfrom datetime import datetime\r\nfrom synoptic.services import stations_nearesttime\r\n\r\ndf = stations_latest(\r\n stid=['WBB', 'KMRY'],\r\n vars=['air_temp', 'wind_speed'],\r\n attime=datetime(2020,1,1),\r\n within=60\r\n)\r\n```\r\n\r\n\r\n\r\n# How to Cite and Acknowledge\r\n\r\nIf SynopticPy played an important role in your work, please [tell me about it](https://github.com/blaylockbk/SynopticPY/discussions/categories/show-and-tell)! Also, consider including a citation or acknowledgement in your article or product.\r\n\r\n**_Suggested Citation_**\r\n\r\n> Blaylock, B. K. (2021). SynopticPy: Synoptic API for Python (Version 0.0.7) [Computer software]. https://github.com/blaylockbk/SynopticPy\r\n\r\n**_Suggested Acknowledgment_**\r\n\r\n> A portion of this work used code generously provided by Brian Blaylock's SynopticPy python package (https://github.com/blaylockbk/SynopticPy)\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Load mesonet weather and environmental data from the Synoptic API into a Pandas Dataframe.",
"version": "2023.3.0",
"split_keywords": [
"meteorology",
"weather",
"mesonet"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c39eb81edc5890d9e4160f5f743ade5398b74dc6cf627b805e81316816ff6cf0",
"md5": "cb4239470ee5f83e8f5df2336398b60a",
"sha256": "fbb003da8cb51d9e89872ee94644abd2aa4ec19509450604d366d26430917355"
},
"downloads": -1,
"filename": "SynopticPy-2023.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cb4239470ee5f83e8f5df2336398b60a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22436,
"upload_time": "2023-03-29T15:33:11",
"upload_time_iso_8601": "2023-03-29T15:33:11.080574Z",
"url": "https://files.pythonhosted.org/packages/c3/9e/b81edc5890d9e4160f5f743ade5398b74dc6cf627b805e81316816ff6cf0/SynopticPy-2023.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c29a97baf4f3761af8446e1f6e0725704f29eae585c3be24c74734c5d0c4a5e9",
"md5": "30b81b9d1bfec5afab578744dade404c",
"sha256": "8e2bcdce432aa58f633e37893606401ca72495f9b49f8ce09aaa445aa64368e1"
},
"downloads": -1,
"filename": "SynopticPy-2023.3.0.tar.gz",
"has_sig": false,
"md5_digest": "30b81b9d1bfec5afab578744dade404c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27624,
"upload_time": "2023-03-29T15:33:13",
"upload_time_iso_8601": "2023-03-29T15:33:13.219053Z",
"url": "https://files.pythonhosted.org/packages/c2/9a/97baf4f3761af8446e1f6e0725704f29eae585c3be24c74734c5d0c4a5e9/SynopticPy-2023.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-29 15:33:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "blaylockbk",
"github_project": "SynopticPy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "synopticpy"
}
JSON
