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 XML from a NBDC endpoint. This data source isn’t fully documented, so there’s no guarantee of its stability.

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

Hello buoy example:

from buoyant import Buoy

# construct the Buoy object with the station ID
# It's an alphanumeric code. If its numeric, an integer works fine.
station = Buoy(13010)
# 'Soul'
# Yes, that buoy is really named Soul.

More examples:

from buoyant import Buoy

station = Buoy('lndc1')

# 9.9

# 'kt'

# -23.14

# (20.43, -23.14)

# Get the time the measurements were made.
# datetime.datetime(2014, 12, 15, 20, 50, tzinfo=<UTC>)

# Not all stations report all data.
# raises AttributeError

# Fetches new data. This isn't very useful, since the buoys update only every hour or so


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)

# ''

# Save image as a file 'out.jpg'

# Get raw image as a BytesIO object (see
# <_io.BytesIO object>

# ''

Measurement metadata

The occassional buoy reports metadata about its measurements. The Buoy object has a meta attribute with this data, if any.

# Buoy in the Frying Pan Shoals, NC
frying_pan = Buoy(41013)

# 30.1

# {'tendency': 'steady'}

No data

Sometimes buoys don’t have recent data. You’ll be able to tell two ways. First, the Buoy object won’t have many attributes. Second, there will be a message. It will say ‘No data’.

station = Buoy('ANRN6')
# 'No data'

Measurements included

Any measurements reported in the NBDC’s XML api are included in a Buoy object. Read about the meaning of the different measurements.

Measurements often included (the text in parentheses is the one used on the NBDC’s measurement descriptions page):

  • air_temp (ATMP)
  • average_period (APD)
  • dominant_period (DPD)
  • mean_wave_direction (Spectral wave direction)
  • water_temp (WTMP)
  • wave_height (WVHT)
  • wind_direction (WDIR)
  • wind_gust (GST)
  • wind_speed (WSPD)
  • datetime
  • dewpoint (DEWP)
  • lat (latitude)
  • lon (longitude)
  • pressure (PRES)

Water quality data isn’t included in the XML data source. Neither is the elevation of the station or the location of the instruments relative to the station.


Get the raw XML, if you like XML for some reason. Maybe the package is missing something? If so, submit an issue or pull request!

soul = Buoy('13010')
'''<?xml version="1.0" encoding="UTF-8"?>
<observation id="13010" name="Soul" lat="-0.01" lon="0.00">
  <winddir uom="degT">190</winddir>
  <windspeed uom="kt">9.9</windspeed>
  <airtemp uom="F">78.8</airtemp>


Buoyant is compatible with Python 2 and 3.


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.

Filename, size & hash SHA256 hash help File type Python version Upload date
buoyant-0.5.2--py2.py3-none-any.whl (10.9 kB) Copy SHA256 hash SHA256 Wheel -py2.py3
buoyant-0.5.2.tar.gz (7.6 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page