ieasyhydro-sdk

name

ieasyhydro-sdk

description

Expert guide for the ieasyhydro-python-sdk library for connecting to iEasyHydro High Frequency (HF) database. Use when: (1) Making API requests to iEasyHydro HF, (2) Retrieving discharge/meteorological data, (3) Debugging 422 or other API errors, (4) Formatting filters for get_data_values_for_site(), (5) Working with code in preprocessing_runoff that fetches from iEasyHydro HF, (6) Understanding response structure from the SDK. Triggers: ieasyhydro, iEasyHydro, SDK, HF database, WDDA, WDD, discharge data retrieval, site_codes filter.

iEasyHydro Python SDK Guide

SDK repository: https://github.com/hydrosolutions/ieasyhydro-python-sdk

Installation

pip install git+https://github.com/hydrosolutions/ieasyhydro-python-sdk

Configuration & Initialization

Environment variables:

IEASYHYDROHF_HOST=https://hf.ieasyhydro.org/api/v1/
IEASYHYDROHF_USERNAME=username
IEASYHYDROHF_PASSWORD=password

Initialization options:

from ieasyhydro_sdk.sdk import IEasyHydroHFSDK

# Option 1: From environment variables
sdk = IEasyHydroHFSDK()

# Option 2: Explicit configuration
sdk = IEasyHydroHFSDK(
    host='https://hf.ieasyhydro.org/api/v1/',
    username='username',
    password='password',
)

Key Methods

Method	Returns	Description
get_discharge_sites()	List[dict]	Discharge stations (manual measurement sites)
get_virtual_sites()	List[dict]	Virtual/calculated stations
get_meteo_sites()	List[dict]	Meteorological stations
get_data_values_for_site(filters)	dict	Time-series data matching filters
get_norm_for_site(site_code, norm_type, norm_period, automatic)	List[float]	Historical norm values

---

Fetching Sites

Discharge Sites

discharge_sites = sdk.get_discharge_sites()

Virtual Sites (calculated from associations)

virtual_sites = sdk.get_virtual_sites()

Meteorological Sites

meteo_sites = sdk.get_meteo_sites()

Site Response Structure

{
    'id': 96,                           # Unique internal ID
    'site_code': '15054',               # Station code (use this for queries)
    'official_name': 'Ак-Сай - с.Көк-Сай',
    'national_name': '',
    'site_type': 'manual',              # 'manual' or 'automatic'
    'latitude': 42.8746,
    'longitude': 74.5698,
    'elevation': 0.0,
    'country': 'Кыргызстан',
    'basin': {
        'official_name': 'Иссык-Куль',
        'national_name': ''
    },
    'region': {
        'official_name': 'ИССЫК-КУЛЬСКАЯ ОБЛАСТЬ',
        'national_name': ''
    },
    'dangerous_discharge': 100.0,
    'historical_discharge_maximum': None,
    'historical_discharge_minimum': None,
    'bulletin_order': 0,
    'enabled_forecasts': {
        'daily_forecast': False,
        'decadal_forecast': False,
        'monthly_forecast': False,
        'pentad_forecast': False,
        : 
    },
    
    
    : [
        {
            : ,
            : ,
            : ,
            : ,
            : 
        }
    ]
}

Note: Meteo sites have enabled_forecasts: None.

---

Fetching Data Values

Basic Usage

filters = {
    "site_codes": ["15013", "16159"],           # Station codes (strings)
    "variable_names": ["WDDA"],                  # Required: at least one metric
    "local_date_time__gte": "2024-01-01T00:00:00Z",  # Required: at least one timestamp
    "local_date_time__lte": "2024-12-31T23:59:59Z",
}

response = sdk.get_data_values_for_site(filters=filters)

All Filter Parameters

Parameter	Type	Required	Description
site_codes	List[str]	No*	Station codes like ["15013", "16159"]
site_ids	List[int]	No*	Station IDs (internal database IDs)
variable_names	List[str]	Yes	Metric codes: WDDA, WDD, WLD, etc.
local_date_time__gte	str	Yes†	Local timestamp >= (ISO format)
local_date_time__gt	str	No	Local timestamp >
local_date_time__lte	str	No	Local timestamp <=
local_date_time__lt	str	No	Local timestamp <
local_date_time	str	No	Exact local timestamp match
utc_date_time__gte	str	No	UTC timestamp >=
utc_date_time__gt	str	No	UTC timestamp >
utc_date_time__lte	str	No	UTC timestamp <=
utc_date_time__lt	str	No	UTC timestamp <
utc_date_time	str	No	Exact UTC timestamp match
page	int	No	Page number for pagination
page_size	int	No	Items per page (max 1000, default 10)

*Either site_codes or site_ids can be used, but site_codes is recommended. †At least one timestamp filter is required.

CRITICAL: Timestamp Handling

local_date_time should NOT include local timezone - treat it as UTC:

import datetime

# To get 8AM local metrics:
local_date_time = datetime.datetime(2025, 9, 25, 8, 0, tzinfo=datetime.timezone.utc).isoformat()
# Result: "2025-09-25T08:00:00+00:00"

# To get 8PM local metrics:
local_date_time = datetime.datetime(2025, 9, 25, 20, 0, tzinfo=datetime.timezone.utc).isoformat()

Response Structure

{
    "count": 42,                    # Total number of results across all pages
    "next": "https://...?page=2",   # URL for next page (None if last page)
    "previous": None,               # URL for previous page
    "results": [
        {
            "station_id": 123,
            "station_uuid": "abc-123-def-456",
            "station_code": "16159",
            "station_name": "Station Name",
            "station_type": "hydro",
            "data": [
                {
                    "variable_code": "WDDA",
                    "unit": "m3/s",
                    "values": [
                        {
                            "value": 156.0,
                            "value_type": "M",
                            "timestamp_local": "2024-03-01T08:00:00",
                            "timestamp_utc": "2024-03-01T02:00:00Z",
                            "value_code": None
                        }
                    ]
                }
            ]
        }
    ]
}

Response notes:

• Non-existent station codes are silently omitted from results
• Stations with no data for requested variables return empty values: []

---

Variable/Metric Codes

Hydrological Measurements

Code	Description	Notes
WLD	Water level daily	8AM or 8PM values from KN-15 telegram
WLDA	Water level daily average	Calculated from 8AM and 8PM values
WLDC	Water level decadal	From KN-15 subgroup 966
WLDCA	Water level decade average	Decadal average for a period
WDD	Water discharge daily	Morning reading, may be estimated from rating curve
WDDA	Water discharge daily average	From daily avg water level + rating curve
WDFA	Water discharge fiveday average	Pentadal average
WDDCA	Water discharge decade average	Decadal average
WTO	Water temperature observation	Daily from KN-15 telegram section 4
ATO	Air temperature observation	Daily from KN-15 telegram section 4
IPO	Ice phenomena observation	Complex: intensity + value code
PD	Precipitation daily	Complex: value + duration code
WTDA	Water temperature daily average
ATDA	Air temperature daily average
RCSA	River cross section area	From KN-15 subgroup 966

Meteorological Measurements

Code	Description	Notes
ATDCA	Air temperature decade average	Manual entry or KN-15 subgroup 988
PDCA	Precipitation decade average	Manual entry or KN-15 subgroup 988
ATMA	Air temperature monthly average	Manual entry or KN-15 subgroup 988
PMA	Precipitation monthly average	Manual entry or KN-15 subgroup 988

Value Type Codes

Code	Description
M	Manual measurement
A	Automatic measurement
E	Estimated value
I	Imported value
U	Unknown source
O	Override (manually entered by hydrologist)

---

Pagination

Page Size Limit

The API supports page_size up to 1000 (updated January 2026).

• Default page size is 10
• Using page_size=1000 significantly improves performance (reduced maintenance run from 800s to 364s)
• You may still need pagination for very large result sets

Pagination Pattern

def fetch_all_with_pagination(sdk, filters):
    """Fetch all results with pagination."""
    all_results = []
    page = 1

    while True:
        paginated_filters = {**filters, "page": page, "page_size": 1000}
        response = sdk.get_data_values_for_site(filters=paginated_filters)

        # Check for API error
        if isinstance(response, dict) and 'status_code' in response:
            print(f"Error: {response}")
            break

        results = response.get('results', [])
        all_results.extend(results)

        # Check if there are more pages
        if not response.get('next'):
            break
        page += 1

    return all_results

Optimized Parallel Pagination

For better performance, fetch pages in parallel after getting the count from page 1:

from concurrent.futures import ThreadPoolExecutor, as_completed

def fetch_all_parallel(sdk, filters, max_workers=10):
    """Fetch all results using parallel page requests."""
    PAGE_SIZE = 1000

    # Step 1: Get first page to learn total count
    first_response = sdk.get_data_values_for_site(
        filters={**filters, "page": 1, "page_size": PAGE_SIZE}
    )

    if isinstance(first_response, dict) and 'status_code' in first_response:
        return []  # Error

    total_count = first_response.get('count', 0)
    all_results = first_response.get('results', [])

    total_pages = (total_count + PAGE_SIZE - 1) // PAGE_SIZE
    if total_pages <= 1:
        return all_results

    # Step 2: Fetch remaining pages in parallel
    def fetch_page(page_num):
        resp = sdk.get_data_values_for_site(
            filters={**filters, "page": page_num, "page_size": PAGE_SIZE}
        )
        if isinstance(resp, dict) and 'status_code' not in resp:
            return resp.get('results', [])
        return []

    with ThreadPoolExecutor(max_workers=max_workers)  executor:
        futures = [executor.submit(fetch_page, p)  p  (, total_pages + )]
         future  as_completed(futures):
            all_results.extend(future.result())

     all_results

---

Fetching Norms

Historical norm values for stations:

# Get decadal discharge norm (default)
norm = sdk.get_norm_for_site("11194", "discharge")

# Get monthly discharge norm
norm = sdk.get_norm_for_site("11194", "discharge", norm_period="m")

# Get pentad norms for automatic station
norm = sdk.get_norm_for_site("11194", "discharge", norm_period="p", automatic=True)

# Get monthly temperature norms
norm = sdk.get_norm_for_site("15194", "temperature", norm_period="m", automatic=False)

Norm Parameters

Parameter	Values	Description
norm_type	discharge, water_level, precipitation, temperature	Type of norm
norm_period	d (decadal, default), p (pentad), m (monthly)	Time period
automatic	True/False	Automatic vs manual station

Norm Response

Returns a list of float values:

• Decadal: 36 values (3 per month)
• Monthly: 12 values (1 per month)
• Pentadal: 72 values (6 per month)

[11.76, 11.69, 11.64, ...]  # 36 decadal values

Missing norms are None:

[2.50, None, 3.75, 0.23, None, None, None, 0.45, 0.50, None, None, None]

---

Error Handling

API Requirements

1. At least one timestamp filter must be present
2. At least one variable name must be specified
3. Variable names must be valid (see metric codes above)

Error Response Format

{
    'status_code': 422,
    'text': '{"detail": "Some data is invalid or missing", "code": "schema_error"}'
}

Common Errors

Error	Cause	Solution
422 "Some data is invalid"	Missing timestamp filter	Add local_date_time__gte or similar
422 "Some data is invalid"	Missing variable_names	Add variable_names: ["WDDA"]
422 "Invalid metric names"	Wrong variable code	Check metric codes table
422 with large requests	Too many sites + large date range	Use batching or individual requests

Robust Fetching Strategy

def fetch_robust(sdk, site_codes, base_filters, batch_size=10):
    """Try bulk, then batches, then individual requests."""

    # 1. Try bulk request
    bulk_filters = {**base_filters, "site_codes": site_codes}
    response = sdk.get_data_values_for_site(filters=bulk_filters)

    if isinstance(response, dict) and 'status_code' not in response:
        return fetch_all_with_pagination(sdk, bulk_filters)

    # 2. Try batches
    all_results = []
    for i in range(0, len(site_codes), batch_size):
        batch = site_codes[i:i + batch_size]
        batch_filters = {**base_filters, "site_codes": batch}
        results = fetch_all_with_pagination(sdk, batch_filters)
        all_results.extend(results)

    if all_results:
        return all_results

    # 3. Fall back to individual requests
    for code in site_codes:
        single_filters = {**base_filters, "site_codes": [code]}
        results = fetch_all_with_pagination(sdk, single_filters)
        all_results.extend(results)

    return all_results

---

Complete Working Example

from ieasyhydro_sdk.sdk import IEasyHydroHFSDK
from datetime import datetime, timezone, timedelta

sdk = IEasyHydroHFSDK()

# 1. Get all discharge sites
sites = sdk.get_discharge_sites()
site_codes = list(set(s['site_code'] for s in sites))  # Unique codes
print(f"Found {len(site_codes)} unique discharge sites")

# 2. Define date range
end_date = datetime.now(timezone.utc)
start_date = end_date - timedelta(days=30)

# 3. Build filters
filters = {
    "site_codes": site_codes,
    "variable_names": ["WDDA"],
    "local_date_time__gte": start_date.strftime('%Y-%m-%dT00:00:00Z'),
    "local_date_time__lte": end_date.strftime('%Y-%m-%dT23:59:59Z'),
}

# 4. Fetch with pagination
all_results = []
page = 1
while True:
    filters['page'] = page
    filters['page_size'] = 1000  # Max allowed

    response = sdk.get_data_values_for_site(filters=filters)

    if isinstance(response, dict) and 'status_code' in response:
        print(f"Error: {response}")
        break

    all_results.extend(response.get('results', []))

    if  response.get():
        
    page += 

()


 station  all_results:
    code = station[]
    name = station[]
     var  station.get(, []):
        values = var.get(, [])
         values:
            latest = (v[][:]  v  values)
            ()

---

Key Gotchas Summary

1. Page size max is 1000 - use this for better performance
2. Use site_codes (strings) not site_ids - both work but codes are more reliable
3. local_date_time acts as UTC - don't include local timezone offset
4. At least one timestamp filter required - or you get 422 error
5. At least one variable_name required - or you get 422 error
6. Non-existent stations are silently omitted - no error, just missing from results
7. Large bulk requests may fail - use batching for many sites + long date ranges
8. Associations are for calculation - they define how virtual station discharge is computed