• Jump to:
• Station ID
• Date & Time
• Data Products
• Datum
• Units
• Time Zone
• Format
• Interval
• Bin
• Application
• Retrieval Time
• Sample URL
• Error Message
• Contact Us
• Help links:
• Response Help Page

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.
currents_predictions	Currents predictions data for currents predictions stations.

* For hourly height and high/low predictions, refer to the Interval section further down.

Datum

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

Option	Description
CRD	Columbia River Datum
IGLD	International Great Lakes Datum
LWD	Great Lakes Low Water Datum (Chart Datum)
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

Velocity Type

The Velocity Type can be specified with the "vel_type=" option parameter. Note! vel_type= speed_dir only supports current prediction intervals of 1, 6, 10, 30, 60. Set vel_type = default for interval = max_slack.

Option	Description
speed_dir	Return results for speed and dirction
default	Return results for velocity major, mean flood direction and mean ebb dirction

Units

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

Option	Description
metric	Metric (Celsius, meters, cm/s) units
english	English (fahrenheit, feet, knots) 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 Harmonic Predictions data only.
Example:interval=h --- Will retrieve hourly Met data

Option	Description
h	Hourly Met data and harmonic predictions will be returned
hilo	High/Low tide predictions for all stations.

The interval for which Current Prediction data is returned
Note! The MAX_SLACK interval is supported for Current Predictions data only.
Example:interval=60 --- Will retrieve hourly Current Prediction data

Option	Description
1, 6, 20, 30, 60	Time series data will be returned
MAX_SLACK	MAX Slack results 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

External Users, please provide the name of your company or your name. Internal CO-OPS users, please include the name of the application. This parameter is used for helping to fix any possible usage issues.

Examples:
application=Your_Company_Name
application=John_Public
application=NDBC
application=NOAA_Tide_Predictions

Option	Description
Your_Company_Name	A user from Your Company Name has called the API
John_Public	The customer, John Public, has called the API
NDBC	A user from the National Data Buoy Center (NDBC) has called the API
NOAA_Tide_Predictions	The internal application, NOAA Tide Predictions, 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://api.tidesandcurrents.noaa.gov/api/prod/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://api.tidesandcurrents.noaa.gov/api/prod/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."
    }
} 
                    

Contact Us

E-mail: User Services (co-ops.userservices@noaa.gov)