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
station_info(station_triplet='')
Get station metadata from USDA AWDB REST API for one SNOTEL stations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
station_triplet
|
str
|
A string of a station triplet in the format 'stationId:stateCode:networkCode' Any portion of the triplet can contain the '*' wildcard character. Examples: '602:CO:SNTL' |
''
|
Returns:
| Type | Description |
|---|---|
list
|
A nested list that has info for request station. |