ndbc-api


Namendbc-api JSON
Version 0.24.12.20.1 PyPI version JSON
download
home_pageNone
SummaryA Python API for the National Data Buoy Center.
upload_time2024-12-21 02:19:43
maintainerNone
docs_urlNone
authorcdjellen
requires_python<3.13,>=3.9
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <div align="center">
    <h2>NDBC API</h2>
</div>


[![Coverage Status](https://coveralls.io/repos/github/CDJellen/ndbc-api/badge.svg?branch=main)](https://coveralls.io/github/CDJellen/ndbc-api?branch=main)
[![PyPI](https://img.shields.io/pypi/v/ndbc-api)](https://pypi.org/project/ndbc-api/#history)
[![PyPI - Status](https://img.shields.io/pypi/status/ndbc-api)](https://pypi.org/project/ndbc-api/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ndbc-api)](https://pypi.org/project/ndbc-api/)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white&style=flat-square)](https://www.linkedin.com/in/cdjellen/)
[![GitHub](https://img.shields.io/github/license/cdjellen/ndbc-api)](https://github.com/cdjellen/ndbc-api/blob/main/LICENSE)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/ndbc-api)](https://pypi.org/project/ndbc-api/)


<div align="center">
    <h3>A Python API for the National Data Buoy Center</h3>
</div>


The National Oceanic and Atmospheric Association's National Data Buoy Center maintains marine monitoring and observation stations around the world[^1]. These stations report atmospheric, oceanographic, and other meterological data at regular intervals to the NDBC. Measurements are made available over HTTP through the NDBC's data service.

The ndbc-api is a python library that makes this data more widely accessible.

The ndbc-api is primarily built to parse whitespace-delimited oceanographic and atmospheric data distributed as text files for available time ranges, on a station-by-station basis[^2]. Measurements are typically distributed as `utf-8` encoded, station-by-station, fixed-period text files. More information on the measurements and methodology are available [on the NDBC website](https://www.ndbc.noaa.gov/docs/ndbc_web_data_guide.pdf)[^3].

Please see [the included example notebook](/notebooks/overview.ipynb) for a more detailed walkthrough of the API's capabilities.

[^1]: https://www.ndbc.noaa.gov/
[^2]: https://www.ndbc.noaa.gov/obs.shtml
[^3]: https://www.ndbc.noaa.gov/docs/ndbc_web_data_guide.pdf



#### Installation
The `ndbc-api` can be installed via PIP:

```sh
pip install ndbc-api
```

Conda users can install the `ndbc-api` via the `conda-forge` channel:

```sh
conda install -c conda-forge ndbc-api
```

Finally, to install the `ndbc-api` from source, clone the repository and run the following command:

```sh
python setup.py install
```

#### Requirements
The `ndbc-api` has been tested on Python 3.6, 3.7, 3.8, 3.9, and 3.10. Python 2 support is not currently planned, but could be implemented based on the needs of the atmospheric research community.

The API uses synchronous HTTP requests to compile data matching the user-supplied parameters. The `ndbc-api` package depends on:
* requests>=2.10.0
* pandas
* bs4
* html5lib>=1.1
* xarray
* scipy

##### Development
If you would like to contribute to the growth and maintenance of the `ndbc-api`, please feel free to open a PR with tests covering your changes. The tests leverage `pytest` and depend on the above requirements, as well as:
* coveralls
* httpretty
* pytest
* pytest-cov
* pyyaml
* pyarrow

Breaking changes will be considered, especially in the current `alpha` state of the package on `PyPi`.  As the API further matures, breaking changes will only be considered with new major versions (e.g. `N.0.0`).

#### Example

The `ndbc-api` exposes public methods through the `NdbcApi` class.

```python3
from ndbc_api import NdbcApi

api = NdbcApi()
```

The `NdbcApi` provides a unified access point for NDBC data. All methods for obtaining data, metadata, and locating stations are available using the `api` object. The `get_data` method is the primary method for accessing NDBC data, and is used to retrieve measurements from a given station over a specified time range. This method can request data from the NDBC HTTP Data Service or the THREDDS data service, and return the data as a `pandas.DataFrame`, `xarray.Dataset` or python `dict` object.

Data made available by the NDBC falls into two broad categories.

1. Station metadata
2. Station measurements

The `api` supports a range of public methods for accessing data from the above categories.

##### Station metadata

The `api` has five key public methods for accessing NDBC metadata.

1. The `stations` method, which returns all NDBC stations.
2. The `nearest_station` method, which returns the station ID of the nearest station.
3. The `station` method, which returns station metadata from a given station ID.
4. The `available_realtime` method, which returns hyperlinks and measurement names for realtime measurements captured by a given station.
5. The `available_historical` method, which returns hyperlinks and measurement names for historical measurements captured by a given station.

###### `stations`

```python3
# get all stations and some metadata as a Pandas DataFrame
stations_df = api.stations()
# parse the response as a dictionary
stations_dict = api.stations(as_df=False)
```

###### `nearest_station`

```python3
# specify desired latitude and longitude
lat = '38.88N'
lon = '76.43W'

# find the station ID of the nearest NDBC station
nearest = api.nearest_station(lat=lat, lon=lon)
print(nearest_station)
```

```python3
'tplm2'
```

###### `radial_search`

```python3
# specify desired latitude, longitude, radius, and units
lat = '38.88N'
lon = '76.43W'
radius = 100
units = 'km'

# find the station IDs of all NDBC stations within the radius
nearby_stations_df = api.radial_search(lat=lat, lon=lon, radius=radius, units=units)
```

```python3
'tplm2'
```

###### `station`

```python3
# get station metadata
tplm2_meta = api.station(station_id='tplm2')
# parse the response as a Pandas DataFrame
tplm2_df = api.station(station_id='tplm2', as_df=True)
```

###### `available_realtime`

```python3
# get all available realtime measurements, periods, and hyperlinks
tplm2_realtime = api.available_realtime(station_id='tplm2')
# parse the response as a Pandas DataFrame
tplm2_realtime_df = api.available_realtime(station_id='tplm2', as_df=True)
```

###### `available_historical`

```python3
# get all available historical measurements, periods, and hyperlinks
tplm2_historical = api.available_historical(station_id='tplm2')
# parse the response as a Pandas DataFrame
tplm2_historical_df = api.available_historical(station_id='tplm2', as_df=True)
```

##### Station measurements

The `api` has two public methods which support accessing supported NDBC station measurements.

1. The `get_modes` method, which returns a list of supported `mode`s, corresponding to the data formats provided by the NDBC data service. For example, the `adcp` mode represents "Acoustic Doppler Current Profiler" measurements, providing information about ocean currents at different depths, while `cwind` represents "Continuous winds" data, offering high-frequency wind speed and direction measurements.

Note that not all stations provide the same set of measurements. The `available_realtime` and `available_historical` methods can be called on a station-by station basis to ensure a station has the desired data available, before building and executing requests with `get_data`. 

2. The `get_data` method, which returns measurements of a given type for a given station.

###### `get_modes`

```python3
# get the list of supported meterological measurement modes
modes = api.get_modes()
print(modes)
```

```python3
[
    'adcp',
    'cwind',
    'ocean',
    'spec',
    'stdmet',
    'supl',
    'swden',
    'swdir',
    'swdir2',
    'swr1',
    'swr2'
]
```

The mode values above map directly to the identifiers used buy the NDBC. Desriptions for each mode are presented below:
* `adcp`: Acoustic Doppler Current Profiler measurements, providing information about ocean currents at different depths.
* `cwind`: Continuous winds data, offering high-frequency wind speed and direction measurements.
* `ocean`: Oceanographic data, including water temperature, salinity, and wave measurements.
* `spec`: Spectral wave data, providing detailed information about wave energy and direction.
* `stdmet`: Standard meteorological data, including air temperature, pressure, wind speed, and visibility.
* `supl`: Supplemental measurements, which can vary depending on the specific buoy and its sensors.
* `swden`: Spectral wave density data, providing information about the distribution of wave energy across different frequencies.
* `swdir`: Spectral wave direction data, indicating the primary direction of wave energy.
* `swdir2`: Secondary spectral wave direction data, capturing additional wave direction information.
* `swr1`: First-order spectral wave data, providing basic wave height and period information.
* `swr2`: Second-order spectral wave data, offering more detailed wave measurements.

###### `get_data`

```python3
# get all continuous wind (`cwind`) measurements for station tplm2
cwind_df = api.get_data(
    station_id='tplm2',
    mode='cwind',
    start_time='2020-01-01',
    end_time='2022-09-15',
)
# return data as a dictionary
cwind_dict = api.get_data(
    station_id='tplm2',
    mode='cwind',
    start_time='2020-01-01',
    end_time='2022-09-15',
    as_df=False
)
# get only the wind speed measurements
wspd_df = api.get_data(
    station_id='tplm2',
    mode='cwind',
    start_time='2020-01-01',
    end_time='2022-09-15',
    as_df=True,
    cols=['WSPD']
)
# get all standard meterological (`stdmet`) measurements for stations tplm2 and apam2
stdmet_df = api.get_data(
    station_ids=['tplm2', 'apam2'],
    mode='stdmet',
    start_time='2022-01-01',
    end_time='2023-01-01',
)
# get all (available) continuous wind and standard meterological measurements for stations tplm2 and apam2
# for station apam2, this is unavailable and will log an error but not affect the rest of the results.
stdmet_df = api.get_data(
    station_ids=['tplm2', 'apam2'],
    modes=['stdmet', 'cwind'],
    start_time='2022-01-01',
    end_time='2023-01-01',
)
```

#### More Information
Please see [the included example notebook](/notebooks/overview.ipynb) for a more detailed walkthrough of the API's capabilities.

#### Questions
If you have questions regarding the library please post them into
the [GitHub discussion forum](https://github.com/cdjellen/ndbc-api/discussions).


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "ndbc-api",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<3.13,>=3.9",
    "maintainer_email": null,
    "keywords": null,
    "author": "cdjellen",
    "author_email": "cdjellen@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/19/11/e8f7a631d461c18d2c26bcf4f1ca08342badbde46c8673382d96eaba943f/ndbc_api-0.24.12.20.1.tar.gz",
    "platform": null,
    "description": "<div align=\"center\">\n    <h2>NDBC API</h2>\n</div>\n\n\n[![Coverage Status](https://coveralls.io/repos/github/CDJellen/ndbc-api/badge.svg?branch=main)](https://coveralls.io/github/CDJellen/ndbc-api?branch=main)\n[![PyPI](https://img.shields.io/pypi/v/ndbc-api)](https://pypi.org/project/ndbc-api/#history)\n[![PyPI - Status](https://img.shields.io/pypi/status/ndbc-api)](https://pypi.org/project/ndbc-api/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ndbc-api)](https://pypi.org/project/ndbc-api/)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white&style=flat-square)](https://www.linkedin.com/in/cdjellen/)\n[![GitHub](https://img.shields.io/github/license/cdjellen/ndbc-api)](https://github.com/cdjellen/ndbc-api/blob/main/LICENSE)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/ndbc-api)](https://pypi.org/project/ndbc-api/)\n\n\n<div align=\"center\">\n    <h3>A Python API for the National Data Buoy Center</h3>\n</div>\n\n\nThe National Oceanic and Atmospheric Association's National Data Buoy Center maintains marine monitoring and observation stations around the world[^1]. These stations report atmospheric, oceanographic, and other meterological data at regular intervals to the NDBC. Measurements are made available over HTTP through the NDBC's data service.\n\nThe ndbc-api is a python library that makes this data more widely accessible.\n\nThe ndbc-api is primarily built to parse whitespace-delimited oceanographic and atmospheric data distributed as text files for available time ranges, on a station-by-station basis[^2]. Measurements are typically distributed as `utf-8` encoded, station-by-station, fixed-period text files. More information on the measurements and methodology are available [on the NDBC website](https://www.ndbc.noaa.gov/docs/ndbc_web_data_guide.pdf)[^3].\n\nPlease see [the included example notebook](/notebooks/overview.ipynb) for a more detailed walkthrough of the API's capabilities.\n\n[^1]: https://www.ndbc.noaa.gov/\n[^2]: https://www.ndbc.noaa.gov/obs.shtml\n[^3]: https://www.ndbc.noaa.gov/docs/ndbc_web_data_guide.pdf\n\n\n\n#### Installation\nThe `ndbc-api` can be installed via PIP:\n\n```sh\npip install ndbc-api\n```\n\nConda users can install the `ndbc-api` via the `conda-forge` channel:\n\n```sh\nconda install -c conda-forge ndbc-api\n```\n\nFinally, to install the `ndbc-api` from source, clone the repository and run the following command:\n\n```sh\npython setup.py install\n```\n\n#### Requirements\nThe `ndbc-api` has been tested on Python 3.6, 3.7, 3.8, 3.9, and 3.10. Python 2 support is not currently planned, but could be implemented based on the needs of the atmospheric research community.\n\nThe API uses synchronous HTTP requests to compile data matching the user-supplied parameters. The `ndbc-api` package depends on:\n* requests>=2.10.0\n* pandas\n* bs4\n* html5lib>=1.1\n* xarray\n* scipy\n\n##### Development\nIf you would like to contribute to the growth and maintenance of the `ndbc-api`, please feel free to open a PR with tests covering your changes. The tests leverage `pytest` and depend on the above requirements, as well as:\n* coveralls\n* httpretty\n* pytest\n* pytest-cov\n* pyyaml\n* pyarrow\n\nBreaking changes will be considered, especially in the current `alpha` state of the package on `PyPi`.  As the API further matures, breaking changes will only be considered with new major versions (e.g. `N.0.0`).\n\n#### Example\n\nThe `ndbc-api` exposes public methods through the `NdbcApi` class.\n\n```python3\nfrom ndbc_api import NdbcApi\n\napi = NdbcApi()\n```\n\nThe `NdbcApi` provides a unified access point for NDBC data. All methods for obtaining data, metadata, and locating stations are available using the `api` object. The `get_data` method is the primary method for accessing NDBC data, and is used to retrieve measurements from a given station over a specified time range. This method can request data from the NDBC HTTP Data Service or the THREDDS data service, and return the data as a `pandas.DataFrame`, `xarray.Dataset` or python `dict` object.\n\nData made available by the NDBC falls into two broad categories.\n\n1. Station metadata\n2. Station measurements\n\nThe `api` supports a range of public methods for accessing data from the above categories.\n\n##### Station metadata\n\nThe `api` has five key public methods for accessing NDBC metadata.\n\n1. The `stations` method, which returns all NDBC stations.\n2. The `nearest_station` method, which returns the station ID of the nearest station.\n3. The `station` method, which returns station metadata from a given station ID.\n4. The `available_realtime` method, which returns hyperlinks and measurement names for realtime measurements captured by a given station.\n5. The `available_historical` method, which returns hyperlinks and measurement names for historical measurements captured by a given station.\n\n###### `stations`\n\n```python3\n# get all stations and some metadata as a Pandas DataFrame\nstations_df = api.stations()\n# parse the response as a dictionary\nstations_dict = api.stations(as_df=False)\n```\n\n###### `nearest_station`\n\n```python3\n# specify desired latitude and longitude\nlat = '38.88N'\nlon = '76.43W'\n\n# find the station ID of the nearest NDBC station\nnearest = api.nearest_station(lat=lat, lon=lon)\nprint(nearest_station)\n```\n\n```python3\n'tplm2'\n```\n\n###### `radial_search`\n\n```python3\n# specify desired latitude, longitude, radius, and units\nlat = '38.88N'\nlon = '76.43W'\nradius = 100\nunits = 'km'\n\n# find the station IDs of all NDBC stations within the radius\nnearby_stations_df = api.radial_search(lat=lat, lon=lon, radius=radius, units=units)\n```\n\n```python3\n'tplm2'\n```\n\n###### `station`\n\n```python3\n# get station metadata\ntplm2_meta = api.station(station_id='tplm2')\n# parse the response as a Pandas DataFrame\ntplm2_df = api.station(station_id='tplm2', as_df=True)\n```\n\n###### `available_realtime`\n\n```python3\n# get all available realtime measurements, periods, and hyperlinks\ntplm2_realtime = api.available_realtime(station_id='tplm2')\n# parse the response as a Pandas DataFrame\ntplm2_realtime_df = api.available_realtime(station_id='tplm2', as_df=True)\n```\n\n###### `available_historical`\n\n```python3\n# get all available historical measurements, periods, and hyperlinks\ntplm2_historical = api.available_historical(station_id='tplm2')\n# parse the response as a Pandas DataFrame\ntplm2_historical_df = api.available_historical(station_id='tplm2', as_df=True)\n```\n\n##### Station measurements\n\nThe `api` has two public methods which support accessing supported NDBC station measurements.\n\n1. The `get_modes` method, which returns a list of supported `mode`s, corresponding to the data formats provided by the NDBC data service. For example, the `adcp` mode represents \"Acoustic Doppler Current Profiler\" measurements, providing information about ocean currents at different depths, while `cwind` represents \"Continuous winds\" data, offering high-frequency wind speed and direction measurements.\n\nNote that not all stations provide the same set of measurements. The `available_realtime` and `available_historical` methods can be called on a station-by station basis to ensure a station has the desired data available, before building and executing requests with `get_data`. \n\n2. The `get_data` method, which returns measurements of a given type for a given station.\n\n###### `get_modes`\n\n```python3\n# get the list of supported meterological measurement modes\nmodes = api.get_modes()\nprint(modes)\n```\n\n```python3\n[\n    'adcp',\n    'cwind',\n    'ocean',\n    'spec',\n    'stdmet',\n    'supl',\n    'swden',\n    'swdir',\n    'swdir2',\n    'swr1',\n    'swr2'\n]\n```\n\nThe mode values above map directly to the identifiers used buy the NDBC. Desriptions for each mode are presented below:\n* `adcp`: Acoustic Doppler Current Profiler measurements, providing information about ocean currents at different depths.\n* `cwind`: Continuous winds data, offering high-frequency wind speed and direction measurements.\n* `ocean`: Oceanographic data, including water temperature, salinity, and wave measurements.\n* `spec`: Spectral wave data, providing detailed information about wave energy and direction.\n* `stdmet`: Standard meteorological data, including air temperature, pressure, wind speed, and visibility.\n* `supl`: Supplemental measurements, which can vary depending on the specific buoy and its sensors.\n* `swden`: Spectral wave density data, providing information about the distribution of wave energy across different frequencies.\n* `swdir`: Spectral wave direction data, indicating the primary direction of wave energy.\n* `swdir2`: Secondary spectral wave direction data, capturing additional wave direction information.\n* `swr1`: First-order spectral wave data, providing basic wave height and period information.\n* `swr2`: Second-order spectral wave data, offering more detailed wave measurements.\n\n###### `get_data`\n\n```python3\n# get all continuous wind (`cwind`) measurements for station tplm2\ncwind_df = api.get_data(\n    station_id='tplm2',\n    mode='cwind',\n    start_time='2020-01-01',\n    end_time='2022-09-15',\n)\n# return data as a dictionary\ncwind_dict = api.get_data(\n    station_id='tplm2',\n    mode='cwind',\n    start_time='2020-01-01',\n    end_time='2022-09-15',\n    as_df=False\n)\n# get only the wind speed measurements\nwspd_df = api.get_data(\n    station_id='tplm2',\n    mode='cwind',\n    start_time='2020-01-01',\n    end_time='2022-09-15',\n    as_df=True,\n    cols=['WSPD']\n)\n# get all standard meterological (`stdmet`) measurements for stations tplm2 and apam2\nstdmet_df = api.get_data(\n    station_ids=['tplm2', 'apam2'],\n    mode='stdmet',\n    start_time='2022-01-01',\n    end_time='2023-01-01',\n)\n# get all (available) continuous wind and standard meterological measurements for stations tplm2 and apam2\n# for station apam2, this is unavailable and will log an error but not affect the rest of the results.\nstdmet_df = api.get_data(\n    station_ids=['tplm2', 'apam2'],\n    modes=['stdmet', 'cwind'],\n    start_time='2022-01-01',\n    end_time='2023-01-01',\n)\n```\n\n#### More Information\nPlease see [the included example notebook](/notebooks/overview.ipynb) for a more detailed walkthrough of the API's capabilities.\n\n#### Questions\nIf you have questions regarding the library please post them into\nthe [GitHub discussion forum](https://github.com/cdjellen/ndbc-api/discussions).\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A Python API for the National Data Buoy Center.",
    "version": "0.24.12.20.1",
    "project_urls": null,
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "9e427bda03ce59469a6017467a2b33b03e6067dffc3283325262aadf85e14614",
                "md5": "e39a8091ac09f5158acd1bcd75c902b8",
                "sha256": "ce5bc495a28f134057fcad7cf945251f162b07eac8ef96dc674966f7de7a9312"
            },
            "downloads": -1,
            "filename": "ndbc_api-0.24.12.20.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e39a8091ac09f5158acd1bcd75c902b8",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.13,>=3.9",
            "size": 56253,
            "upload_time": "2024-12-21T02:19:40",
            "upload_time_iso_8601": "2024-12-21T02:19:40.776229Z",
            "url": "https://files.pythonhosted.org/packages/9e/42/7bda03ce59469a6017467a2b33b03e6067dffc3283325262aadf85e14614/ndbc_api-0.24.12.20.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "1911e8f7a631d461c18d2c26bcf4f1ca08342badbde46c8673382d96eaba943f",
                "md5": "c7a9c897065965e39fe3cf8eea88c6be",
                "sha256": "28be2a3a45cf9355e9d38a60530193cdbd9aa30bce11da9ae99620554f722b2b"
            },
            "downloads": -1,
            "filename": "ndbc_api-0.24.12.20.1.tar.gz",
            "has_sig": false,
            "md5_digest": "c7a9c897065965e39fe3cf8eea88c6be",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.13,>=3.9",
            "size": 32938,
            "upload_time": "2024-12-21T02:19:43",
            "upload_time_iso_8601": "2024-12-21T02:19:43.347788Z",
            "url": "https://files.pythonhosted.org/packages/19/11/e8f7a631d461c18d2c26bcf4f1ca08342badbde46c8673382d96eaba943f/ndbc_api-0.24.12.20.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-21 02:19:43",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "ndbc-api"
}
        
Elapsed time: 0.34688s