Grab data from buoys around the world
Python
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
buoyant
tests
.gitignore
.travis.yml
LICENSE
MANIFEST.in
README.md
setup.cfg
setup.py

README.md

Buoyant

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.

> buoy.wave_height
AttributeError

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]'

Images

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
'http://www.ndbc.noaa.gov/images/buoycam/Z14C_2014_11_01_2200.jpg'

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
'http://www.ndbc.noaa.gov/station_page.php?station=41009'

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
AttributeError

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!

Compatibility

Buoyant is compatible with Python 2 and 3.

License

Buoyant is licensed under the GPL.