CO-OPS API For Data Retrieval

The CO-OPS API for data retrieval can be used to retrieve observations and predictions from CO-OPS stations.

Station ID

A 7 character station ID, or a currents station ID. Specify the station ID with the "station=" parameter.
Example: station=9414290
Station listings for various products can be viewed at or viewed on a map at Tides & Currents Station Map

Date & Time

The API understands several parameters related to date ranges.
All dates can be formatted as follows:
yyyyMMdd, yyyyMMdd HH:mm, MM/dd/yyyy, or MM/dd/yyyy HH:mm

One the 4 following sets of parameters can be specified in a request:

Parameter Name (s) Description
begin_date and end_date Specify the date/time range of retrieval
date Valid options for the date parameters are: latest (last data point available within the last 18 min), today, or recent (last 72 hours)
begin_date and a range Specify a begin date and a number of hours to retrieve data starting from that date
end_date and a range Specify an end date and a number of hours to retrieve data ending at that date
range Specify a number of hours to go back from now and retrieve data for that date range
January 1st, 2012 through January 2nd, 2012
48 hours beginning on April 15, 2012
48 hours ending on March 17, 2012
Today's data
The last 3 days of data
The last data point available within the last 18 min
The last 24 hours from now
The last 3 hours from now

Data Products

Specify the type of data with the "product=" option parameter.

Option Description
water_level Preliminary or verified water levels, depending on availability.
air_temperature Air temperature as measured at the station.
water_temperature Water temperature as measured at the station.
wind Wind speed, direction, and gusts as measured at the station.
air_pressure Barometric pressure as measured at the station.
air_gap Air Gap (distance between a bridge and the water's surface) at the station.
conductivity The water's conductivity as measured at the station.
visibility Visibility from the station's visibility sensor. A measure of atmospheric clarity.
humidity Relative humidity as measured at the station.
salinity Salinity and specific gravity data for the station.
hourly_height Verified hourly height water level data for the station.
high_low Verified high/low water level data for the station.
daily_mean Verified daily mean water level data for the station.
monthly_mean Verified monthly mean water level data for the station.
one_minute_water_level One minute water level data for the station.
predictions 6 minute predictions water level data for the station.
datums datums data for the stations.
currents Currents data for currents stations.


The datum can be specified with the "datum=" option parameter. Note! Datum is mandatory for all water level products.

Option Description
MHHW Mean Higher High Water
MHW Mean High Water
MTL Mean Tide Level
MSL Mean Sea Level
MLW Mean Low Water
MLLW Mean Lower Low Water
NAVD North American Vertical Datum
STND Station Datum


Metric or english units. The unit type can be specified with the "units=" option parameter.

Option Description
metric Metric (Celsius, meters) units
english English (fahrenheit, feet) units
Example: units=english
Retrieve data in english units.

Time Zone

gmt, lst or lst_ldt. The time_zone can be specified with the "time_zone=" option parameter.

Option Description
gmt Greenwich Mean Time
lst Local Standard Time. The time local to the requested station.
lst_ldt Local Standard/Local Daylight Time. The time local to the requested station.
Example: time_zone=gmt
Retrieve data with GMT date/times.


The output format can be specified with the "format=" option parameter.

Option Description
json Javascript Object Notation. This format is useful for direct import to a javascript plotting library. Parsers are available for other languages such as Java and Perl.
xml Extensible Markup Language. This format is an industry standard for data.
csv Comma Separated Values. This format is suitable for export to Microsoft Excel or other spreadsheet programs. This is also the most easily human-readable format.


The interval for which Meteorological data is returned
Note! The default is 6 minute interval and there is no need to specify it. The hourly interval is supported for Met data and Predictions data only.
Example:interval=h --- Will retrieve hourly Met data

Option Description
h Hourly Met data and predictions data will be returned


The bin number for the specified currents station
Example:bin=4 --- Will retrieve data for bin number 4
Note! If a bin is not specified for a PORTS station, the data is returned using a predefined real-time bin.

Option Description
3 Currents data for bin number 3 of the specified station is returned


If you are a CO-OPS developer, please include the application name calling the API. If you are an external user, please provide the name of your organization for this parameter when calling this API.
application=Web Services

Option Description
Web_Services The internal application Web Services has called the API
NDBC A user from the National Data Buoy Center has called the API
Maximum Retrieval Time Data Types
31 days All 6 minute data products
1 year Hourly Height, and High/Low
10 years Tide Predictions, Daily, and Monthly Means

Sample URL requests and responses 10:00&end_date=20130101 10:24&station=8454000&product=water_level&datum=mllw&units=metric&time_zone=gmt&application=web_services&format=xml

Sample XML output
  <?xml version="1.0" encoding="UTF-8" ?> 
    <metadata id="8454000" name="Providence" lat="41.8071" lon="-71.4012" /> 
        <wl t="2013-01-01 10:00" v="0.072" s="0.003" f="0,0,0,0" q="v" /> 
        <wl t="2013-01-01 10:06" v="0.095" s="0.003" f="0,0,0,0" q="v" /> 
        <wl t="2013-01-01 10:12" v="0.115" s="0.003" f="0,0,0,0" q="v" /> 
        <wl t="2013-01-01 10:18" v="0.138" s="0.004" f="0,0,0,0" q="v" /> 
        <wl t="2013-01-01 10:24" v="0.167" s="0.004" f="0,0,0,0" q="v" /> 
             15:00&end_date=20130808 15:06&station=8454000&product=water_temperature&units=english&time_zone=gmt&application=ports_screen&format=json

Sample JSON output
    "metadata": {
        "id": "8454000",
        "name": "Providence",
        "lat": "41.8071",
        "lon": "-71.4012"
    "data": [
            "t": "2013-08-08 15:00",
            "v": "72.50",
            "f": "0,0,0"
            "t": "2013-08-08 15:06",
            "v": "72.50",
            "f": "0,0,0"

Error Message

Depending on the nature of the exception the user will get a customized error message back in the same format of the request.

<?xml version="1.0" encoding="UTF-8" ?>
Wrong Date: The end date should be greater than the begin date 
        "Great Lakes stations don't have Predictions data."