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 or discontinued

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 or discontinued

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:

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

2. a region within which to retrieve the data product

3. 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 or discontinued

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]