Package: cdsspy
cdsspyÂ« CDSS Â»CDSS REST Web
ServicesThe goal ofcdsspyis 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!Seecdssr, for theRversion of this packagecdssr (R)cdssr documentationcdsspy (Python)cdsspy documentationInstallationInstall the latest version ofcdsspyfromPyPI:pip install cdsspyAvailable endpointsBelow is a table of all of the CDSS API endpointscdsspyprovides functions for.-FunctionDescriptionEndpoint1get_admin_calls()Returns list of active/historic administrative callsadministrativecalls/active2get_structures()Returns list of administrative structuresstructures3get_structures_divrec_ts()Returns list of diversion/release records based on WDIDstructures/divrec/divrec4get_structures_stage_ts()Returns list of stage/volume records based on WDIDstructures/divrec/stagevolume5get_climate_stations()Returns Climate Stationsclimatedata/climatestations6get_climate_ts()Returns Climate Station Time Series (day, month, year)climatedata/climatestationts7get_climate_frostdates()Returns Climate Station Frost Datesclimatedata/climatestationfrostdates8get_gw_gplogs_wells()Returns Groundwater GeophysicalLogsWell from filtersgroundwater/geophysicallogs/9get_gw_gplogs_geologpicks()Returns Groundwater Geophysical Log picks by well IDgroundwater/geophysicallogs/10get_gw_wl_wells()Returns WaterLevelsWell from filtersgroundwater/waterlevels/wells11get_gw_wl_wellmeasures()Returns  Groundwater Measurementsgroundwater/waterlevels/wellmeasurements12get_reference_tbl()Returns reference tables listreferencetables/13get_sw_stations()Returns Surface Water Station infosurfacewater/surfacewaterstations14get_sw_ts()Returns Surface Water Time Seriessurfacewater/surfacewaterts15get_telemetry_stations()Returns telemetry stations and their most recent parameter readingtelemetrystations/telemetrystation16get_telemetry_ts()Returns telemetry time series data (raw, hour, day)telemetrystations/telemetrytimeseries17get_water_rights_netamount()Returns current status of a water right based on all of its court decreed actionswaterrights/netamount18get_water_rights_trans()Returns court decreed actions that affect amount and use(s) that can be used by each water rightwaterrights/transaction19get_call_analysis_wdid()Performs a call analysis that returns a time series showing the percentage of each day that the specified WDID and priority was out of priority and the downstream call in priorityanalysisservices/callanalysisbywdid20get_source_route_framework()Returns the DWR source route framework reference table for the criteria specifiedanalysisservices/watersourcerouteframeworkIdentify query inputs using reference tablesTheget_reference_tbl()function will return tables that makes it easier to know what information should be supplied to the data retrieval functions incdsspy. For more information on the source reference tables clickhere.# available parameters for telemetry stationstelemetry_params=cdsspy.get_reference_tbl(table_name="telemetryparams")Parameter0AIRTEMP1BAR_P2BATTERY3COND4D15D26DISCHRG7DISCHRG18DISCHRG29DISCHRG310DISCHRG411ELEVLocate structurescdsspyprovides functions for locating structures/stations/wells/sites by providing a spatial extent, water district, division, county, designated basin, or management district to the functions in the table below. Site data can also be retrieved by providing the site specific abbreviations, GNIS IDs, USGS IDs, WDIDs, or Well IDs.-FunctionDescriptionEndpoint1get_structures()Returns list of administrative structuresstructures2get_climate_stations()Returns Climate Stationsclimatedata/climatestations3get_gw_gplogs_wells()Returns Groundwater GeophysicalLogsWell from filtersgroundwater/geophysicallogs/4get_gw_wl_wells()Returns WaterLevelsWell from filtersgroundwater/waterlevels/wells5get_sw_stations()Returns Surface Water Station infosurfacewater/surfacewaterstations6get_telemetry_stations()Returns telemetry stations and their most recent parameter readingtelemetrystations/telemetrystationExample: Locating telemetry stations by county:# identify telemetry stations in Boulder Countystations=cdsspy.get_telemetry_stations(county="Boulder")Example: Locating telemetry stations around a point# identify telemetry stations within a 15 mile radius of the center point of Boulder Countystations=cdsspy.get_telemetry_stations(aoi=[-105.358164,40.092608],radius=15)Example: Locating telemetry stations within a spatial extentA masking operation is performed when a location search is done using apolygon. This ensures that the function only returns points that arewithinthe given polygon.# identify telemetry stations 15 miles around the centroid of a polygonstations=cdsspy.get_telemetry_stations(aoi=geopandas.read_file("https://cdsspy-images.s3.us-west-1.amazonaws.com/boulder_county.gpkg")radius=15)This gif highlights the masking process that happens when theaoiargument is given apolygonRetrieve time series dataThe functions in the table below retrieve time series data from the various time series related CDSS API endpoints.-FunctionDescriptionEndpoint1get_structures_divrec_ts()Returns list of diversion/release records based on WDIDstructures/divrec/divrec2get_structures_stage_ts()Returns list of stage/volume records based on WDIDstructures/divrec/stagevolume3get_climate_ts()Returns Climate Station Time Series (day, month, year)climatedata/climatestationts4get_gw_wl_wellmeasures()Returns  Groundwater Measurementsgroundwater/waterlevels/wellmeasurements5get_sw_ts()Returns Surface Water Time Seriessurfacewater/surfacewaterts6get_telemetry_ts()Returns telemetry time series data (raw, hour, day)telemetrystations/telemetrytimeseriesExample: Daily discharge at a telemetry stationWe can then take a station abbreviations from theget_telemetry_stations()call, a parameter from theget_reference_tbl()call, and use this information as inputs into theget_telemetry_ts()function.The function below returns a dataframe of daily discharge for the "ANDDITCO" site between 2015-2022.# Daily discharge at "ANDDITCO" telemetry stationdischarge_ts=cdsspy.get_telemetry_ts(abbrev="ANDDITCO",# Site abbreviation from the outputs of get_telemetry_stations()parameter="DISCHRG",# Desired parameter, identified by the get_reference_tbl()start_date="2015-01-01",# Starting dateend_date="2022-01-01",# Ending datetimescale="day"# select daily timescale)Example: Retrieve Diversion records for multiple structuresSome of the CDSS API endpoints allow users to request data from multiple structures if you provide a list of IDs. If we want to get diversion data from multiple structure locations, we'll need to get a list of WDIDs. We can get a list WDIDs within a given area by:Executing a spatial search usingget_structures()Selecting the WDIDs of interest from the search resultsProviding the WDIDs as a vector toget_structures_divrec_ts()# 1. Executing a spatial searchstructures=cdsspy.get_structures(aoi=[-105.3578,40.09244],radius=5)# 2. Selecting the WDID's of interest from search results and putting WDIDs into a listditch_wdids=structures[(structures["ciuCode"]=="A")&(structures["structureType"]=="DITCH")]ditch_wdids=list(ditch_wdids['wdid'])# 3. Providing the WDID's as a list to get_structures_divrec_ts()diversion_rec=cdsspy.get_structures_divrec_ts(wdid=ditch_wdids,wc_identifier="diversion",timescale="month")Note:Data availability can vary between structures (i.e. Missing data, not all structures have every data type/temporal resolution available, etc.)Retrieve groundwater dataTheget_gw_()set of functions lets users retrieve data from the various groundwater related API endpoints shown in the table below:-FunctionEndpoint1get_gw_wl_wellmeasures()api/v2/groundwater/waterlevels/wellmeasurements2get_gw_wl_wells()api/v2/groundwater/waterlevels/wells3get_gw_gplogs_wells()api/v2/groundwater/geophysicallogs/wells4get_gw_gplogs_geologpicks()api/v2/groundwater/geophysicallogs/geoplogpicksHere we will retrieve groundwater well measurement data for Well ID 1274 between 2021-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")