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=None)

Deprecated since version 0.4.0: Use get_coops_stations() instead.

retrieve a list of CO-OPS stations with associated metadata

Parameters:

station_status (COOPS_StationStatus | None) – one of active or discontinued

Returns:

GeoDataFrame – 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=None, station_status=None)

Deprecated since version 0.4.0: Use get_coops_stations() instead.

Retrieve all stations within the specified region of interest

Parameters:

• region (Polygon | None) – polygon or multipolygon denoting region of interest

• station_status (COOPS_StationStatus | None) – one of active or discontinued

Returns:

GeoDataFrame – 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)

a specific CO-OPS station

Parameters:

id (int | str) – 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, start_date, end_date=None, interval=None, datum=None)

retrieve data for the current station within the specified parameters

Parameters:

• product (COOPS_Product) – CO-OPS product

• start_date (datetime) – start date

• end_date (datetime | None) – end date

• interval (COOPS_Interval | None) – time interval of data

• datum (COOPS_TidalDatum | None) – tidal datum

Returns:

Dataset – 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, region, start_date, end_date=None, datum=None, interval=None, station_status=None)

Deprecated since version 0.4.0: Use fetch_coops_station() instead.

Retrieve CO-OPS data from within the specified region of interest

Parameters:

• product (COOPS_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 | MultiPolygon) – polygon or multipolygon denoting region of interest

• start_date (datetime) – start date of CO-OPS query

• end_date (datetime | None) – start date of CO-OPS query

• datum (COOPS_TidalDatum | None) – tidal datum

• interval (COOPS_Interval | None) – data time interval

• station_status (COOPS_StationStatus | None) – either active or discontinued

Returns:

Dataset – 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, product, start_date, end_date=None, datum=None, units=None, time_zone=None, interval=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 (int) – NOS station ID

• product (COOPS_Product) – CO-OPS product

• start_date (datetime) – start date

• end_date (datetime | None) – end date

• datum (COOPS_TidalDatum | None) – station datum

• units (COOPS_Units | None) – one of metric, english

• time_zone (COOPS_TimeZone | None) – time zone of data

• interval (COOPS_Interval | None) – 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]

New API

searvey.get_coops_stations(region=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, metadata_source='nws')

Return COOPS station metadata from either COOPS metadata API at https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi or from the COOPS NWS product table at https://access.co-ops.nos.noaa.gov/nwsproducts.html

If region is defined then the stations that are outside of the region are filtered out.. If the coordinates of the Bounding Box are defined then stations outside of the BBox are filtered out. If both region and the Bounding Box are defined, then an exception is raised.

Note: The longitudes of the COOPS stations are in the [-180, 180] range.

Parameters:

• region (MultiPolygon | Polygon | None) – Polygon or MultiPolygon denoting region of interest

• lon_min (float | None) – The minimum Longitude of the Bounding Box.

• lon_max (float | None) – The maximum Longitude of the Bounding Box.

• lat_min (float | None) – The minimum Latitude of the Bounding Box.

• lat_max (float | None) – The maximum Latitude of the Bounding Box.

• metadata_source (COOPS_StationMetadataSource | str) – Metadata API to be used: ‘nws’ or ‘main’

Returns:

GeoDataFrame – pandas.DataFrame with the station metadata

searvey.fetch_coops_station(station_id, start_date=None, end_date=None, *, rate_limit=None, http_client=None, multiprocessing_executor=None, multithreading_executor=None, progress_bar=False, product=COOPS_Product.WATER_LEVEL, datum=COOPS_TidalDatum.MSL, units=COOPS_Units.METRIC, interval=COOPS_Interval.NONE, **aux_params)

Make a query to the COOPS API for tide gauge data for station_id and return the results as a pandas.Dataframe.

start_date and end_date can be of any type that is valid for pandas.to_datetime(). If start_date or end_date are timezone-aware timestamps they are coersed to UTC. The returned data are always in UTC.

Each query to the COOPS API can request up to 30 days of data. When we request data for larger time spans, multiple requests are made. This is where rate_limit, multiprocessing_executor and multithreading_executor come into play.

In order to make the data retrieval more efficient, a multithreading pool is spawned and the requests are executed concurrently, while adhering to the rate_limit. The parsing of the JSON responses is a CPU heavy process so it is made within a multiprocessing Pool.

If no arguments are specified, then sensible defaults are being used, but if the pools need to be configured, an executor instance needs to be passed as an argument. For example:

executor = concurrent.futures.ProcessPoolExecutor(max_workers=4)
df = fetch_coops_station("acap", multiprocessing_executor=executor)

Parameters:

• station_id (str) – The station identifier. In COOPS terminology, this is called coops_code.

• start_date (str | date | Timestamp | datetime | datetime64 | None) – The starting date of the query. Defaults to 7 days ago.

• end_date (str | date | Timestamp | datetime | datetime64 | None) – The finishing date of the query. Defaults to “now”.

• rate_limit (RateLimit | None) – The rate limit for making requests to the COOPS servers. Defaults to 5 requests/second.

• http_client (Client | None) – The httpx.Client.

• multiprocessing_executor (ExecutorProtocol | None) – An instance of a class implementing the concurrent.futures.Executor API.

• multithreading_executor (ExecutorProtocol | None) – An instance of a class implementing the concurrent.futures.Executor API.

• progress_bar (bool) – If True then a progress bar is displayed for monitoring the progress of the outgoing requests.

Return type:

DataFrame