Skip to main content

Wrapper for the NOAA National Data Buoy Center

Project description


Buoyant is a Python wrapper for grabbing buoy data from the National Buoy Data Center. It parses CSV from the SDF endpoint and images from the BuoyCam service.

The NBDC provides a list and a map of active buoys.

Hello buoy example:

> from buoyant import Buoy
> buoy = Buoy(13010)

Construct the Buoy object with the station ID. It's an alphanumeric code. If its numeric, an integer works fine.

More examples:

> from buoyant import Buoy
> buoy = Buoy('0Y2W3')
> buoy.air_pressure_at_sea_level
Observation(1014.1, 'hPa')

Get buoy location.
> buoy.coords
(44.794, -87.313)

Get the time the measurements were made. This can be some time ago!
> buoy.air_pressure_at_sea_level.datetime
datetime.datetime(2015, 8, 18, 11, 40, tzinfo=<UTC>)

Not all stations report all data at all times. Be prepared to handle empty attributes.
> buoy.wave_height

Clear the buoy object's data dictionary. This isn't very useful, since the buoys update only every hour or so.
> buoy.refresh()

The Observation object is numeric value (a float) with two additional attributes, unit and value. Generally unit this is an abbreviation for a metric unit or composition of units. You can use Observations just like numeric objects, and use the value or unit field when formatting:

> pressure = buoy.air_pressure_at_sea_level
Observation(1014.1, 'hPa')
> min(pressure, 1020)
Observation(1014.1, 'hPa')
> '{0.value} [{0.unit}]'.format(pressure)
'1014.1 [hPa]'


Some buoys have cameras! If the buoy doesn't have an active camera, a placeholder image provided by the NBDC will be returned.

> station = Buoy(41009)
> station.image_url

Save image as a file 'out.jpg'

> station.write_image('out.jpg')

Get raw image as a BytesIO object

> station.image
<_io.BytesIO object>
> station.url

No data

There are two ways to a buoy can be missing a certain data field. Either there's no recent observation, or that buoy doesn't observe that datum.

> buoy = Buoy('0Y2W3')
> buoy.winds
# None, because while this is usually recorded, it hasn't been lately.
> sturgeon.waves

Measurements included

  • air_pressure_at_sea_level
  • air_temperature
  • currents
  • sea_floor_depth_below_sea_surface
  • sea_water_electrical_conductivity
  • sea_water_salinity
  • sea_water_temperature
  • waves
  • winds

Currents and Waves and Wind

Wave and wind data have multiple data points, the are returned as dicts.

Currents data is returned as a list of dicts with current information at different times/depths. It's not well-documented on the NBDC site, so good luck!


Buoyant is compatible with Python 3.5+.


Buoyant is licensed under the GPL.

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

buoyant-0.7.0.macosx-10.13-x86_64.tar.gz (9.7 kB view hashes)

Uploaded Source

Built Distribution

buoyant-0.7.0-py3-none-any.whl (19.3 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