Fetch

fetch_snotel(stations=None, elements=None, duration='DAILY', start_date='1991-01-01', end_date='2100-01-01', include_coords=False)

Fetch data from the USDA AWDB REST API for one or more SNOTEL stations. Automatically detects large requests exceeding the API's 500,000 data point limit and fetches data in chunks, then concatenates the results.

Parameters:

Name	Type	Description	Default
stations	list	A list of station triplets in the format 'stationId:stateCode:networkCode'. Any portion of the triplet can contain the '' wildcard character. Examples: ['602:CO:SNTL'], [':OR:SNTL', '*:WA:SNTL']	None
elements	list	A comma separated list of elements in the format elementCode:heightDepth:ordinal. Any part of the element string can contain the '' wildcard character. HeightDepth and ordinal are optional, defaulting to null and 1 respectively. Examples: ['PREC', 'WTEQ'], 'SMS:', 'PREC::2'	None
duration	str	The time duration of the data to retrieve, by default 'DAILY'. Options: - 'DAILY' - 'HOURLY' - 'SEMIMONTHLY' - 'MONTHLY' - 'CALENDAR_YEAR' - 'WATER_YEAR'	'DAILY'
start_date	str	Begin date in 'YYYY-MM-DD' format, by default '1991-01-01'.	'1991-01-01'
end_date	str	End date in 'YYYY-MM-DD' format, by default '2100-01-01'.	'2100-01-01'
include_coords	bool		False
If			required
on			required

Returns:

Type	Description
Dataset	An xarray Dataset with dimensions (time, station) containing the requested elements as data variables, with metadata attributes loaded from ELEMENTS.yaml.

Raises:

Type	Description
ValueError	If the API request fails or returns no data.
Notes
For large requests, data is automatically fetched in multiple chunks
and concatenated. Stations with no data for a given chunk will contain NaN values.

get_stations(station_triplets=['::SNTL'], elements=None, hucs=None, county_name='', station_name='', returnStationElements='false', returnType='pd')

Retrieve SNOTEL station metadata from the USDA AWDB REST API.

Parameters:

Name	Type	Description	Default
station_triplets	List	A comma separated list of station triplets in the format 'stationId:stateCode:networkCode', by default '::SNTL' (all SNOTEL stations). Any portion of the triplet can contain the '' wildcard character. Examples: '602:CO:SNTL', ':CO:SNTL'	['::SNTL']
elements	list	Filter stations by element code, by default '' (no filter), comma seperated list, can include wildcard *. Examples: ['PREC', 'WTEQ']	None
hucs	list of str	Filter stations by HUC watershed code, by default [] (no filter).	None
county_name	str	Filter stations by county name, by default '' (no filter). Example: 'Boulder'	''
station_name	str	Filter stations by station name, by default '' (no filter).	''
returnStationElements	str	Whether to return station elements, by default 'false'.	'false'
returnType	str	The type of object to return, by default 'pd'. Options: - 'pd' : pandas DataFrame - 'gpd' : geopandas GeoDataFrame with point geometry (EPSG:4326)	'pd'

Returns:

Type	Description
DataFrame or GeoDataFrame	Station metadata including name, triplet, elevation, latitude, and longitude. Returns a GeoDataFrame with point geometry if returnType='gpd'.

Raises:

Type	Description
ValueError	If the API request fails.

save_data(data, filename='snotel_data')

Saves data to NetCDF or CSV.

Parameters:

Name	Type	Description	Default
data	Dataset or GeoDataFrame or DataFrame	xr.Dataset saves to NetCDF (.nc). GeoDataFrame saves to GeoJSON (.geojson) preserving geometry. DataFrame saves to CSV (.csv).	required
filename	str	Output filename without extension. Default is "snotel_data".	'snotel_data'

Returns:

Type	Description
None

Raises:

Type	Description
TypeError	If data is not an xr.Dataset, pd.DataFrame, or gpd.GeoDataFrame.

Examples:

>>> ds = sp.fetch_snotel(...)
>>> sp.save_data(ds, filename="snotel_data")       # -> snotel_data.nc

>>> gdf = sp.get_stations(returnType="gpd")
>>> sp.save_data(gdf, filename="stations")         # -> stations.geojson

>>> df = sp.get_stations(returnType="pd")
>>> sp.save_data(df, filename="stations")          # -> stations.csv