tsgettoolbox - Quick Guide

The 'tsgettoolbox' is a Python script and library to get time-series data from different web services. The tsgettoolbox will work with Python and 3.10+.

Starting with version 27.0.0+, this package supplies the core functionality for the tsgettoolbox command line tool and Python library. The real work is done by a group of plugins that have this package as a dependency. The plugins are available using pip or conda.

The current plugins are:

• tsgettoolbox_cdec + California Department of Water Resources (CDEC) time series data
• tsgettoolbox_coops + Center for Operational Oceanographic Products and Services (CO-OPS) time series data
• tsgettoolbox_daymet + Daily meteorology by the Oak Ridge National Laboratory (Daymet) gridded data
• tsgettoolbox_fawn + Florida Automated Weather Network (FAWN) time series data
• tsgettoolbox_hydstra + Kisters Hydstra Webservice time series data
• tsgettoolbox_ldas + Land Data Assimilation System (LDAS) gridded data
• tsgettoolbox_metdata + Daily data from METDATA based on PRISM gridded data
• tsgettoolbox_modis + MODIS derived gridded data
• tsgettoolbox_ncei + National Centers for Environmental Information (NCEI) time series data
• tsgettoolbox_ndbc + National Data Buoy Center (NDBC) time series data
• tsgettoolbox_nldas3 + North American Land Data Assimilation System (NLDAS) version 3 gridded data
• tsgettoolbox_nwis + USGS National Water Information System (NWIS) time series data (USGS will turn off NWIS in 2027, use functions in tsgettoolbox_wdfn instead)
• tsgettoolbox_rivergages + USACE river gages time series data
• tsgettoolbox_terraclimate + TerraClimate gridded data
• tsgettoolbox_twc + Texas Weather Connection (TWC) time series data
• tsgettoolbox_unavco + UNAVCO well time series data
• tsgettoolbox_wdfn + USGS Water Data for the Nation (WDFN) time series data

Documentation

Reference documentation is at tsgettoolbox_documentation.

Installation

At the command line:

$ pip install <tsgettoolbox plugin name>

OR

$ conda install -c conda-forge <tsgettoolbox plugin name>

Usage Summary - Command Line

Just run 'tsgettoolbox --help' to get a list of subcommands from currently install plugins. To get detailed help for a particular sub-command, for instance 'coops', type 'tsgettoolbox coops --help'.

plugin.function	Spatial Extent	Time Extent	Type	Time Interval	Description
tsgettoolbox_cdec.cdec	US/CA	varies	station	E,H,D,M	California Department of Water Resources
tsgettoolbox_coops.coops	global	varies	station	1T,6T,H, D,M	Center for Operational Oceanographic Products and Services
cpc DISCONTINUED	US	varies	region	W	Climate Prediction Center
tsgettoolbox_daymet.daymet	NAmerica	1980-	grid 1km	D,M	daily meteorology by the Oak Ridge National Laboratory
tsgettoolbox_fawn.fawn	US/FL	varies	station	15T,H,D, M	Florida Automated Weather
tsgettoolbox_hydstra.hydstra_ts	varies	varies	station	E,H,D,M	Kisters Hydstra Webservice - time series values
tsgettoolbox_hydstra. hydstra_catalog	varies	varies	station	-NA-	Kisters Hydstra Webservice - variable catalog
tsgettoolbox_hydstra. hydstra_stations	varies	varies	station	-NA-	Kisters Hydstra Webservice - station list
ldas DEPRECATED use ldas_* functions below instead	global	varies	grid	varies	Land Data Assimilation System
tsgettoolbox_ldas. ldas_gldas_noah	global	2000-	grid 0.25deg	3H	GLDAS NOAH hydrology model results
tsgettoolbox_ldas. ldas_gldas_noah_v2_0	global	1948- 2014	grid 0.25deg	3H	GLDAS NOAH hydrology model
tsgettoolbox_ldas. ldas_gldas_noah_v2_1	global	2000-	grid 0.25deg	3H	GLDAS NOAH hydrology model
tsgettoolbox_ldas.ldas_grace	NAmerica	2002-	grid 0.125deg	7D	Groundwater and soil moisture from GRACE
tsgettoolbox_ldas.ldas_merra	global	1980-	grid 0.5x 0.625deg	H	MERRA-2 Land surface
tsgettoolbox_ldas. ldas_nldas3_forcing	NAmerica	2001-	grid 0.01deg	HDM	NLDAS3 Weather Forcing A (surface)
tsgettoolbox_ldas. ldas_nldas_fora	NAmerica	1979-	grid 0.125deg	H	NLDAS Weather Forcing A (surface)
tsgettoolbox_ldas. ldas_nldas_noah	NAmerica	1979-	grid 0.125deg	H	NLDAS NOAH hydrology model
tsgettoolbox_ldas.ldas_nldas_vic	NAmerica	1979-	grid 0.125deg	H	NLDAS VIC hydrology model
tsgettoolbox_ldas.ldas_smerge	global	1997-	grid 0.125deg	D	SMERGE-Noah-CCI root zone soil
tsgettoolbox_metdata.metdata	NAmerica	1980-	grid 4km	D	Daily data from METDATA based on PRISM.
tsgettoolbox_modis.modis	global	2000-	grid 250m, 500m, 1000m	4D,8D,16 D,A	MODIS derived data
tsgettoolbox_ncei.ncei_ghcnd_ftp	global	varies	station	D	NCEI Global Historical Climatology Network - Daily (GHCND) from FTP server.
tsgettoolbox_ncei.ncei_ghcnd	global	varies	station	D	NCEI Global Historical Climatology Network - Daily (GHCND) from web services.
tsgettoolbox_ncei.ncei_gsod	global	varies	station	D	NCEI Global Summary of the Day (GSOD)
tsgettoolbox_ncei.ncei_gsom	global	varies	station	M	NCEI Global Summary of the Month (GSOM)
tsgettoolbox_ncei.ncei_gsoy	global	varies	station	A	NCEI Global Summary of Year
tsgettoolbox_ncei. ncei_normal_ann	global	varies	station	A	NCEI annual normals
tsgettoolbox_ncei. ncei_normal_dly	global	varies	station	D	NCEI daily normals
tsgettoolbox_ncei. ncei_normal_hly	global	varies	station	H	NCEI hourly normals
tsgettoolbox_ncei. ncei_normal_mly	global	varies	station	M	NCEI monthly normals
tsgettoolbox_ncei.ncei_precip_15	global	varies	station	15T	NCEI 15 minute precipitation
tsgettoolbox_ncei. ncei_precip_hly	global	varies	station	H	NCEI hourly precipitation
tsgettoolbox_ncei.ncei_annual	global	varies	station	A	NCEI annual data summaries
tsgettoolbox_ncei.ncei_ghcndms	global	varies	station	M	NCEI GHCND Monthly Summaries (GHCNDMS)
tsgettoolbox_ncei.ncei_ish	global	varies	station	H	NCEI Integrated Surface hourly
tsgettoolbox_ndbc.ndbc	US	varies	station	6T,10T, 15T,H,D	National Data Buoy Center
nwis DEPRECATED use wdfn_* functions from tsgetoolbox_wdfn instead.	US	varies	station	varies	USGS National Water
tsgettoolbox_nwis.nwis_iv DEPRECATED: use tsgettoolbox_wdfn. wdfn_continuous	US	varies	station	E	USGS NWIS Instantaneous Values
tsgettoolbox_nwis.nwis_dv DEPRECATED: use tsgettoolbox_wdfn.wdfn_daily	US	varies	station	D	USGS NWIS Daily Values
tsgettoolbox_nwis.nwis_site DEPRECATED: use tsgettoolbox_wdfn. wdfn_monitoring_locations	US	varies	station	-NA-	USGS NWIS Site Database
tsgettoolbox_nwis.nwis_gwlevels DEPRECATED: use tsgettoolbox_wdfn. wdfn_field_measurements	US	varies	station	varies	USGS NWIS Groundwater
tsgettoolbox_nwis. nwis_measurements DEPRECATED: use tsgettoolbox_wdfn. wdfn_field_measurements	US	varies	station	varies	USGS NWIS Measurements
tsgettoolbox_nwis.nwis_peak DEPRECATED: use tsgettoolbox_wdfn.wdfn_peaks	US	varies	station	varies	USGS NWIS Peak
tsgettoolbox_nwis.nwis_stat DEPRECATED: use tsgettoolbox_wdfn. wdfn_read_normal_observations or tsgettoolbox_wdfn. wdfn_read_interval_observations	US	varies	station	varies	USGS NWIS Statistic
tsgettoolbox_wqp.project	US	varies	station	varies	US EPA Water Quality
tsgettoolbox_wqp.station	US	varies	station	varies	US EPA Water Quality
tsgettoolbox_wqp.result	US	varies	station	varies	US EPA Water Quality
tsgettoolbox_wqp. result_detection_quantitation_li mit	US	varies	station	varies	US EPA Water Quality
tsgettoolbox_wqp.activity	US	varies	station	varies	US EPA Water Quality
tsgettoolbox_wqp.activity_metric	US	varies	station	varies	US EPA Water Quality
tsgettoolbox_wqp. biological_metric	US	varies	station	varies	US EPA Water Quality
tsgettoolbox_wqp. projec_monitoring_location_weigh ting	US	varies	station	varies	US EPA Water Quality
tsgettoolbox_rivergages. rivergages	US	varies	station	varies	USACE river gages
tsgettoolbox_terraclimate. terraclimate	global	varies	grid 1/24deg	M	Monthly data from TerraClimate
tsgettoolbox_terraclimate. terraclimate19812010	global	varies	grid 1/24deg	M	Monthly normals using TerraClimate monthly data from 1981 to 2010
tsgettoolbox_terraclimate. terraclimate19912020	global	varies	grid 1/24deg	M	Monthly normals using TerraClimate monthly data from 1991 to 2020
tsgettoolbox_twc.twc	US/OK	varies	station	D	Texas Weather Connection (TWC) data
tsgettoolbox_unavco.unavco	US	varies	station	varies	UNAVCO well data
tsgettoolbox_wdfn. wdfn_agency_codes	US	varies	station		USGS WDFN Agency codes as table
tsgettoolbox_wdfn. wdfn_altitude_datums	US	varies	station		USGS WDFN Altitude datums as table
tsgettoolbox_wdfn. wdfn_aquifer_codes	US	varies	station		USGS WDFN Aquifer codes as table
tsgettoolbox_wdfn. wdfn_aquifer_types	US	varies	station		USGS WDFN Aquifer types as table
tsgettoolbox_wdfn. wdfn_channel_measurements	US	varies	station	E	USGS WDFN Channel measurements as time- series
tsgettoolbox_wdfn.wdfn_citations	US	varies	station		USGS WDFN Citations as table
tsgettoolbox_wdfn. wdfn_combined_metadata	US	varies	station		USGS WDFN Combined metadata as table
tsgettoolbox_wdfn. wdfn_continuous	US	varies	station	E	USGS WDFN Continuous data as time-series
tsgettoolbox_wdfn. wdfn_coordinate_accuracy_codes	US	varies	station		USGS WDFN Coordinate accuracy codes as table
tsgettoolbox_wdfn. wdfn_coordinate_datum_codes	US	varies	station		USGS WDFN Coordinate datum codes as table
tsgettoolbox_wdfn. wdfn_coordinate_method_codes	US	varies	station		USGS WDFN Coordinate method codes as table
tsgettoolbox_wdfn.wdfn_counties	US	varies	station		USGS WDFN Counties as table
tsgettoolbox_wdfn.wdfn_countries	US	varies	station		USGS WDFN Countries as table
tsgettoolbox_wdfn.wdfn_daily	US	varies	station	D	USGS WDFN Daily data as time-series
tsgettoolbox_wdfn. wdfn_field_measurements	US	varies	station	E	USGS WDFN Field measurements as time- series
tsgettoolbox_wdfn. wdfn_field_measurements_metadata	US	varies	station		USGS WDFN Field measurements metadata as table
tsgettoolbox_wdfn. wdfn_hydrologic_unit_codes	US	varies	station		USGS WDFN Hydrologic unit codes as table
tsgettoolbox_wdfn. wdfn_latest_continuous	US	varies	station	E	USGS WDFN Latest continuous data as time- series
tsgettoolbox_wdfn. wdfn_latest_daily	US	varies	station	D	USGS WDFN Latest daily data as time-series
tsgettoolbox_wdfn. wdfn_latest_field_measurements	US	varies	station	E	USGS WDFN Latest field measurements as time- series
tsgettoolbox_wdfn. wdfn_medium_codes	US	varies	station		USGS WDFN Medium codes as table
tsgettoolbox_wdfn. wdfn_method_categories	US	varies	station		USGS WDFN Method categories as table
tsgettoolbox_wdfn. wdfn_method_citations	US	varies	station		USGS WDFN Method citations as table
tsgettoolbox_wdfn.wdfn_methods	US	varies	station		USGS WDFN Methods as table
tsgettoolbox_wdfn. wdfn_monitoring_locations	US	varies	station		USGS WDFN Monitoring locations as table
tsgettoolbox_wdfn. wdfn_national_aquifer_codes	US	varies	station		USGS WDFN National aquifer codes as table
tsgettoolbox_wdfn. wdfn_parameter_codes	US	varies	station		USGS WDFN Parameter codes as table
tsgettoolbox_wdfn.wdfn_peaks	US	varies	station	E	USGS WDFN Peaks as time- series
tsgettoolbox_wdfn. wdfn_reliability_codes	US	varies	station		USGS WDFN Reliability codes as table
tsgettoolbox_wdfn. wdfn_site_types	US	varies	station		USGS WDFN Site types as table
tsgettoolbox_wdfn.wdfn_states	US	varies	station		USGS WDFN States as table
tsgettoolbox_wdfn. wdfn_statistic_codes	US	varies	station		USGS WDFN Statistic codes as table
tsgettoolbox_wdfn. wdfn_time_series_metadata	US	varies	station		USGS WDFN Time series metadata as table
tsgettoolbox_wdfn. wdfn_time_series_methods	US	varies	station		USGS WDFN Time series methods as table
tsgettoolbox_wdfn. wdfn_time_series_revisions	US	varies	station	E	USGS WDFN Time series revisions as time-series
tsgettoolbox_wdfn. wdfn_time_zone_codes	US	varies	station		USGS WDFN Time zone codes as table
tsgettoolbox_wdfn. wdfn_read_normal_observations	US	varies	station	DM	USGS WDFN Statistical normal observations
tsgettoolbox_wdfn. wdfn_read_interval_observations	US	varies	station	MA	USGS WDFN Statistical interval obs as time- series

Time Interval Code	Description
E	Event
T	Minute
H	Hourly
D	Daily
M	Monthly
A	Annual

Usage Summary - Python Library

To use the tsgettoolbox in a project:

from tsgettoolbox import tsgettoolbox
df = tsgettoolbox.wdfn_daily(monitoring_location_number="02329500", time="2000-01-01/..")

Refer to the API Documentation at tsgettoolbox_api.

Usage Summary - Command Line

tsgettoolbox wdfn_daily --monitoring_location_number 02329500 --time 2000-01-01/..

Refer to the command line documentation at tsgettoolbox_cli.

Development

Development is managed on bitbucket or github. https://bitbucket.org/timcera/tsgettoolbox/overview. https://github.com/timcera/tsgettoolbox