CO-OPS Data Retrieval API

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.
Examples:
station=9414290 (water level / met station)
station=cb1401 (currents station)
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 5 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
begin_date and range	Specify a begin date and a number of hours to retrieve data starting from that date
end_date and range	Specify an end date and a number of hours to retrieve data ending at that date
date	Data from today’s date. Note! Only available for preliminary water level data, meteorological data and predictions. Valid options for the date parameter are: • Today (24 hours starting at midnight) • Latest (last data point available within the last 18 min) • Recent (last 72 hours)
range	Specify a number of hours to to back from now and retrieve data for that period Note! • If used alone, only available for preliminary water level data, meteorological data • If used with a historical begin or end date, may be used with verified data • If used for daily maximum/minimum with a historical begin or end date, range is set in the number of years.

Examples:

begin_date=20120101&end_date=20120102	Retrieves data for January 1st, 2012 through January 2nd, 2012
begin_date=20120415&range=48	Retrieves data for 48 hours beginning on April 15, 2012
end_date=20120307&range=48	Retrieves data for 48 hours ending on March 17, 2012
begin_date=20190101&range=5	Retrieves data for January 1st, 2019 through December 31, 2023
date=today	Retrieves data for today
date=latest	Retrieves the last data point available within the last 18 min
date=recent	Retrieves the last 3 days of data
range=12	Retrieves the last 12 hours of data

Data Products

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

Data Length Limitations:	To prevent numerous large data requests slowing data access through the internet services; all internet data services have limits on the amount/length of data which can be retrieved per request. These limits are based on the interval of data requested.
1-minute interval data	Data length is limited to 4 days
6-minute interval data	Data length is limited to 1 month
Hourly interval data	Data length is limited to 1 year
High / Low data	Data length is limited to 1 year
Daily Means data	Data length is limited to 10 years
Daily Maximum / Minimum data	Data length is limited to 10 years
Monthly Means data	Data length is limited to 200 years

Tides / Water Levels Data	Note!Data is verified on a monthly basis for the past month. (Example: January data is verified in February). Daily maximum/minimum becomes available after monthly verification is completed for the past month. (Example: January data becomes available in March).No specific date can be provided for verified data availability; as the order stations are verified will change each month to avoid appearances of one station being “more important” than another. Datum is mandatory for water level data products, except Air Gap
Option	Description
water_level	Preliminary or verified 6-minute interval water levels, depending on data availability.
hourly_height	Verified hourly height water level data for the station.
high_low	Verified high tide / low tide water level data for the station.
daily_mean	Verified daily mean water level data for the station. Note!Great Lakes stations only. Only available with “time_zone=LST”
Daily Maximum	Verified daily maximum 6 minute or hourly water level data for the station. Note!Only available with “time_zone=LST” or “time_zone=GMT” and default is from the hourly data. Use “interval=6” for 6-minute data
Daily Minimum	Verified daily minimum 6 minute or hourly water level data for the station. Note!Only available with “time_zone=LST” or “time_zone=GMT” and default is from the hourly data. Use “interval=6” for 6-minute data
monthly_mean	Verified monthly mean water level data for the station.
one_minute_water_level	Preliminary 1-minute interval water level data for the station.
predictions	Water level / tide prediction data for the station. Note!See Interval for available data interval options and data length limitations.
~~datums~~	Datums product no longer available on CO-OPS Data API, please visit CO-OPS Metadata API.
air_gap	Air Gap (distance between a bridge and the water's surface) at the station.

Meteorological Data	Note!Default is 6-minute interval data. Use with “interval=h” for hourly data
Option	Description
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.
conductivity	The water's conductivity as measured at the station.
visibility	Visibility (atmospheric clarity) as measured at the station. (Units of Nautical Miles or Kilometers.)
humidity	Relative humidity as measured at the station.
salinity	Salinity and specific gravity data for the station.

Currents Data	Bin is required for most stations
Option	Description
currents	Currents data for the station. Note! Default data interval is 6-minute interval data.Use with “interval=h” for hourly data> There may be differences in bin depths across the deployments as sensor depth and on rare occasions bin size could change when a sensor is re-deployed.
currents_predictions	Currents prediction data for the stations. Note! See Interval for options available and data length limitations.
currents_header	Currents header data for the stations. Note! Data length is limited to 1 month.

Operational Forecast (OFS)	Note! Model nowcast / forecast data is available at most real-time water level stations within OFS model domains.
Option	Description
ofs_water_level	Water level model guidance at 6-minute intervals based on NOS OFS models. Data available from 2020 to present.

Examples:

product=water_level	Retrieves 6-minute interval water level data for the station
product=hourly_height	Retrieves verified hourly water level data for the station
product=visibility	Retrieves visibility data for the station
product =currents_predictions	Retrieves predicted currents for the station
product=ofs_water_level	Retrieves 6-minute nowcast/forecast guidance from OFS models for the station

Expand

The expand can be specified with the "expand=" option parameter.
Note! expand is for currents product to retrieve echo intensity and correlation magnitude data.
Only apply to currents product.

Option	Description
detailed	Currents product - to retrieve echo intensity and correlation magnitude data(The units are in counts)

Examples:

expand=detailed

Retrieves currents data with echo intensity and correlation magnitude data for the station

Datum

The datum can be specified with the "datum=" option parameter.
Note! Datum is mandatory for all water level products to correct the data to the reference point desired.
Does not apply to Air Gap data, which is only provided relative to a fixed reference point on the bridge.

Option	Description
CRD	Columbia River Datum. Note!Only available for certain stations on the Columbia River, Washington/Oregon
IGLD	International Great Lakes Datum Note! Only available for Great Lakes stations.
LWD	Great Lakes Low Water Datum (Nautical Chart Datum for the Great Lakes). Note! Only available for Great Lakes Stations
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 (Nautical Chart Datum for all U.S. coastal waters) Note! Subordinate tide prediction stations must use “datum=MLLW”
NAVD	North American Vertical Datum Note! This datum is not available for all stations.
STND	Station Datum - original reference that all data is collected to, uniquely defined for each station.

Examples:

datum=MLLW

Retrieves data with heights relative to Mean Lower Low Water (MLLW) for the station

Units

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

Option	Description
metric	Metric units (Celsius, meters, cm/s appropriate for the data) Note!Visibility data is kilometers (km), Currents data is in cm/s.
english	English units (fahrenheit, feet, knots appropriate for the data) Note!Visibility data is Nautical Miles (nm), Currents data is in knots.

Examples:

units=english

Retrieves data in english units.

Time Zone

The time_zone of the data can be specified with the "time_zone=" option parameter.
Note!Does not apply to products of monthly_mean; daily_mean (Great Lakes) must use time_zone=lst

Option	Description
gmt	Greenwich Mean Time
lst	Local Standard Time, not corrected for Daylight Saving Time, local to the requested station.
lst_ldt	Local Standard Time, corrected for Daylight Saving Time when appropriate, local to the requested station

Examples:

time_zone=gmt	Retrieves data with date/times in Greenwich Mean Time.
time_zone=lst_ldt	Retrieves data with dates/times in Local Time, adjusted for daylight saving time when appropriate.

Interval

Tide/Water Level Data
Verified water level height data cannot be retrieved using the Interval parameter.
Each available interval for verified water level data is a separate data product and must be retrieved using the appropriate product type.

Tide/Water Level Predictions
Note! Harmonic tide prediction stations can provide tide predictions on any available interval.
Subordinate tide prediction stations can only provide tide predictions on a high / low interval.
Data Length Limitation: High/Low tide predictions are limited to 10 years. All other intervals are limited to 1 year.

Option	Description
h	Hourly tide predictions for the station.
1, 5, 6, 10, 15, 30, 60	Tide predictions on the interval (number of minutes) requested. These are the only values accepted.
hilo	Tide predictions for high tide and low tide times and heights.

Examples:

interval=h	Returns tide predictions on an hourly interval
interval=15	Returns tide predictions on a 15-minute interval
interval =hilo	Returns tide predictions for high tide and low tide times and heights

Currents Data
Note!The default interval is the only interval available, 6-minute interval data. There is no need to specify it.

Currents Predictions
Note!Harmonic currents prediction stations can provide tidal current predictions on any available interval.
Subordinate current prediction stations can only provide tidal current predictions on a max/slack interval.
Data Length Limitation: Max_Slack current predictions are limited to 1 year. All other intervals are limited to 1 month.

Option	Description
h	Hourly current predictions for the station.
1, 6, 10, 30, 60	Current predictions on the interval (number of minutes) requested. These are the only values accepted.
max_slack	Current predictions of max flood/ebb currents (time and speed) and slack water (times).

Examples:

interval=h	Returns current predictions on an hourly interval
interval=10	Returns current predictions on a 10-minute interval
interval=max_slack	Returns current predictions for max flood, slack water, and max ebb currents

Meteorological Data
Note! The default interval is a 6-minute interval and there is no need to specify it.

Option	Description
h	Hourly interval data (the 6-minute interval value on the hour) is returned.

Examples:

interval=h

Retrieves meteorological data on the hour.

Bin

Current data and predictions provide information for a specific depth, each depth available for a station has a different Bin number.
• At PORTS (real time currents) stations a bin number is not required, the data is returned using a predefined bin.
◦ If a bin number of 0 (bin=0) is used, data for all bins are provided. (Data Length Limitation: 7 days for all bins)
• All other current stations require a bin number to access data.
• Historic Survey Current Stations - the Bin numbers / depths for historical survey currents stations are available through the MetaData API
◦ If a bin number of 0 (bin=0) is used, data for all bins is provided. (Data Length Limitation: 7 days for all bins)
• Tidal current predictions stations - the Bin number for tidal current prediction stations are available through the MetaData API and Soap Web Services Station Listing
◦ If a bin number is not used, the bin nearest the surface will be provided.
◦ Using an invalid number (like bin=-1) will provide an error message noting the valid bin numbers.

Option	Description
<numerical value>	The bin number requested

Examples:

bin=3

Returns currents data for bin number 3 of the specified station

Velocity Type

The Velocity Type can be specified with the "vel_type=" option parameter.
Note! This only applies to Current Predictions at Harmonic Stations.

Option	Description
speed_dir	Return results for speed and direction -the 2 dimensional speed and direction, may not match flood/ebb directions Note!only supports current prediction intervals of 1, 6, 10, 30, 60; does not apply to max_slack predictions.
default	Return results for velocity major, mean flood direction and mean ebb direction. If not included in the API query, the default is automatically used

Examples:

vel_type = speed_dir	Returns current predictions data in a velocity and direction output.
vel_type = default	Returns current predictions data in flood/ebb directions

Format

The data file output format can be specified.

Option	Description
xml	Extensible Markup Language. This format is an industry standard for data.
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.
csv	Comma Separated Values. This format is suitable for import into Microsoft Excel or other spreadsheet programs.

Examples:

format=xml

Returns data requested in xml format.

Application

This parameter provides an “identifier” in automated activity / error logs that allows us to identify your query from others.
This allows us to identify and assist you in correcting any problems encountered in your query.
• External Users: please use the name of your company, organization, application, your name, or a combination / variation of these.
• Internal NOAA Users: please include the office acronym and name of the application calling the API.
Initials, abbreviations or acronyms for part of the value are acceptable.
Separate words of the name can be separated by an underscore, or merged into a single entry.

Note! This is not a required parameter. Not including the parameter will make identifying issues through automated logs impossible.
Examples:

Your_Company	A user or application from Your Company has called the API
MyTideApp	An application, My Tide App, has called the API
John_Public	The customer, John Public, has called the API
UnivAlpha_AStudent	The customer, A. Student from University Alpha, has called the API
NWSMarineForecast	The NOAA National Weather Service (NWS), Marine Forecast application has called the API

Data API Response Descriptions

The formatted data responses (columns and data flags) for different data types are described in the Response Help Page.

Sample API Queries

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)