Thailand

[thiagovmdon]

Summary

Related to issue #103
This PR adds support for Thailand via the official public ThaiWater API.

It introduces a new ThailandFetcher, cached station metadata, tests, example usage, and Sphinx documentation.

Data sources

Official/public sources used:

• https://www.thaiwater.net/
• https://standard.thaiwater.net/
• https://api-v3.thaiwater.net/api/v1/thaiwater30/public/waterlevel_load
• https://api-v3.thaiwater.net/api/v1/thaiwater30/public/waterlevel_graph

What is included

• new rivretrieve/thailand.py
• export in rivretrieve/__init__.py
• Thailand docs page
• cached metadata CSV for Thailand stations
• example fetcher script
• unit tests and fixture payloads

Supported variables

• constants.STAGE_DAILY_MEAN
• constants.STAGE_INSTANT
• constants.DISCHARGE_DAILY_MEAN
• constants.DISCHARGE_INSTANT

Implementation details

• Metadata is sourced from waterlevel_load
• Stage and discharge series are sourced from waterlevel_graph
• The narrower flow endpoint is not used in this first version
• Long requests are split internally into smaller windows because the upstream graph endpoint truncates oversized requests to about the most recent year
• The implementation documents the current source behavior that waterlevel_msl is populated while waterlevel_m is mostly null
• The fetcher currently interprets waterlevel_graph.data.graph_data[].value as stage relative to MSL based on observed live source behavior
• Discharge is available only for a subset of stations, and missing station-variable combinations return empty DataFrames

Validation

• added Thailand-specific tests for metadata, daily stage, instantaneous discharge, and long-range window splitting
• verified Sphinx docs build cleanly
• verified live multi-year retrieval works after internal request chunking

Notes

One important upstream behavior is that very large single requests can be truncated by the ThaiWater backend. This PR works around that internally by splitting long ranges into smaller windows before combining the results.