| Name | ndbc-api JSON |
| Version |
0.24.12.20.1
JSON |
| download |
| home_page | None |
| Summary | A Python API for the National Data Buoy Center. |
| upload_time | 2024-12-21 02:19:43 |
| maintainer | None |
| docs_url | None |
| author | cdjellen |
| requires_python | <3.13,>=3.9 |
| license | MIT |
| 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>
[](https://coveralls.io/github/CDJellen/ndbc-api?branch=main)
[](https://pypi.org/project/ndbc-api/#history)
[](https://pypi.org/project/ndbc-api/)
[](https://pypi.org/project/ndbc-api/)
[](https://www.linkedin.com/in/cdjellen/)
[](https://github.com/cdjellen/ndbc-api/blob/main/LICENSE)
[](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[](https://coveralls.io/github/CDJellen/ndbc-api?branch=main)\n[](https://pypi.org/project/ndbc-api/#history)\n[](https://pypi.org/project/ndbc-api/)\n[](https://pypi.org/project/ndbc-api/)\n[](https://www.linkedin.com/in/cdjellen/)\n[](https://github.com/cdjellen/ndbc-api/blob/main/LICENSE)\n[](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"
}
