Using API for CBIBS

While many CBIBS users just want to check on conditions at a buoy from time to time, others with high technical knowledge may want to build a way to continually get data. The information presented here will help these users develop an Application Programming Interface--an API--for that purpose. An API essentially is the part of a server that receives requests and sends responses. (For nontechnical CBIBS data users, you essentially serve as your very own API client when you access the CBIBS data you're looking for via the website or mobile apps.)

The information below focuses on computer-to-computer data interchanges. A user can access the REST endpoints via HTTP. There are two return types, JSON and XML. There are two types of requests: One returns the latest measurements and the other will return a time range and a parameter. The key and time are required; the station and parameter are optional and can return all stations and/or all parameters. Any request will require an apikey. This is the security code to access the data. For testing, use this key. Know that it may change at any time and is only for testing purposes. If you would like a key, contact us here or email us at cbibs@noaa.gov and we will provide one.

All of the API methods use the base URL.

Base URL: https://mw.buoybay.noaa.gov/api/v1

Testing Key: f159959c117f473477edbdf3245cc2a4831ac61f

Quick Version

Query the latest measurements:

XML

All stations: baseURL/xml/station?key=apikey

One station: baseURL/xml/station/station?key=apikey

JSON

All stations: baseURL/json/station?key=apikey

One station: baseURL/json/station/station?key=apikey

Query based on criteria

XML

All stations 

baseURL/xml/query?key=apikey&sd=start_date&ed=end_date&var=var_name

One station baseURL/xml/query/AN?key=apikey&sd=start_date&ed=end_date&var=var_name

JSON

All stations 

baseURL/json/query?key=apikey&sd=start_date&ed=end_date&var=var_name

One station baseURL/json/query/AN?key=apikey&sd=start_date&ed=end_date&var=var_name

Detailed Version

How to Retrieve the Current Readings

To get the latest measurements for one or all stations send a GET request to the service. There is a query parameter filter if you want to get just one station. Note that data may be old because the query returns the last values recorded for a station. If the  <active> flag is true then the station is defined as an active station and the data should be current. If the data is not current then the station may have some temporary issues causing a delay in the data recording. If the flag is false then the station has been taken out of service and the data will not be current. These examples can be copied and pasted into a browser.

XML Endpoint

URI path: baseURL/xml/station?key=apikey

Optional station name: baseURL/xml/station/FL?key=apikey

Required Parameters: key=apikey

Example URI

https://mw.buoybay.noaa.gov/api/v1/xml/station?key=apikey

Example: Return current data for First Landing in XML

https://mw.buoybay.noaa.gov/api/v1/xml/station/FL?key=apikey

<CBIBS>

  <stations>

    <station stationLongName="First Landing CBIBS Buoy" stationShortName="FL">

      <active>true</active>

      <latitude>36.99810</latitude>

      <longitude>-76.08710</longitude>

      <variable reportName="Air Pressure" actualName="air_pressure" interval="600">

        <measurements>

          <measurement>

            <time>2019-05-06T13:40:00+00</time>

            <value>1015.57</value>

            <unit>hPa</unit>

            <elevation>0.0</elevation>

            <QA id="1">N/A</QA>

          </measurement>

        </measurements>

      </variable>

      <variable reportName="Air Temperature" actualName="air_temperature" interval="600">

        <measurements>

          <measurement>

            <time>2019-05-06T13:40:00+00</time>

            <value>15.30</value>

            <unit>C</unit>

            <elevation>0.0</elevation>

            <QA id="1">N/A</QA>

          </measurement>

        </measurements>

      </variable>

JSON Endpoint

URI path: baseURL/json/station?key=apikey

Optional Parameter: baseURL/json/station/FL?key=apikey

Required Parameters: key=apikey

Example: Retrieve all stations current data with JSON. Use this URL and the API Key

https://mw.buoybay.noaa.gov/api/v1/json/station?key=apikey

Example Return Data Format

{

  "stations": [

    {

      "stationShortName": "FL",

      "stationLongName": "First Landing CBIBS Buoy",

      "active": true,

      "latitude": 36.9981,

      "longitude": -76.0871,

      "variable": [

        {

          "reportName": "Air Temperature",

          "actualName": "air_temperature",

          "interval": 600,

          "units": "C",

          "group": "Meteorological",

          "elevation": "0.0",

          "measurements": [

            {

              "time": "2019-05-06T14:10:00+00",

              "value": 15.4,

              "QA": "N/A"

            }

          ]

        },

Query Data Using Criteria

This method will take parameters to query data for a specific time range, station, and parameter. This will return historical records. To use this method send a GET request to the service. The required parameters are

key = apikey

var = Variable queried (Can be ‘all’ if you want all parameters)

sd = Start date time in ISO8601 format format

    example (2020-04-01T10:00:00z)

ed = End date time in ISO8601 format format

    example (2020-04-01T10:00:00z)

XML Endpoint

URI path: baseURL/xml/query?key=apikey&sd=start_date&ed=end_date&var=var_name

Optional station name: baseURL/xml/query/FL?key=apikey&sd=start_date&ed=end_date&var=var_name

Example

https://mw.buoybay.noaa.gov/api/v1/xml/query/AN?key=<<key>>&sd=2020-04-01T10:00:00z&ed=2020-04-01T20:00:00z&var=sea_water_temperature

Example Return Data Format

<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet href="/api/cbibsXmlQueryStyle.xsl" type="text/xsl"?>

<CBIBS>

  <stations>

    <station stationLongName="Annapolis CBIBS Buoy" stationShortName="AN">

      <active>true</active>

      <latitude>38.96340</latitude>

      <longitude>-76.44670</longitude>

      <variable reportName="Water Temperature" actualName="sea_water_temperature" interval="360">

        <measurements>

          <measurement>

            <time>2020-04-01T10:00:00+00</time>

            <value>10.736</value>

            <unit>C</unit>

            <elevation>0.0</elevation>

            <QA id="1">GOOD Value</QA>

          </measurement>

          <measurement>

            <time>2020-04-01T10:06:00+00</time>

            <value>10.734</value>

            <unit>C</unit>

            <elevation>0.0</elevation>

            <QA id="1">GOOD Value</QA>

          </measurement>

          <measurement>

    ...

JSON Endpoint

URI path: baseURL/json/query?key=apikey

Optional Parameter: baseURL/json/query/FL?key=apikey

Example

https://mw.buoybay.noaa.gov/api/v1/json/query/AN?key=<<api_key>>&sd=2020-04-01T10:00:00z&ed=2020-04-01T20:00:00z&var=sea_water_temperature

Example Return Data Format

{"stations":[{"stationShortName":"AN","stationLongName":"Annapolis CBIBS Buoy","active":true,"latitude":38.9634,"longitude":-76.4467,"variable":[{"reportName":"Water Temperature","actualName":"sea_water_temperature","units":"C","elevation":"0.0","group":"WaterQuality","interval":"360","measurements":[{"time":"2020-04-01T10:00:00+00","value":"10.736","QA":"GOOD Value"},{"time":"2020-04-01T10:06:00+00","value":"10.734","QA":"GOOD Value"},{"time":"2020-04-01T10:12:00+00","value":"10.716","QA":"GOOD Value"},{"time":"2020-04-01T10:24:00+00","value":"10.613","QA":"GOOD Value"},{"time":"2020-04-

Appendix

Station Long and Short Names. Use the Short Name in the API calls.

Parameter Names