Python package for accessing CDSS API web services
Project description
cdsspy
The goal of cdsspy
is to provide functions that help Python users to navigate, explore, and make requests to the CDSS REST API web service.
The Colorado’s Decision Support Systems (CDSS) is a water management system created and developed by the Colorado Water Conservation Board (CWCB) and the Colorado Division of Water Resources (DWR).
Thank you to those at CWCB and DWR for providing an accessible and well documented REST API!
Installation
Install the latest version of cdsspy
from PyPI:
pip install cdsspy
Available endpoints
Below is a table of all of the CDSS API endpoints cdsspy
has
functions for.
- | Function | Description | Endpoint |
---|---|---|---|
1 | get_admin_calls() | Returns list of active/historic administrative calls | administrativecalls/active |
2 | get_structures() | Returns list of administrative structures | structures |
3 | get_structures_divrec() | Returns list of diversion/release/stage records based on WDID | structures/divrec/ |
4 | get_climate_stations() | Returns Climate Stations | climatedata/climatestations |
5 | get_climate_ts() | Returns Climate Station Time Series (day, month, year) | climatedata/climatestationts |
6 | get_gw_gplogs_wells() | Returns Groundwater GeophysicalLogsWell from filters | groundwater/geophysicallogs/ |
7 | get_gw_gplogs_geologpicks() | Returns Groundwater Geophysical Log picks by well ID | groundwater/geophysicallogs/ |
7 | get_gw_wl_wells() | Returns WaterLevelsWell from filters | groundwater/waterlevels/wells |
6 | get_gw_wl_wellmeasures() | Returns Groundwater Measurements | groundwater/waterlevels/wellmeasurements |
8 | get_reference_tbl() | Returns reference tables list | referencetables/ |
9 | get_sw_stations() | Returns Surface Water Station info | surfacewater/surfacewaterstations |
10 | get_sw_ts() | Returns Surface Water Time Series | surfacewater/surfacewaterts |
11 | get_telemetry_stations() | Returns telemetry stations and their most recent parameter reading | telemetrystations/telemetrystation |
12 | get_telemetry_ts() | Returns telemetry time series data (raw, hour, day) | telemetrystations/telemetrytimeseries |
Identify query inputs using reference tables
The get_reference_tbl() function will return tables that makes it easier to know what information should be supplied to the data retrieval functions in cdsspy. For more information on the exact reference tables click here.
Let’s locate the parameters available at telemetry stations.
# available parameters for telemetry stations
telemetry_params = cdsspy.get_reference_tbl(
table_name = "telemetryparams"
)
Locate stations
We can use the get_<endpoint>_stations() set of functions to identify different types of stations within a given water district, division, or county. Station data can also be retrieved by providing a specific station abbreviation, GNIS ID, USGS ID, or WDID.
Here we locate all the telemetry stations within water district 6:
# identify telemetry stations in water district 6
stations = cdsspy.get_telemetry_stations(
water_district = "6"
)
Retrieve Telemetry station timeseries data
The get_<endpoint>_ts() set of functions retrieve timeseries data from the CDSS API.
We can then take a station abbreviations from the get_telemetry_stations() call, a parameter from the get_reference_tbl() call, and use this information as inputs into the get_telemetry_ts() function.
The function call below with return a daily discharge timeseries for the ANDDITCO site between 2015-2022:
# identify telemetry stations in water district 6
discharge_ts = cdsspy.get_telemetry_ts(
abbrev = "ANDDITCO",
parameter = telemetry_params.parameter[6],
start_date = "2015-01-01",
end_date = "2022-01-01",
timescale = "day"
)
Retrieve groundwater data
The get_gw_() set of functions lets users make get requests to the various CDSS API groundwater endpoints shown in the table below:
- | Function | Endpoint |
---|---|---|
1 | get_gw_wl_wellmeasures() | api/v2/groundwater/waterlevels/wellmeasurements |
2 | get_gw_wl_wells() | api/v2/groundwater/waterlevels/wells |
3 | get_gw_gplogs_wells() | api/v2/groundwater/geophysicallogs/wells |
4 | get_gw_gplogs_geologpicks() | api/v2/groundwater/geophysicallogs/geoplogpicks |
Here we will retrieve groundwater well measurement data for Well ID 1274 between 1990-2022.
# Request wellmeasurements endpoint (api/v2/groundwater/waterlevels/wellmeasurements)
well_measure = cdsspy.get_gw_wl_wellmeasures(
wellid = "1274",
start_date = "1990-01-01",
end_date = "2022-01-01"
)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.