• Jump to:
• Station ID
• Date & Time
• Data Products
• Datum
• Units
• Time Zone
• Format
• Interval
• Bin
• Application
• Retrieval Time
• Sample URL
• Error Message

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 https://tidesandcurrents.noaa.gov 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

begin_date=20120101&end_date=20120102

48 hours beginning on April 15, 2012

begin_date=20120415&range=48

48 hours ending on March 17, 2012

end_date=20120307&range=48

Today's data

date=today

The last 3 days of data

date=recent

The last data point available within the last 18 min

date=latest

The last 24 hours from now

range=24

The last 3 hours from now

range=3

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.

Datum

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

Units

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.

Format

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.

Interval

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

Bin

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

Application

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.
Examples:
application=Web Services
application=Tides_and_Currents
application=NDBC

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

https://tidesandcurrents.noaa.gov/api/datagetter?begin_date=20130101 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" ?> 
    <data>
    <metadata id="8454000" name="Providence" lat="41.8071" lon="-71.4012" /> 
    <observations>
        <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" /> 
    </observations>
    </data>
                    

https://tidesandcurrents.noaa.gov/api/datagetter?begin_date=20130808 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" ?>
<error>
Wrong Date: The end date should be greater than the begin date 
</error>
                    

{
    "error": 
    {
    "message":
        "Great Lakes stations don't have Predictions data."
    }
}