Northern-Thailand-Ping-River-Monitor/docs/references/NOTABLE_DOCUMENTS.md

Notable Documents and References

This document contains important references and external resources related to the Thailand Water Level Monitoring System.

🌊 Official Thai Government Water Resources

Royal Irrigation Department (RID) Resources

1. Water Level Monitoring Diagram

• URL: https://water.rid.go.th/hyd/Diagram/graphic_ping.pdf
• Description: Official diagram showing the water level monitoring network structure
• Content: Technical diagrams and network topology for Thailand's water monitoring system
• Language: Thai
• Format: PDF
• Usage: Understanding the official monitoring infrastructure and station relationships

2. Hourly Water Level Data Portal

• URL: https://hyd-app-db.rid.go.th/hydro1h.html
• Description: Real-time hourly water level data web interface
• Content: Live data from all 16 monitoring stations across Thailand
• Language: Thai
• Format: Web Application
• Usage: Primary data source for the monitoring system
• API Endpoint: Used by our scraper to fetch real-time data
• Update Frequency: Hourly updates
• Data Points: ~240-384 measurements per hour across all stations

3. Individual Station Data - P.76 Example

• URL: https://www.hydro-1.net/Data/STATION/P.76.html
• Description: Detailed individual station data page for station P.76
• Content: Historical data, station details, and specific measurements
• Language: Thai/English
• Format: Web Page
• Usage: Reference for individual station characteristics and historical data patterns
• Station: P.76 - บ้านแม่อีไฮ (Banb Mae I Hai)

ThaiWater / HII (Hydro-Informatics Institute) Resources

4. ThaiWater Portal

• URL: https://twa.thaiwater.net
• Description: National water situation portal (rainfall, water level, dams, warnings)
• Language: Thai/English
• Usage: Backed by open and auth-gated APIs — full endpoint catalog in DATA_SOURCES.md

5. ThaiWater Data Standard

• URL: https://standard.thaiwater.net
• Description: Official water-data standard for exchange and warning — canonical station/basin/province code registries, data formats, warning-level definitions
• Language: Thai
• Usage: Reference for station metadata and warning-level semantics

📊 Data Sources and APIs

Primary Data Source

• API Endpoint: https://hyd-app-db.rid.go.th/webservice/getGroupHourlyWaterLevelReportAllHL.ashx
• Method: POST
• Data Format: JSON
• Update Schedule: Hourly (top of each hour)
• Coverage: All 16 monitoring stations
• Metrics: Water level (m), Discharge (cms), Discharge percentage (%)

Station Coverage

The system monitors 16 stations across Thailand:

• P.1 - สะพานนวรัฐ (Nawarat Bridge)
• P.5 - สะพานท่านาง (Tha Nang Bridge)
• P.20 - บ้านเชียงดาว (Ban Chiang Dao)
• P.21 - บ้านริมใต้ (Ban Rim Tai)
• P.4A - บ้านแม่แตง (Ban Mae Taeng)
• P.67 - บ้านแม่แต (Ban Tae)
• P.75 - บ้านช่อแล (Ban Chai Lat)
• P.76 - บ้านแม่อีไฮ (Banb Mae I Hai)
• P.77 - บ้านสบแม่สะป๊วด (Baan Sop Mae Sapuord)
• P.81 - บ้านโป่ง (Ban Pong)
• P.82 - บ้านสบวิน (Ban Sob win)
• P.84 - บ้านพันตน (Ban Panton)
• P.85 - บ้านหล่ายแก้ว (Baan Lai Kaew)
• P.87 - บ้านป่าซาง (Ban Pa Sang)
• P.92 - บ้านเมืองกึ๊ด (Ban Muang Aut)
• P.103 - สะพานวงแหวนรอบ 3 (Ring Bridge 3)

🔗 Related Resources

Technical Documentation

• Thai Water Resources: https://water.rid.go.th/
• Hydro Information Network: https://www.hydro-1.net/
• Royal Irrigation Department: https://www.rid.go.th/

Data Standards

• Time Format: Thai Buddhist calendar (BE) + 24-hour format
• Coordinate System: WGS84 decimal degrees
• Water Level Units: Meters (m)
• Discharge Units: Cubic meters per second (cms)
• Update Frequency: Hourly at :00 minutes

API Parameters

{
    'DW[UtokID]': '1',
    'DW[BasinID]': '6',
    'DW[TimeCurrent]': 'DD/MM/YYYY', // Thai Buddhist calendar
    '_search': 'false',
    'nd': timestamp_milliseconds,
    'rows': '100',
    'page': '1',
    'sidx': 'indexhourly',
    'sord': 'asc'
}

📋 Data Structure Reference

JSON Response Format

{
    "rows": [
        {
            "hourlytime": "1.00",  // Hour (1-24, where 24 = midnight next day)
            "wlvalues1": "2.45",   // Water level for station 1 (meters)
            "qvalues1": "125.3",   // Discharge for station 1 (cms)
            "QPercent1": "45.2",   // Discharge percentage for station 1
            "wlvalues2": "1.89",   // Station 2 data...
            // ... continues for all 16 stations
        }
    ]
}

Station ID Mapping

• Station 1 → P.20 (Ban Chiang Dao)
• Station 2 → P.75 (Ban Chai Lat)
• Station 3 → P.92 (Ban Muang Aut)
• Station 4 → P.4A (Ban Mae Taeng)
• Station 5 → P.67 (Ban Tae)
• Station 6 → P.21 (Ban Rim Tai)
• Station 7 → P.103 (Ring Bridge 3)
• Station 8 → P.1 (Nawarat Bridge)
• Station 9 → P.82 (Ban Sob win)
• Station 10 → P.84 (Ban Panton)
• Station 11 → P.81 (Ban Pong)
• Station 12 → P.5 (Tha Nang Bridge)
• Station 13 → P.77 (Baan Sop Mae Sapuord)
• Station 14 → P.87 (Ban Pa Sang)
• Station 15 → P.76 (Banb Mae I Hai)
• Station 16 → P.85 (Baan Lai Kaew)

🌐 Geolocation Reference

Sample Coordinates (P.1 - Nawarat Bridge)

• Latitude: 15.6944°N
• Longitude: 100.2028°E
• Geohash: w5q6uuhvfcfp25
• Location: Nakhon Sawan Province, Thailand

Coordinate System

• Datum: WGS84
• Format: Decimal degrees
• Precision: 4 decimal places (~11m accuracy)
• Usage: Grafana geomap visualization

📝 Usage Notes

Data Collection

• Frequency: Every 15 minutes (full check at :00, quick checks at :15, :30, :45)
• Retention: 2+ years of historical data
• Gap Filling: Automatic detection and filling of missing data
• Data Updates: Checks for changed values in recent data

Time Handling

• Thai Time: UTC+7 (Asia/Bangkok)
• Buddhist Calendar: Thai year = Gregorian year + 543
• Hour 24: Represents midnight (00:00) of the next day
• API Format: DD/MM/YYYY (Buddhist calendar)

Data Quality

• Validation: Automatic data validation and error detection
• Retry Logic: 15-minute retry intervals when data is unavailable
• Error Handling: Comprehensive error logging and recovery
• Monitoring: Health checks and alert conditions

🔍 Research and Development

Future Enhancements

• Additional Stations: Potential expansion to more monitoring points
• Real-time Alerts: Threshold-based notification system
• Predictive Analytics: Water level forecasting capabilities
• Mobile Integration: Field data collection and verification

Technical Improvements

• API Optimization: Enhanced data fetching efficiency
• Database Performance: Query optimization and indexing
• Visualization: Advanced Grafana dashboard features
• Integration: Connection with other water management systems

This document serves as a comprehensive reference for understanding the data sources, technical specifications, and official resources that support the Thailand Water Level Monitoring System.