CO-OPS tidal station data¶
The Center for Operational Oceanographic Products and Services (CO-OPS) maintains and operates a large array of tidal buoys and oceanic weather stations that measure water and atmospheric variables across the coastal United States. CO-OPS provides several data products including hourly water levels, tidal datums and predictions, and trends in sea level over time.
A list of CO-OPS stations can be retrieved with the coops_stations()
function.
- searvey.coops.coops_stations(station_status: StationStatus | None = None) GeoDataFrame ¶
retrieve a list of CO-OPS stations with associated metadata
- Parameters:
station_status – one of
active
ordiscontinued
- Returns:
data frame of stations
>>> coops_stations() nws_id name state status removed geometry nos_id 1600012 46125 QREB buoy active <NA> POINT (122.62500 37.75000) 8735180 DILA1 Dauphin Island AL active 2019-07-18 10:00:00,2018-07-30 16:40:00,2017-0... POINT (-88.06250 30.25000) 8557380 LWSD1 Lewes DE active 2019-08-01 00:00:00,2018-06-18 00:00:00,2017-0... POINT (-75.12500 38.78125) 8465705 NWHC3 New Haven CT active 2019-08-18 14:55:00,2019-08-18 14:54:00,2018-0... POINT (-72.93750 41.28125) 9439099 WAUO3 Wauna OR active 2019-08-19 22:59:00,2014-06-20 21:30:00,2013-0... POINT (-123.43750 46.15625) ... ... ... ... ... ... ... 8448725 MSHM3 Menemsha Harbor, MA MA discontinued 2013-09-26 23:59:00,2013-09-26 00:00:00,2012-0... POINT (-70.75000 41.34375) 8538886 TPBN4 Tacony-Palmyra Bridge NJ discontinued 2013-11-11 00:01:00,2013-11-11 00:00:00,2012-0... POINT (-75.06250 40.00000) 9439011 HMDO3 Hammond OR discontinued 2014-08-13 00:00:00,2011-04-12 23:59:00,2011-0... POINT (-123.93750 46.18750) 8762372 LABL1 East Bank 1, Norco, B. LaBranche LA discontinued 2012-11-05 10:38:00,2012-11-05 10:37:00,2012-1... POINT (-90.37500 30.04688) 8530528 CARN4 CARLSTADT, HACKENSACK RIVER NJ discontinued 1994-11-12 23:59:00,1994-11-12 00:00:00 POINT (-74.06250 40.81250) [436 rows x 6 columns] >>> coops_stations(station_status='active') nws_id name state status removed geometry nos_id 1600012 46125 QREB buoy active <NA> POINT (122.62500 37.75000) 1611400 NWWH1 Nawiliwili HI active <NA> POINT (-159.37500 21.95312) 1612340 OOUH1 Honolulu HI active <NA> POINT (-157.87500 21.31250) 1612480 MOKH1 Mokuoloe HI active <NA> POINT (-157.75000 21.43750) 1615680 KLIH1 Kahului, Kahului Harbor HI active <NA> POINT (-156.50000 20.89062) ... ... ... ... ... ... ... 9759394 MGZP4 Mayaguez PR active <NA> POINT (-67.18750 18.21875) 9759938 MISP4 Mona Island active <NA> POINT (-67.93750 18.09375) 9761115 BARA9 Barbuda active <NA> POINT (-61.81250 17.59375) 9999530 FRCB6 Bermuda, Ferry Reach Channel active <NA> POINT (-64.68750 32.37500) 9999531 Calcasieu Test Station LA active <NA> POINT (-93.31250 29.76562) [365 rows x 6 columns] >>> coops_stations(station_status='discontinued') nws_id name state status removed geometry nos_id 8530528 CARN4 CARLSTADT, HACKENSACK RIVER NJ discontinued 1994-11-12 23:59:00,1994-11-12 00:00:00 POINT (-74.06250 40.81250) 9415064 NCHC1 ANTIOCH, SAN JOAQUIN RIVER CA discontinued 1997-03-03 23:59:00,1997-03-03 00:00:00 POINT (-121.81250 38.03125) 9415316 RVXC1 Rio Vista CA discontinued 1997-03-04 23:59:00,1997-03-04 00:00:00 POINT (-121.68750 38.15625) 9440572 ILWW1 JETTY A, COLUMBIA RIVER WA discontinued 1997-04-11 23:00:00 POINT (-124.06250 46.28125) 8760551 SPSL1 South Pass LA discontinued 2000-09-26 23:59:00,2000-09-26 00:00:00,1998-1... POINT (-89.12500 28.98438) ... ... ... ... ... ... ... 8726667 MCYF1 Mckay Bay Entrance FL discontinued 2020-05-20 00:00:00,2019-03-08 00:00:00,2017-0... POINT (-82.43750 27.90625) 8772447 FCGT2 Freeport TX discontinued 2020-05-24 18:45:00,2018-10-10 21:50:00,2018-1... POINT (-95.31250 28.93750) 9087079 GBWW3 Green Bay WI discontinued 2020-10-28 13:00:00,2007-08-06 23:59:00,2007-0... POINT (-88.00000 44.53125) 8770570 SBPT2 Sabine Pass North TX discontinued 2021-01-18 00:00:00,2020-09-30 15:45:00,2020-0... POINT (-93.87500 29.73438) 8740166 GBRM6 Grand Bay NERR, Mississippi Sound MS discontinued 2022-04-07 00:00:00,2022-03-30 23:58:00,2015-1... POINT (-88.37500 30.40625) [71 rows x 6 columns]
Additionally, you can use a Shapely Polygon
or MultiPolygon
to constrain the stations query to a specific region:
- searvey.coops.coops_stations_within_region(region: Polygon | None = None, station_status: StationStatus | None = None) GeoDataFrame ¶
retrieve all stations within the specified region of interest
- Parameters:
region – polygon or multipolygon denoting region of interest
station_status – one of
active
ordiscontinued
- Returns:
data frame of stations within the specified region
>>> import shapely >>> east_coast = shapely.geometry.box(-85, 25, -65, 45) >>> coops_stations_within_region(east_coast) nws_id name state status removed geometry nos_id 8726412 MTBF1 Middle Tampa Bay active <NA> POINT (-82.62500 27.65625) 8726679 TSHF1 East Bay Causeway FL active <NA> POINT (-82.43750 27.92188) 8726694 TPAF1 TPA Cruise Terminal 2 FL active <NA> POINT (-82.43750 27.93750) 9044036 FWNM4 Fort Wayne MI active 2005-04-29 23:59:00,2005-04-29 00:00:00,2001-1... POINT (-83.06250 42.31250) 9075035 ESVM4 Essexville MI active 2007-03-28 23:59:00,2007-03-28 00:00:00,2007-0... POINT (-83.87500 43.62500) ... ... ... ... ... ... ... 8720503 GCVF1 Red Bay Point, St Johns River FL discontinued 2017-10-07 20:54:00,2017-10-07 10:54:00,2017-1... POINT (-81.62500 29.98438) 8654400 CFPN7 Cape Hatteras Fishing Pier NC discontinued 2018-09-19 23:59:00,2003-09-18 23:59:00,2003-0... POINT (-75.62500 35.21875) 8720625 RCYF1 Racy Point, St Johns River FL discontinued 2019-08-05 14:00:00,2017-06-14 15:36:00,2017-0... POINT (-81.56250 29.79688) 8423898 FTPN3 Fort Point NH discontinued 2020-04-13 00:00:00,2014-08-05 00:00:00,2012-0... POINT (-70.68750 43.06250) 8726667 MCYF1 Mckay Bay Entrance FL discontinued 2020-05-20 00:00:00,2019-03-08 00:00:00,2017-0... POINT (-82.43750 27.90625) [164 rows x 6 columns]
CO-OPS station class¶
- class searvey.coops.COOPS_Station(id: int | str)¶
a specific CO-OPS station
- Parameters:
id – NOS ID, NWS ID, or station name
from NOS ID:
>>> COOPS_Station(1612480) COOPS_Station(1612480)
from NWS ID:
>>> COOPS_Station('OOUH1') COOPS_Station(1612340)
from station name:
>>> COOPS_Station('San Mateo Bridge') COOPS_Station(9414458)
- property constituents: DataFrame¶
return: table of tidal constituents for the current station
- product(product: COOPS_Product, start_date: datetime, end_date: datetime | None = None, interval: COOPS_Interval | None = None, datum: COOPS_TidalDatum | None = None) Dataset ¶
retrieve data for the current station within the specified parameters
- Parameters:
product – CO-OPS product
start_date – start date
end_date – end date
interval – time interval of data
datum – tidal datum
- Returns:
data for the current station within the specified parameters
>>> station = COOPS_Station(8632200) >>> station.product('water_level', start_date=datetime(2018, 9, 13), end_date=datetime(2018, 9, 16, 12)) <xarray.Dataset> Dimensions: (nos_id: 1, t: 841) Coordinates: * nos_id (nos_id) int64 8632200 * t (t) datetime64[ns] 2018-09-13 ... 2018-09-16T12:00:00 nws_id (nos_id) <U5 'KPTV2' x (nos_id) float64 -76.0 y (nos_id) float64 37.16 Data variables: v (nos_id, t) float32 1.67 1.694 1.73 1.751 ... 1.597 1.607 1.605 s (nos_id, t) float32 0.026 0.027 0.034 0.03 ... 0.018 0.019 0.021 f (nos_id, t) object '0,0,0,0' '0,0,0,0' ... '0,0,0,0' '0,0,0,0' q (nos_id, t) object 'v' 'v' 'v' 'v' 'v' 'v' ... 'v' 'v' 'v' 'v' 'v'
retrieve CO-OPS data product from within a region and time interval¶
To retrieve data, you must provide three things:
- the data product of interest; one of
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.
a region within which to retrieve the data product
a time interval within which to retrieve the data product
- searvey.coops.coops_product_within_region(product: COOPS_Product, region: Polygon | MultiPolygon, start_date: datetime, end_date: datetime | None = None, datum: COOPS_TidalDatum | None = None, interval: COOPS_Interval | None = None, station_status: StationStatus | None = None) Dataset ¶
retrieve CO-OPS data from within the specified region of interest
- Parameters:
product – CO-OPS product; one of
water_level
,air_temperature
,water_temperature
,wind
,air_pressure
,air_gap
,conductivity
,visibility
,humidity
,salinity
,hourly_height
,high_low
,daily_mean
,monthly_mean
,one_minute_water_level
,predictions
,datums
,currents
,currents_predictions
region – polygon or multipolygon denoting region of interest
start_date – start date of CO-OPS query
end_date – start date of CO-OPS query
datum – tidal datum
interval – data time interval
station_status – either
active
ordiscontinued
- Returns:
array of data within the specified region
>>> from datetime import datetime, timedelta >>> import shapely >>> east_coast = shapely.geometry.box(-85, 25, -65, 45) >>> coops_product_within_region('water_level', region=east_coast, start_date=datetime(2022, 4, 2, 12), end_date=datetime(2022, 4, 2, 12, 30)) <xarray.Dataset> Dimensions: (t: 6, nos_id: 111) Coordinates: * t (t) datetime64[ns] 2022-04-02T12:00:00 ... 2022-04-02T12:30:00 * nos_id (nos_id) int64 9044036 9075035 9052076 ... 8516945 9052000 8638901 nws_id (nos_id) <U5 'FWNM4' 'ESVM4' 'OCTN6' ... 'KPTN6' 'CAVN6' 'CHBV2' x (nos_id) float64 -83.06 -83.88 -78.75 ... -73.75 -76.31 -76.06 y (nos_id) float64 42.31 43.62 43.34 42.09 ... 40.81 44.12 37.03 Data variables: v (nos_id, t) float32 175.1 175.1 175.1 175.1 ... 2.084 2.089 2.096 s (nos_id, t) float32 0.0 0.0 0.0 0.0 0.0 ... 0.059 0.076 0.088 0.08 f (nos_id, t) object '0,0,0,0' '0,0,0,0' ... '1,0,0,0' '1,0,0,0' q (nos_id, t) object 'p' 'p' 'p' 'p' 'p' 'p' ... 'p' 'p' 'p' 'p' 'p'
CO-OPS query class¶
The COOPS_Query
class lets you send an individual query to the CO-OPS API by specifying a station, data product, and time interval.
- class searvey.coops.COOPS_Query(station: int, product: COOPS_Product, start_date: datetime, end_date: datetime | None = None, datum: COOPS_TidalDatum | None = None, units: COOPS_Units | None = None, time_zone: COOPS_TimeZone | None = None, interval: COOPS_Interval | None = None)¶
abstraction of an individual query to the CO-OPS API https://api.tidesandcurrents.noaa.gov/api/prod/
instantiate a new query with the specified parameters
- Parameters:
station – NOS station ID
product – CO-OPS product
start_date – start date
end_date – end date
datum – station datum
units – one of metric, english
time_zone – time zone of data
interval – time interval of data
- Returns:
data for the current station within the specified parameters
>>> COOPS_Query(1612480, start_date='2022-01-01', end_date='2022-01-03') COOPS_Query(1612480, datetime.datetime(2022, 1, 1, 0, 0), datetime.datetime(2022, 1, 3, 0, 0), 'water_level', 'MLLW', 'metric', 'gmt', 'h')
- property data: DataFrame¶
return: data for the current query parameters
>>> query = COOPS_Query(1612480, 'water_level', start_date='2022-01-01', end_date='2022-01-03') >>> query.data v s f q t 2022-01-01 00:00:00 1.193 0.002 0,0,0,0 v 2022-01-01 00:06:00 1.180 0.002 0,0,0,0 v 2022-01-01 00:12:00 1.167 0.002 0,0,0,0 v 2022-01-01 00:18:00 1.156 0.003 0,0,0,0 v 2022-01-01 00:24:00 1.147 0.003 0,0,0,0 v ... ... ... .. 2022-01-02 23:36:00 1.229 0.004 0,0,0,0 v 2022-01-02 23:42:00 1.219 0.003 0,0,0,0 v 2022-01-02 23:48:00 1.223 0.004 0,0,0,0 v 2022-01-02 23:54:00 1.217 0.004 0,0,0,0 v 2022-01-03 00:00:00 1.207 0.002 0,0,0,0 v [481 rows x 4 columns]