awdb.client.AWDBClient

awdb.client.AWDBClient(timeout=60, config=None)

Async client for accessing data via the NRCS AWDB REST API.

The AWDB (Air-Water Database) API provides access to real-time and historical monitoring data from networks such as SCAN and SNOTEL.

Attributes

Name	Description
timeout	Get the timeout in seconds (for backward compatibility).

Methods

Name	Description
check_station_data_availability	Check data availability for a station by querying coarser time granularity.
connect	Test connection to AWDB service.
find_nearby_stations	Find stations near a given location.
get_forecasts	Get forecast data for one or more stations.
get_reference_data	Get reference data from AWDB.
get_station_data	Get time series data for a specific station and element with enhanced options.
get_stations	Get list of available stations with comprehensive filtering options.

check_station_data_availability

awdb.client.AWDBClient.check_station_data_availability(
    station_triplet,
    elements,
    start_date,
    end_date,
    duration='MONTHLY',
    ordinal=1,
)

Check data availability for a station by querying coarser time granularity.

This method helps determine if a station has any data for a given element by using monthly aggregation, which is more likely to return results than daily data for sparse or intermittent measurements.

Returns: Dictionary with availability information: - ‘has_data’: Boolean indicating if any data exists - ‘data_points’: Number of data points found - ‘date_range’: Date range checked - ‘sample_values’: List of up to 5 sample values with dates

Raises: AWDBQueryError: If station/element not found or invalid parameters AWDBConnectionError: If there are network or server issues

connect

awdb.client.AWDBClient.connect()

Test connection to AWDB service.

Returns: True if connection successful

Raises: AWDBConnectionError: If connection fails

find_nearby_stations

awdb.client.AWDBClient.find_nearby_stations(
    latitude,
    longitude,
    max_distance_km=50.0,
    network_codes=None,
    limit=10,
)

Find stations near a given location.

Note: This method fetches all stations and filters client-side for distance. For large-scale applications, consider using the get_stations method with geographic filtering if available in future API versions.

Args: latitude: Target latitude (-90 to 90) longitude: Target longitude (-180 to 180) max_distance_km: Maximum search distance in kilometers network_codes: Optional network codes to filter by before distance limit: Maximum number of nearest stations to return

Returns: List of (StationInfo, distance_km) tuples, sorted by ascending distance

Raises: ValueError: If latitude/longitude are outside valid ranges AWDBQueryError: If station retrieval fails

get_forecasts

awdb.client.AWDBClient.get_forecasts(
    station_triplets,
    element_codes=None,
    start_publication_date=None,
    end_publication_date=None,
    exceedence_probabilities=None,
    forecast_periods=None,
)

Get forecast data for one or more stations.

Args: station_triplets: List of station triplets (e.g., [‘302:OR:SNTL’]) element_codes: List of element codes (e.g., [‘RESC’, ‘SRVO’]) start_publication_date: Start date for publication period (YYYY-MM-DD) end_publication_date: End date for publication period (YYYY-MM-DD) exceedence_probabilities: List of exceedence probabilities (e.g., [10, 30, 50]) forecast_periods: List of forecast periods (e.g., [‘03-01’, ‘07-31’])

Returns: List of ForecastData objects

get_reference_data

awdb.client.AWDBClient.get_reference_data(reference_lists=None)

Get reference data from AWDB.

Retrieves lookup tables and reference information used by the AWDB system, including elements, networks, units, states, and other metadata.

Args: reference_lists: List of reference data types to retrieve. Available options: ‘dcos’, ‘durations’, ‘elements’, ‘forecastPeriods’, ‘functions’, ‘instruments’, ‘networks’, ‘physicalElements’, ‘states’, ‘units’. If None, returns all reference data.

Returns: ReferenceData object containing requested reference information

Raises: AWDBQueryError: If invalid reference list specified AWDBConnectionError: If there are network or server issues

get_station_data

awdb.client.AWDBClient.get_station_data(
    station_triplet,
    elements,
    start_date,
    end_date,
    duration='DAILY',
    ordinal=1,
    period_ref='END',
    central_tendency_type='NONE',
    return_flags=True,
    return_original_values=False,
    return_suspect_data=False,
    insert_or_update_begin_date=None,
)

Get time series data for a specific station and element with enhanced options.

This method provides access to all AWDB data retrieval parameters, including quality flags, central tendency calculations, and incremental data updates.

Args: station_triplet: Station identifier (e.g., ‘1234:UT:SNTL’) elements: Element code (e.g., ‘SMS’, ‘STO’, ‘PREC’) start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format duration: Data duration (‘DAILY’, ‘HOURLY’, ‘MONTHLY’, etc.) ordinal: Sensor ordinal (1, 2, 3, etc. for multiple sensors) period_ref: Timestamp reference (‘START’ or ‘END’ of period) central_tendency_type: Include averages/medians (‘NONE’, ‘ALL’, ‘MEDIAN’, ‘AVERAGE’) return_flags: Include quality control and assurance flags return_original_values: Include original values before processing return_suspect_data: Include data marked as suspect (normally filtered) insert_or_update_begin_date: For incremental updates (YYYY-MM-DD format)

Returns: List of TimeSeriesDataPoint objects with comprehensive data and quality information

Raises: AWDBQueryError: If station/element not found or invalid parameters AWDBConnectionError: If there are network or server issues

get_stations

awdb.client.AWDBClient.get_stations(
    network_codes=None,
    state_codes=None,
    station_triplets=None,
    station_names=None,
    dco_codes=None,
    county_names=None,
    elements=None,
    durations=None,
    hucs=None,
    return_forecast_point_metadata=False,
    return_reservoir_metadata=False,
    return_station_elements=False,
    active_only=True,
    limit=None,
)

Get list of available stations with comprehensive filtering options.

This method leverages full AWDB API filtering capabilities, including wildcard support for station triplets, names, counties, and HUCs. All filtering is performed server-side for optimal performance.

Args: network_codes: Filter by network codes (e.g., [‘SCAN’, ‘SNTL’]). Supports wildcards like [‘:OR:’]. state_codes: Filter by state codes (e.g., [‘OR’, ‘WA’]) station_triplets: Filter by triplets with wildcards (e.g., [’*:OR:SNTL’, ‘302::’]) station_names: Filter by names with wildcards (e.g., [‘Lake’, ’Alab*’]) dco_codes: Filter by DCO codes county_names: Filter by county names with wildcards (e.g., [‘County’, ’Wall’]) elements: Filter by elements (format: elementCode:heightDepth:ordinal, supports wildcards) durations: Filter by durations (HOURLY, DAILY, SEMIMONTHLY, MONTHLY, CALENDAR_YEAR, WATER_YEAR, SEASONAL) hucs: Filter by HUC codes with wildcards (e.g., [‘170601’, ’050101’]) return_forecast_point_metadata: Include forecast point metadata for applicable stations return_reservoir_metadata: Include reservoir metadata for applicable stations return_station_elements: Include detailed station elements active_only: Return only active stations (default: True)

Returns: List of StationInfo objects with enhanced metadata based on request parameters

Raises: AWDBQueryError: If the request parameters are invalid AWDBConnectionError: If there are network or server issues

Examples: # Get all SNOTEL stations in Oregon or Washington stations = client.get_stations(station_triplets=[‘:OR:SNTL’, ’:WA:SNTL’])

# Get stations with soil moisture sensors in California
stations = client.get_stations(elements=['SMS:*'], state_codes=['CA'])

# Get stations in specific HUC areas
stations = client.get_stations(hucs=['170601*'])