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
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
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
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). 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”
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 Observed tidal datum values at the station for the present National Tidal Datum Epoch (NTDE).
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>
currents_predictions Currents prediction data for the stations. Note! See Interval for options available and data length limitations.
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


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)
english English units (fahrenheit, feet, knots appropriate for the data)
Note!Visibility data is Nautical Miles (nm)
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 datums or 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 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 current data on the hour.

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.
• 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.
• 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

Note! The order of specific parameters listed in the query is flexible. The samples below use the parameter order created by our API Builder Tool.


• Real Time Water Levels Data - 9414290 San Francisco, CA - Today.
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?date=today&station=9414290&product=water_level&datum=MLLW&time_zone=gmt&units=english&application=DataAPI_Sample&format=xml


• Verified Hourly Heights Data - 8518750 The Battery, NY - 2020
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?begin_date=20200101&end_date=20201231&station=8518750&product=hourly_height&datum=MLLW&time_zone=lst&units=metric&application=DataAPI_Sample&format=json

• Tide Predictions (high/low) - 8557863 Rehoboth Beach, MD - August 2025
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?begin_date=20250801&end_date=20250831&station=8557863&product=predictions&datum=MLLW&time_zone=lst_ldt&interval=hilo&units=english&application=DataAPI_Sample&format=xml

• Wind Data (Hourly) - 8724580 Key West, FL - June 2021
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?begin_date=20210601&end_date=20210630&station=8724580&product=wind&time_zone=lst_ldt&interval=h&units=english&application=DataAPI_Sample&format=csv

• Visibility Data - 8453662 Providence Visibility (kilometers) - Today
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?date=today&station=8453662&product=visibility&time_zone=lst_ldt&units=metric&format=csv

• Real Time Currents Data - cb0102 Cape Henry (PORTS station) - Today
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?date=today&station=cb0102&product=currents&time_zone=gmt&units=english&application=DataAPI_Sample&format=xml

• Historical Currents Survey Data - CFR1624 Southport, NC; 10ft depth (bin 9) - April 2016
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?begin_date=20160401&end_date=20160430&station=CFR1624&product=currents&time_zone=gmt&units=english&application=DataAPI_Sample&format=csv&bin=9

• Current Predictions (10 minute Interval, flood/ebb direction) - EPT0003 Eastport, Estes Head - Today
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?date=today&station=EPT0003&product=currents_predictions&time_zone=gmt&interval=10&units=english&application=DataAPI_Sample&format=xml&bin=14

• Current Predictions (10 Minute Interval, speed/direction) - EPT0003 Eastport, Estes Head - Today
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?date=today&station=EPT0003&product=currents_predictions&time_zone=gmt&interval=10&units=english&vel_type=speed_dir&application=DataAPI_Sample&format=xml&bin=14

• Current Predictions (Max/Slack) - PCT1291 Grays Harbor Entrance, WA - November 2022
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?begin_date=20221101&end_date=20221130&station=PCT1291&product=currents_predictions&time_zone=lst&interval=MAX_SLACK&units=english&application=DataAPI_Sample&format=xml&bin=1

• OFS Water Level (6-min) - 8638610 Sewells Point, VA (CBOFS)
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?begin_date=20220701&end_date=20220703&station=8638610&product=ofs_water_level&datum=MLLW&time_zone=gmt&units=english&format=xml

• OFS Water Level (6-min) - 9063020 Buffalo, NY (LEOFS)
https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?begin_date=20220701&end_date=20220703&station=9063020&product=ofs_water_level&datum=LWD&time_zone=gmt&units=english&format=xml


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)