pygeohydro.stnfloodevents

Access USGS Short-Term Network (STN) via Restful API.

Module Contents

class pygeohydro.stnfloodevents.STNFloodEventData

Client for STN Flood Event Data’s RESTFUL Service API.

Advantages of using this client are:

• The user does not need to know the details of RESTFUL in general and of this API specifically.

• Parses the data and returns Python objects (e.g., pandas.DataFrame, geopandas.GeoDataFrame) instead of JSON.

• Convenience functions are offered for data dictionaries.

• Geo-references the data where applicable.

service_url

The service url of the STN Flood Event Data RESTFUL Service API.

Type:

str

data_dictionary_url

The data dictionary url of the STN Flood Event Data RESTFUL Service API.

Type:

str

service_crs

The CRS of the data from the service which is EPSG:4326.

Type:

int

instruments_query_params

The accepted query parameters for the instruments data type. Accepted values are SensorType, CurrentStatus, States, Event, County, DeploymentType, EventType, EventStatus, and CollectionCondition.

Type:

set

peaks_query_params

The accepted query parameters for the peaks data type. Accepted values are EndDate, States, Event, StartDate, County, EventType, and EventStatus.

Type:

set

hwms_query_params

The accepted query parameters for the hwms data type. Accepted values are EndDate, States, Event, StartDate, County, EventType, and EventStatus.

Type:

set

sites_query_params

The accepted query parameters for the sites data type. Accepted values are OPDefined, HousingTypeOne, NetworkName, HousingTypeSeven, RDGOnly, HWMOnly, Event, SensorOnly, State, SensorType, and HWMSurveyed.

Type:

set

Notes

Point data from the service is assumed to be in the WGS84 coordinate reference system (EPSG:4326).

References

• USGS Short-Term Network (STN)

• All Sensors API Documentation

• All Peak Summary API Documentation

• All HWM API Documentation

• All Sites API Documentation

• USGS Flood Event Viewer: Providing Hurricane and Flood Response Data

• A USGS guide for finding and interpreting high-water marks

• High-Water Marks and Flooding

• Identifying and preserving high-water mark data

classmethod data_dictionary(data_type: str, *, as_dict: Literal[False] = False, async_retriever_kwargs: dict[str, Any] | None = None) → pandas.DataFrame

classmethod data_dictionary(data_type: str, *, as_dict: Literal[True], async_retriever_kwargs: dict[str, Any] | None = None) → dict[str, Any]

Retrieve data dictionaries from the STN Flood Event Data API.

Parameters:

• data_type (str) – The data source from STN Flood Event Data API. It can be instruments, peaks, hwms, or sites.

• as_dict (bool, default = False) – If True, return the data dictionary as a dictionary. Otherwise, it returns as pandas.DataFrame.

• async_retriever_kwargs (dict, optional) – Additional keyword arguments to pass to async_retriever.retrieve_json(). The url and request_kwds options are already set.

Returns:

pandas.DataFrame or dict – The retrieved data dictionary as pandas.DataFrame or dict.

See also

get_all_data()

Retrieves all data for a given data type.

get_filtered_data()

Retrieves filtered data for a given data type.

Examples

>>> from pygeohydro import STNFloodEventData
>>> data = STNFloodEventData.data_dictionary(data_type="instruments", as_dict=False)  
>>> data.shape[1]  
2
>>> data.columns  
Index(['Field', 'Definition'], dtype='object')

classmethod get_all_data(data_type: str, *, as_list: Literal[False] = False, crs: CRSTYPE = 4326, async_retriever_kwargs: dict[str, Any] | None = None) → geopandas.GeoDataFrame | pandas.DataFrame

classmethod get_all_data(data_type: str, *, as_list: Literal[True], crs: CRSTYPE = 4326, async_retriever_kwargs: dict[str, Any] | None = None) → list[dict[str, Any]]

Retrieve all data from the STN Flood Event Data API.

Parameters:

• data_type (str) – The data source from STN Flood Event Data API. It can be instruments, peaks, hwms, or sites.

• as_list (bool, optional) – If True, return the data as a list, defaults to False.

• crs (int, str, or pyproj.CRS, optional) – Desired Coordinate reference system (CRS) of output. Only used for GeoDataFrames with hwms and sites data types.

• async_retriever_kwargs (dict, optional) – Additional keyword arguments to pass to async_retriever.retrieve_json(). The url and request_kwds options are already set.

Returns:

geopandas.GeoDataFrame or pandas.DataFrame or list of dict – The retrieved data as a GeoDataFrame, DataFrame, or a list of dictionaries.

Raises:

InputValueError – If the input data_type is not one of instruments, peaks, hwms, or sites

See also

get_filtered_data()

Retrieves filtered data for a given data type.

data_dictionary()

Retrieves the data dictionary for a given data type.

Notes

Notice schema differences between the data dictionaries, filtered data queries, and all data queries. This is a known issue and is being addressed by USGS.

Examples

>>> from pygeohydro.stnfloodevents import STNFloodEventData
>>> data = STNFloodEventData.get_all_data(data_type="instruments")
>>> data.shape[1]
18
>>> data.columns
Index(['instrument_id', 'sensor_type_id', 'deployment_type_id',
       'location_description', 'serial_number', 'interval', 'site_id',
       'event_id', 'inst_collection_id', 'housing_type_id', 'sensor_brand_id',
       'vented', 'instrument_status', 'data_files', 'files', 'last_updated',
       'last_updated_by', 'housing_serial_number'],
       dtype='object')

classmethod get_filtered_data(data_type: str, query_params: dict[str, Any] | None = None, *, as_list: Literal[False] = False, crs: CRSTYPE = 4326, async_retriever_kwargs: dict[str, Any] | None = None) → geopandas.GeoDataFrame | pandas.DataFrame

classmethod get_filtered_data(data_type: str, query_params: dict[str, Any] | None = None, *, as_list: Literal[True], crs: CRSTYPE = 4326, async_retriever_kwargs: dict[str, Any] | None = None) → list[dict[str, Any]]

Retrieve filtered data from the STN Flood Event Data API.

Parameters:

• data_type (str) – The data source from STN Flood Event Data API. It can be instruments, peaks, hwms, or sites.

• query_params (dict, optional) – RESTFUL API query parameters. For accepted values, see the STNFloodEventData class attributes instruments_query_params, peaks_query_params, hwms_query_params, and sites_query_params for available values.

  Also, see the API documentation for each data type for more information:

  • instruments

  • peaks

  • hwms

  • sites

• as_list (bool, optional) – If True, return the data as a list, defaults to False.

• crs (int, str, or pyproj.CRS, optional) – Desired Coordinate reference system (CRS) of output. Only used for GeoDataFrames outputs.

• async_retriever_kwargs (dict, optional) – Additional keyword arguments to pass to async_retriever.retrieve_json(). The url and request_kwds options are already set.

Returns:

geopandas.GeoDataFrame or pandas.DataFrame or list of dict – The retrieved data as a GeoDataFrame, DataFrame, or a list of dictionaries.

Raises:

• InputValueError – If the input data_type is not one of instruments, peaks, hwms, or sites

• InputValueError – If any of the input query_params are not in accepted parameters (See instruments_query_params, peaks_query_params, hwms_query_params, or sites_query_params).

See also

get_all_data()

Retrieves all data for a given data type.

data_dictionary()

Retrieves the data dictionary for a given data type.

Notes

Notice schema differences between the data dictionaries, filtered data queries, and all data queries. This is a known issue and is being addressed by USGS.

Examples

>>> from pygeohydro.stnfloodevents import STNFloodEventData
>>> query_params = {"States": "SC, CA"}
>>> data = STNFloodEventData.get_filtered_data(data_type="instruments", query_params=query_params)
>>> data.shape[1]
34
>>> data.columns
Index(['sensorType', 'deploymentType', 'eventName', 'collectionCondition',
    'housingType', 'sensorBrand', 'statusId', 'timeStamp', 'site_no',
    'latitude', 'longitude', 'siteDescription', 'networkNames', 'stateName',
    'countyName', 'siteWaterbody', 'siteHDatum', 'sitePriorityName',
    'siteZone', 'siteHCollectMethod', 'sitePermHousing', 'instrument_id',
    'sensor_type_id', 'deployment_type_id', 'location_description',
    'serial_number', 'housing_serial_number', 'interval', 'site_id',
    'vented', 'instrument_status', 'data_files', 'files', 'geometry'],
    dtype='object')

pygeohydro.stnfloodevents.stn_flood_event(data_type, query_params=None)

Retrieve data from the STN Flood Event Data API.

Parameters:

• data_type (str) – The data source from STN Flood Event Data API. It can be instruments, peaks, hwms, or sites.

• query_params (dict, optional) – RESTFUL API query parameters, defaults to None which returns a pandas.DataFrame of information about the given data_type. For accepted values, see the STNFloodEventData class attributes instruments_query_params, peaks_query_params, hwms_query_params, and sites_query_params for available values.

  Also, see the API documentation for each data type for more information:

  • instruments

  • peaks

  • hwms

  • sites

Returns:

geopandas.GeoDataFrame or pandas.DataFrame – The retrieved data as a GeoDataFrame or DataFrame (if query_params is not passed).

Raises:

• InputValueError – If the input data_type is not one of instruments, peaks, hwms, or sites

• InputValueError – If any of the input query_params are not in accepted parameters.

Return type:

geopandas.GeoDataFrame | pandas.DataFrame

References

• USGS Short-Term Network (STN)

• Filtered Sensors API Documentation

• Peak Summary API Documentation

• Filtered HWM API Documentation

• Filtered Sites API Documentation

• USGS Flood Event Viewer: Providing Hurricane and Flood Response Data

• A USGS guide for finding and interpreting high-water marks

• High-Water Marks and Flooding

• Identifying and preserving high-water mark data

Notes

Notice schema differences between the data dictionaries, filtered data queries, and all data queries. This is a known issue and is being addressed by USGS.

Examples

>>> query_params = {"States": "SC, CA"}
>>> data = stn_flood_event("instruments", query_params=query_params)
>>> data.shape[1]
34
>>> data.columns
Index(['sensorType', 'deploymentType', 'eventName', 'collectionCondition',
    'housingType', 'sensorBrand', 'statusId', 'timeStamp', 'site_no',
    'latitude', 'longitude', 'siteDescription', 'networkNames', 'stateName',
    'countyName', 'siteWaterbody', 'siteHDatum', 'sitePriorityName',
    'siteZone', 'siteHCollectMethod', 'sitePermHousing', 'instrument_id',
    'sensor_type_id', 'deployment_type_id', 'location_description',
    'serial_number', 'housing_serial_number', 'interval', 'site_id',
    'vented', 'instrument_status', 'data_files', 'files', 'geometry'],
    dtype='object')