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
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."
}
}