API สำหรับอ่านข้อมูลแหล่งน้ำขนาดใหญ่

การกำหนดรายละเอียดของ API สำหรับอ่านข้อมูลแหล่งน้ำขนาดใหญ่

API ID	URL	รายละเอียด
A003.1	/LargesizedWaterResources	อ่านข้อมูลแหล่งน้ำขนาดใหญ่ ตามเงื่อนไขที่ระบุ

คุณลักษณะ API สำหรับอ่านข้อมูลแหล่งน้ำขนาดใหญ่

API ID: A003.1
วัตถุประสงค์: อ่านข้อมูลแหล่งน้ำขนาดใหญ่
Status: Required (ตั้งแต่ API version 1.0 Draft 1)
Since: 1.0 Draft 1
Revision: 1.0 Draft 1

ข้อมูลทั่วไป ในการติดต่อ API สำหรับอ่านข้อมูลแหล่งน้ำขนาดใหญ่

ข้อมูล	รายละเอียด
URL	/LargesizedWaterResources
HTTP Method	GET

Query parameter ของ API สำหรับอ่านข้อมูลแหล่งน้ำขนาดใหญ่

ลำดับ	Parameter	Type	ความหมาย	หมายเหตุ
1	interval	string	ประเภทความถี่ของการตรวจวัด อ้างอิงค่าตามหัวข้อ การใช้ค่า interval ในการระบุความถี่ของข้อมูลด้านน้ำจากการตรวจวัด	required
2	latest	boolean	true – ดึงข้อมูลเฉพาะค่าของการตรวจวัดล่าสุด false – ดึงข้อมูลตาม startDateTime และ endDateTime	required
3	startDatetime	datetime	วัน-เวลาที่ตรวจวัด (เริ่มต้น) – Inclusive	required เมื่อค่าพารามิเตอร์ latest = false
4	endDatetime	datetime	วัน-เวลาที่ตรวจวัด (สิ้นสุด) – Inclusive	required เมื่อค่าพารามิเตอร์ latest = false
5	provinceCode	string	รหัสจังหวัด (2 หลัก) ดูหัวข้อการอ้างอิงจังหวัด	optional
6	amphoeCode	string	รหัสอำเภอ (4 หลัก) ดูหัวข้อการอ้างอิงอำเภอ	optional
7	tambonCode	string	รหัสตำบล (6 หลัก) ดูหัวข้อการอ้างอิงตำบล	optional
8	basinCode	string	รหัสลุ่มน้ำหลัก (2 หลัก) ดูหัวข้อการอ้างอิงลุ่มน้ำหลัก/ลุ่มน้ำสาขา	optional
9	subBasinCode	string	รหัสลุ่มน้ำสาขา (4 หลัก) ดูหัวข้อการอ้างอิงลุ่มน้ำหลัก/ลุ่มน้ำสาขา	optional
10	agencyCode	string	รหัสหน่วยงาน ดูหัวข้อรหัสหน่วยงาน	optional

หมายเหตุ

1) การดึงข้อมูลที่มีความถี่แตกต่างกัน ให้ทำการ call API แยกกัน
2) ข้อมูล parameter 5-10 ใช้ในการบ่งบอก filter ว่าต้องการดึงข้อมูลของแหล่งน้ำขนาดใหญ่ครอบคลุมพื้นที่ใดบ้าง

ตัวอย่าง HTTP Request Parameter ในการอ่านค่าแบบช่วงรายชั่วโมง

latest=false 
&amp;startDatetime=2022-05-02T23:00:00 
&amp;endDatetime=2022-05-02T23:59:59 
&amp;interval=C-60 
&amp;provinceCode=10

โครงสร้างของ Response body ข้อมูลแหล่งน้ำขนาดใหญ่

{ 
	"metadata": { 
		"version": string, 
		"dataProviderCode": string, 
		"dataProviderName": string, 
		"documentGenerateTime": datetime, 
		"waterDatatype": string, 
		"interval": string 
		 
	},  
	"timeSeriesObservation": [{ 
		"observationMetadata":  
				{ 
				"observeAgencyCode": string, 
				"observeAgencyName": string, 
				"originality": integer, 
				"editAgencyCode": string, 
				"editAgencyName": string 
				}, 
 		"resultTime": datetime, 
		"station":  
				{ 
				"stationCode": string, 
				"stationReference": url	 	
				}, 
		"waterResources":  
				{ 
				"waterResorcesCode": string, 
				"waterResourcesReference": url		 
				}, 
		"measurementResults": [ 
				{ 
				"instrumentPosition": 
					{  
					"position": string, 
					"number": integer 
					} 
				"measureTime": datetime, 
				"createTime": datetime, 
				"updateTime": datetime, 
				"variable": "Storage", 
				"value": decimal, 
				"uom": string, 
				"qualityFlag": string, 
				"comment": string, 
				"qualityControlLevel": string 
				}, 
				{ 
				"instrumentPosition": 
					{  
					"position": string, 
					"number": integer 
					} 
				"measureTime": datetime, 
				"createTime": datetime, 
				"updateTime": datetime, 
				"variable": "ActiveStorage", 
				"value": decimal, 
				"uom": string, 
				"qualityFlag": string, 
				"comment": string, 
				"qualityControlLevel": string 
				}, 
				{ 
				"instrumentPosition": 
					{  
					"position": string, 
					"number": integer 
					} 
				"measureTime": datetime, 
				"createTime": datetime, 
				"updateTime": datetime, 
				"variable": "Inflow", 
				"value": decimal, 
				"uom": string, 
				"qualityFlag": string, 
				"comment": string, 
				"qualityControlLevel": string 
				}, 
				{ 
				"instrumentPosition": 
					{  
					"position": string, 
					"number": integer 
					} 
				"measureTime": datetime, 
				"createTime": datetime, 
				"updateTime": datetime, 
				"variable": "Outflow, 
				"value": decimal, 
				"uom": string, 
				"qualityFlag": string, 
				"comment": string, 
				"qualityControlLevel": string 
				} 
 
			] 
		} 
	] 
}

หมายเหตุ

ในกรณีที่ ข้อมูลตามโครงสร้างมาตรฐานไม่ได้กำหนดเป็น Mandatory (ดูหัวข้อโครงสร้างข้อมูลตามลำดับเวลา (Time Series)) ถ้ามีข้อมูลสามารถส่งข้อมูลนั้นๆได้ตามโครงสร้าง แต่ในกรณีที่ไม่มีข้อมูล API จะไม่ส่งข้อมูลกลับออกมา

ตัวอย่าง HTTP Response Body ของข้อมูลแหล่งน้ำขนาดใหญ่รายชั่วโมง (60นาที)

 { 
	"metadata": { 
		"version": "1.0", 
		"dataProviderCode":"G50504", 
		"dataProviderName":"Electricity Generating Authority of Thailand ", 
		"documentGenerateTime":"2022-05-02T23:01:00", 
		"waterDatatype": "A003", 
		"interval": "C-60" 
		 
	},  
	"timeSeriesObservation": [{ 
		"observationMetadata":  
				{ 
				"observeAgencyCode": "G50504", 
				"observeAgencyName": "Electricity Generating Authority of     Thailand", 
				"originality": 1 
				} 
		"resultTime": "2022-05-02T23:01:00", 
		"waterResources":  
				{ 
				"waterResorcesCode": "G50504-435436", 
			"waterResourcesReference": "https://api.my.org/twsapi/v1.0/ LargesizedWaterResourcesInfo/G50504-435436"
				},
 
	 
		"measurementResults": [ 
				{ 
				"measureTime":"2022-05-02T23:00:00", 
				"createTime": "2022-05-02T23:01:00", 
				"updateTime": "2022-05-02T23:01:00", 
				"variable": "Storage", 
				"value": 3990, 
				"uom": "MCM", 
				"qualityFlag": "U", 
				"comment": "No Quality Control", 
				"qualityControlLevel": "1" 
				}, 
				{ 
				"measureTime":"2022-05-02T23:00:00", 
				"createTime": "2022-05-02T23:01:00", 
				"updateTime": "2022-05-02T23:01:00", 
				"variable": "ActiveStorage", 
				"value": 3000, 
				"uom": "MCM", 
				"qualityFlag": "U", 
				"comment": "No Quality Control", 
				"qualityControlLevel": "1" 
				}, 
				{ 
				"measureTime":"2022-05-02T23:00:00", 
				"createTime": "2022-05-02T23:01:00", 
				"updateTime": "2022-05-02T23:01:00", 
				"variable": "Inflow", 
				"value": 450, 
				"uom": "MCM", 
				"qualityFlag": "U", 
				"comment": "No Quality Control", 
				"qualityControlLevel": "1" 
				}, 
				{ 
				"measureTime":"2022-05-02T23:00:00", 
				"createTime": "2022-05-02T23:01:00", 
				"updateTime": "2022-05-02T23:01:00", 
				"variable": "Outflow", 
				"value": 10, 
				"uom": "MCM", 
				"qualityFlag": "U", 
				"comment": "No Quality Control", 
				"qualityControlLevel": "1" 
				} 
 
			] 
		} 
	] 
}

หมายเหตุ

ข้อมูลที่ใส่ในตัวอย่างเป็นข้อมูลจำลองเพื่อประกอบความเข้าใจในการทำงานของ API เท่านั้น อาจจะไม่ตรงกับการใช้งานจริง

รายละเอียดเพิ่มเติมเกี่ยวกับ API เพื่อการดึงข้อมูลผลการตรวจวัดด้านน้ำ

การใช้งาน property “interval” ให้เป็นไปตามความเหมาะสมของข้อมูลด้านน้ำนั้นๆ เช่น ข้อมูลปริมาณฝนรายวันสามารถมีได้ทั้งแบบย้อนหลัง 24 ชม. และแบบตามคาบเวลารายวัน (7.00 น. – 7.00 น.)
response ที่ตอบกลับจาก API server ควรมีจำนวนข้อมูลการตรวจวัดแต่ละประเภทเพียง 1 ค่าต่อ 1 slot ของคาบเวลาที่ร้องขอ เช่น หากร้องขอข้อมูลน้ำฝนโดยกำหนด interval เป็น 15 นาที ควรมีค่าการตรวจวัดอยู่ใน slot 15 นาทีเพียง 1 ค่าเท่านั้น ทั้งนี้ เพื่อให้ API client ไม่ต้องนำข้อมูลไปทำการสรุปเพื่อให้ได้ค่าข้อมูลเพียง 1 ค่าภายใน slot ในภายหลัง
ค่าของ “measureTime” ที่ระบุมาจาก API server กำหนดให้ใช้เป็นวัน-เวลาท้ายสุดของ slot เวลานั้นๆ เช่น ปริมาณน้ำฝนสะสม 15 นาทีของ measureTime ที่เวลา 9:00 น. คือ ปริมาณน้ำฝนสะสมในช่วงเวลา 8:45 น. จนถึง 9:00 น. เป็นต้น
ในกรณีที่ข้อมูลที่ได้จากตรวจวัดมี interval ที่ไม่สอดคล้องกับข้อมูลที่ให้บริการ เช่น มีการตรวจวัดค่าน้ำฝนทุก 10 นาที แต่ต้องการให้บริการข้อมูลน้ำฝนรายชั่วโมง ผู้ให้บริการสามารถทำ data interpolation ได้ตามความเหมาะสมเพื่อให้ได้ข้อมูลที่สอดคล้องกับ slot ของการให้บริการข้อมูล รวมถึงทำการกำหนดค่าของ measureTime ให้สอดคล้องกับ slot เวลาที่ได้บริการข้อมูล
การระบุค่าของ “startDateTime” และ “endDateTime” ที่เป็น filter ในการ query ข้อมูลการตรวจวัดในกรณีที่ต้องการค่าเฉพาะช่วง โดยปกติไม่ควรจะทำการกำหนดค่าเกิน 1 วันในแต่ละครั้ง เพราะอาจจะมีปริมาณข้อมูลจำนวนมากเกินไป ในการ query แต่ละครั้ง