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)

## 📊 **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**
```javascript
{
    '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**
```json
{
    "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.