tsgettoolbox.tsgettoolbox.coops¶
- tsgettoolbox.tsgettoolbox.coops(station, date=None, begin_date=None, end_date=None, range=None, product='hourly_height', datum='NAVD', time_zone='GMT', interval='h', bin=None)¶
global:station::1T,6T,H,D,M:Center for Operational Oceanographic Products and Services
CO-OPS web services is at https://tidesandcurrents.noaa.gov/api/. The time zone of the returned data depends on the setting of the “time_zone” option. The default is “GMT” also known as “UTC”.
- Parameters:
station (
str) –A 7 character station ID, or a currents station ID.
Station listings for various products can be viewed at https://tidesandcurrents.noaa.gov or viewed on a map at Tides & Currents Station Map
date (str) –
[optional, default is None]
The API understands several parameters related to date ranges. Date formats are pretty flexible, however the closer to ISO 8601, the better.
The date related options are ‘begin_date’, ‘end_date’, ‘date’, and ‘range’. They can be combined in the following 5 ways, but if conflicting then follows the table in order. For example, the ‘date’ option will be used if present regardless of any other option, then ‘range’, …etc.:
Parameter Name(s)
Description
date
’latest’, ‘today’, or ‘recent’
range
Specify a number of hours to go back from now and retrieve data for that date range
begin_date and range
Specify a begin date and a number of hours to retrieve data starting from that date
begin_date and end_date
Specify the date/time range of retrieval
end_date and range
Specify an end date and a number of hours to retrieve data ending at that date
Description of “–date” option
Option
Today’s data
–date=’today’
The last 3 days of data
–date=’recent’
The last data point available within the last 18 minutes.
–date=’latest’
begin_date (
Optional[Timestamp]) –[optional, default is None]
The beginning date for the data. See explanation with the ‘date’ option on how to use all of the date related parameters.
end_date (
Optional[Timestamp]) –[optional, default is None]
The end date for the data. January 1st, 2012 through January 2nd, 2012:
--begin_date='20120101' --end_date='20120102'
See explanation with the ‘date’ option on how to use all of the date related parameters.
range (
Optional[int]) –[optional, default is None]
Specify the number of hours to go back from now, an ‘end_date’, or forward from a ‘begin_date’.
48 hours beginning on April 15, 2012:
--begin_date='20120415' --range=48
48 hours ending on March 17, 2012:
--end_date='20120307' --range=48
The last 24 hours from now:
--range=24
The last 3 hours from now:
--range=3
See explanation with the ‘date’ option on how to use all of the date related parameters.
product (str) –
[optional, default is ‘hourly_height’]
Specify the observation requested.
Option
Description
water_level
Six minute preliminary or verified water levels, depending on availability.
air_temperature
Air temperature
water_temperature
Water temperature
wind
Wind speed, direction, and gusts
air_gap
(distance between a bridge and the water’s surface)
conductivity
The water’s conductivity
visibility
Visibility from the station’s visibility sensor. A measure of atmospheric clarity.
humidity
Relative humidity
salinity
Salinity and specific gravity
hourly_height
Verified hourly height water level data
high_low
Verified high/low water level data
daily_mean
Verified daily mean water level data
monthly_mean
Verified monthly mean water level data
one_minute_water_level
One minute water level data
predictions
Six minute predictions water level data
datums
datums data
currents
Currents data
The returned data for each “product” documented below is derived from https://api.tidesandcurrents.noaa.gov/api/prod/responseHelp.html
product = “water_level”
tsgettoolbox Column Name
Description
water_level:{units}
Measurement
water_level_sigma:{units}
Standard deviation of 1 second samples used to compute the water level height
water_level_CntSigma OR water_level_Inferred
if preliminary Count of number of 1 second that falls outside a 3-sigma band about the mean if verified A flag that when set to 1 indicates that the water level value has been inferred
water_level_FlatTol
A flag that when set to 1 indicates that the flat tolerance limit was exceeded
water_level_RateTol
A flag that when set to 1 indicates that the rate of change tolerance limit was exceeded
water_level_LimitTol OR water_level_TempRateTol
if preliminary A flag that when set to 1 indicates that either the maximum or minimum expected value was exceeded if verified A flag that when set to 1 indicates that the rate of change in temperature tolerance limit was exceeded
water_level_quality:{units}
Quality Assurance/Quality Control “p” = preliminary “v” = verified
product = “air_pressure”, “air_temperature”, “humidity”, “water_temperature”, or “conductivity”
tsgettoolbox Column Name
Description
{product}:{units}
Measurement
{product}_MaxTol
A flag that when set to 1 indicates that the maximum expected value was exceeded
{product}_MinTol
A flag that when set to 1 indicates that the minimum expected value was exceeded
{product}_RateTol
A flag that when set to 1 indicates that the rate of change tolerance limit was exceeded
Hourly Height: product = “hourly_height”
tsgettoolbox Column Name
Description
hourly_height:{units}
Value - Measured water level height
hourly_height_sigma:{units}
Sigma - Standard deviation of 1 second samples used to compute the water level height
hourly_height_Inferred
A flag that when set to 1 indicates that the water level value has been inferred
hourly_height_LimitTol
A flag that when set to 1 indicates that either the maximum or minimum expected value was exceeded
High Low: product = “high_low”
tsgettoolbox Column Name
Description
high_low:{units}
Value - Measured water level height
high_low_Type
Type - Designation of Water level height. HH = Higher High water H = High water L = Low water LL = Lower Low water
high_low_Inferred
A flag that when set to 1 indicates that the water level value has been inferred
high_low_LimitTol
A flag that when set to 1 indicates that either the maximum or minimum expected value was exceeded
Daily Mean: product = “daily_mean”
tsgettoolbox Column Name
Description
daily_mean:{units}
Value – Mean hourly data over a 24 hour period
daily_mean_Inferred
A flag that when set to 1 indicates that the water level value has been inferred
daily_mean_LimitTol
A flag that when set to 1 indicates that either the maximum or minimum expected value was exceeded
Monthly Mean: product = “monthly_mean”
tsgettoolbox Column Name
Description
year
Year
month
Month
highest
Highest Tide
MHHW
Mean Higher-High Water
MHW
Mean High Water
MSL
Mean Sea Level
MTL
Mean Tide Level
MLW
Mean Low Water
MLLW
Mean Lower-Low Water
DTL
Mean Diurnal Tide Level
GT
Great Diurnal Range
MN
Mean Range of Tide
DHQ
Mean Diurnal High Water Inequality
DLQ
Mean Diurnal Low Water Inequality
HWI
Greenwich High Water Interval (in Hours)
LWI
Greenwich Low Water Interval (in Hours)
lowest
Lowest Tide
inferred
A flag that when set to 1 indicates that the water level value has been inferred
One Minute Water Level: product = “one_minute_water_level”
tsgettoolbox Column Name
Description
one_minute_water_level:{units}
Value - Measured water level height
Tide Predictions: product = “predictions”
tsgettoolbox Column Name
Description
predictions:{units}
Value - Predicted water level height
Air Gap: product = “air_gap”
tsgettoolbox Column Name
Description
air_gap:{units}
Value - Measured air gap
air_gap_sigma:{units}
Sigma - Standard deviation of 1 second samples used to compute the air gap
air_gap_CntSigma
Count of number of 1 second that falls outside a 3-sigma band about the mean
air_gap_FlatTol
A flag that when set to 1 indicates that the flat tolerance limit was exceeded
air_gap_RateTol
A flag that when set to 1 indicates that the rate of change tolerance limit was exceeded
air_gap_MinMaxTol
A flag that when set to 1 indicates that either the maximum or minimum expected air gap limit was exceeded
Wind: product = “wind”
tsgettoolbox Column Name
Description
wind_speed:{units}
Speed - Measured wind speed
wind_direction:degrees
Direction - wind direction in degrees
wind_direction:text
Direction - wind direction in text
wind_gust:{units}
Gust - Measured wind gust speed
wind{suffix}
Data Flags - in order of listing “X,R” Flags described above
Visibility: product = “visibility”
tsgettoolbox Column Name
Description
visibility:{units}
Value - Measured visibility
Salinity: product = “salinity”
tsgettoolbox Column Name
Description
salinity:{units}
Salinity
specific_gravity
Specific Gravity
Currents: product = “currents”
tsgettoolbox Column Name
Description
currents_speed:{units}
Speed - Measured current speed
currents_direction:degrees
Direction - current direction in degrees
currents_bin_number
Bin number
datum (
Literal['MHHW','MHW','MTL','MSL','MLW','MLLW','NAVD','STND']) –[optional, default is ‘NAVD’]
Specify the datum that all water levels will be reported against. Note! Datum is mandatory for all water level products and defaults to “NAVD”.
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
time_zone (
Literal['GMT','UTC','LST','LST_LDT']) –[optional, default is ‘GMT’]
The time zone is specified as ‘gmt’, ‘lst’ or ‘lst_ldt’.
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.
interval –
[optional, defaults to ‘h’]
Deliver the meteorological and prediction data at hourly intervals. Does not override 6 minute intervals for –product=’water_level’ or 1 minute intervals for –product=’one_minute_water_level’.
Option
Description
h
Hourly meteorological data
hilo
High/low predictions for subordinate stations
bin –
[optional, defaults to None]
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.
