Package: ndbc-api
NDBC APIA Python API for the National Data Buoy CenterThe 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 asutf-8encoded, station-by-station, fixed-period text files. More information on the measurements and methodology are availableon the NDBC website^3.Please seethe included example notebookfor a more detailed walkthrough of the API's capabilities.InstallationThendbc-apican be installed via PIP:pipinstallndbc-apiRequirementsThendbc-apihas 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. Thendbc-apipackage depends on:requests>=2.10.0pandasbs4html5lib>=1.1DevelopmentIf you would like to contribute to the growth and maintenance of thendbc-api, please feel free to open a PR with tests covering your changes. The tests leveragepytestand depend on the above requirements, as well as:coverallshttprettypytestpytest-covpyyamlpyarrowBreaking changes will be considered, especially in the currentalphastate of the package onPyPi.  As the API further matures, breaking changes will only be considered with new major versions (e.g.N.0.0).ExampleThendbc-apiexposes public methods through theNdbcApiclass.fromndbc_apiimportNdbcApiapi=NdbcApi()Theapiis a singleton, such that the underlyingRequestHandlerand NDBC station-levelRequestCaches are shared between instances. Both the singleton metaclass andRequestHandlerare implemented to reduce the likelihood of repeat requests to the NDBC's data service, and to converse NDBC resources. This is balanced by a station-levelcache_limit, implemented as an LRU cache, which seeks to respect user resources.Data made available by the NDBC falls into two broad catagories.Station metadataStation measurementsTheapisupports a range of public methods for accessing data from the above catagories.Station metadataTheapihas five key public methods for accessing NDBC metadata.Thestationsmethod, which returns all NDBC stations.Thenearest_staionmethod, which returns the station ID of the nearest station.Thestationmethod, which returns station metadata from a given station ID.Theavailable_realtimemethod, which returns hyperlinks and measurement names for realtime measurements captured by a given station.Theavailable_historicalmethod, which returns hyperlinks and measurement names for historical measurements captured by a given station.stations# get all stations and some metadata as a Pandas DataFramestations_df=api.stations()# parse the response as a dictionarystations_dict=api.stations(as_df=False)nearest_station# specify desired latitude and longitudelat='38.88N'lon='76.43W'# find the station ID of the nearest NDBC stationnearest=api.nearest_station(lat=lat,lon=lon)print(nearest_station)'tplm2'station# get staion metadatatplm2_meta=api.station(station_id='tplm2')# parse the response as a Pandas DataFrametplm2_df=api.station(station_id='tplm2',as_df=True)available_realtime# get all available realtime measurements, periods, and hyperlinkstplm2_realtime=api.available_realtime(station_id='tplm2')# parse the response as a Pandas DataFrametplm2_realtime_df=api.available_realtime(station_id='tplm2',as_df=True)available_historical# get all available historical measurements, periods, and hyperlinkstplm2_historical=api.available_historical(station_id='tplm2')# parse the response as a Pandas DataFrametplm2_historical_df=api.available_historical(station_id='tplm2',as_df=True)Station measurementsTheapihas two public method which support accessing supported NDBC station measurements.Theget_modesmethod, which returns a list of supportedmodes, coresponding to the data formats provided by the NDBC data service.Note that not all stations provide the same set of measurements. Theavailable_realtimeandavailable_historicalmethods can be called on a station-by station basis to ensure a station has the desired data available, before building and executing requests withget_data.Theget_datamethod, which returns measurements of a given type for a given station.get_modes# get the list of supported meterological measurement modesmodes=api.get_modes()print(modes)['adcp','cwind','ocean','spec','stdmet','supl','swden','swdir','swdir2','swr1','swr2']get_data# get all continuous wind measurements for station tplm2cwind_df=api.get_data(station_id='tplm2',mode='cwind',start_time='2020-01-01',end_time='2022-09-15',)# return data as a dictionarycwind_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 measurementswspd_df=api.get_data(station_id='tplm2',mode='cwind',start_time='2020-01-01',end_time='2022-09-15',as_df=True,cols=['WSPD'])More InformationPlease seethe included example notebookfor a more detailed walkthrough of the API's capabilities.QuestionsIf you have questions regarding the library please post them into
theGitHub discussion forum.ContributingThendbc-apiis actively maintained, please feel free to open a pull request if you have any suggested improvements, test coverage is strongly preferred.As a reminder, breaking changes will be considered, especially in the currentalphastate of the package onPyPi.  As the API further matures, breaking changes will only be considered with new major versions (e.g.N.0.0).Alternatively, if you have an idea for a new capability or improvement, feel free to open a feature request issue outlining your suggestion and the ways in which it will empower the atmospheric research community.