คู่มือการใช้งาน API

 เลือกตัวอย่างการใช้งาน API

• RESTful API
• ใช้ Json Web Token (JWT) ในการ Authentication
• ตอบสนองเป็น JSON (Javascript Object Notation)
• endpoint หลักของข้อมูลหน่วยงานบริการสุขภาพ https://hcode.moph.go.th/api/health_office/
• คลิกเพื่อตรวจสอบ รายการ endpoints, สิทธิ์การเข้าถึงข้อมูล และข้อจำกัด และ รายการ query parameters

---

การขอ Token

กรณียังไม่มีบัญชีผู้ใช้ สมัครบัญชีผู้ใช้ที่ https://hcode.moph.go.th/signup/
HTTP Request ใช้ POST method ส่ง key-value ใน body มี key 2 ตัวคือ "username" และ "password" ที่ท่านใช้สมัครบัญชี
ส่งไปที่ endpoint https://hcode.moph.go.th/api/token/
โดยตั้งค่า headers เป็น "Content-Type": "application/json"

{
	"username": "your_username",
	"password": "your_password"
}
				

จะได้ Response กลับมาเป็น Token 2 ตัว คือ refresh และ access

{
	"refresh": "eyJhbGciOiJIUzI1NiIsInR5cAI6IkpXVCE9.eyJ0b2tlbi90eXBlIjoicmVmcmVzaCIsImV4cCI6MTY5OTg0MTg5NywiaWF0IjoxNjk5MjM3MDk3LCJqdGkiOiIxMmI1nmUwODY0Yjc0YTJlYjM1N2VmZGYwNjlhOWRlZCIsInVzZXJfaWQiOjQ5fQ.GFuP7MuQuenmYAeblPmqmYGJlnDq2bf8Vlr5-CXqbAw",
	"access": "eyJhbGciOiTIUzI1NiIsInR5cCI6IkpVXCE9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjk5MjQwNjk3LCJpYXQiOjE2OTkyMzcwOTcsImp0aSI6IjYxMzllyMJkZTJlNjQ1YjA4OTI3NzM0ZGY4NTQ3YzEwIiwidXNlal9pZCI6NDl9.RsQHNIQ3-rkCPNkHiZngwa4V934E-EtzJK_mMlrArWs"
}
				

• "access" เป็น short life token มีอายุ 240 นาที ใช้ส่งไปกับ headers เพื่อเข้าถึงข้อมูล โดยตั้งค่า
  "Authentication": "Bearer access" (ให้แทน access หลัง Bearer ด้วย access-token ที่เราได้จากวิธีการข้างต้น)
• "refresh" เป็น long life token มีอายุ 7 วัน ใช้ในการขอ access-token ใหม่เมื่อ token เดิมหมดอายุ โดยส่ง JSON ที่มี refresh-token ตามตัวอย่างต่อไป
  และใช้ headers "Content-Type": "application/json"
  ส่งไปที่ endpoint https://hcode.moph.go.th/api/token/refresh/

ส่ง refresh-token ไปที่ https://hcode.moph.go.th/api/token/refresh/

{
	"refresh": "eyJhbGciOiJIUzI1NiIsInR5cAI6IkpXVCE9.eyJ0b2tlbi90eXBlIjoicmVmcmVzaCIsImV4cCI6MTY5OTg0MTg5NywiaWF0IjoxNjk5MjM3MDk3LCJqdGkiOiIxMmI1nmUwODY0Yjc0YTJlYjM1N2VmZGYwNjlhOWRlZCIsInVzZXJfaWQiOjQ5fQ.GFuP7MuQuenmYAeblPmqmYGJlnDq2bf8Vlr5-CXqbAw"
}
			

Response ที่ได้จะเป็น access-token ใหม่ที่รีเซ็ตอายุเป็น 240 นาที

{
	"access": "eyJhizCiOpObnzI1NiIsInR5cCI6IkpXVCJ9.eyT0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzA4NDkzMDAyLCJpYXQiOJE3MDgzMjM4MTcsImp0aSI6IjI2MDdiNzFiMTY1ZDQ3OyjiYTaXZGY2ZjgxNTIxNTE5IiwidXNlcl9pZCI6MywiaXNzIjoiaGNvZGUubW9yAc5nby50aCJ9.qAXx2AEvCr1R4L9UiukCLKi4fbemJ539glUeeHlvBMY"
}
			

การขอข้อมูลหน่วยงานบริการสุขภาพ

ใช้ GET ไปที่ endpoint https://hcode.moph.go.th/api/health_office/ โดยตั้งค่า headers ของ HTTP Request ดังนี้ (access-token หลัง Bearer ในตัวอย่างนี้ ให้แทนด้วย access-token จริงที่ได้จากข้างต้น)

{
	"Content-Type": "application/json",
	"Authorization": "Bearer access-token"
}
				

รูปแบบ JSON ที่ API ตอบสนอง

JSON ที่เซิร์ฟเวอร์ตอบสนองจะมีลักษณะเป็น Pagination หรือการแบ่งชุดข้อมูลย่อยต่อหน้า ปัจจุบันได้ตั้งค่าการตอบสนองไว้เป็นข้อมูลตั้งต้น 100 รายการ ต่อหน้า บัญชีทั่วไปสามารถปรับได้สูงสุดหน้าละ 1,000 รายการ และบัญชีผู้ใช้ประเภทหน่วยงานรัฐบาลจะเพิ่มได้สูงสุดหน้าละ 10,000 รายการ แต่ละหน้าจะมี key ทั้งหมด 4 ตัว ได้แก่ "count", "next", "previous" และ "results" ดังต่อไปนี้

{
	"count": 0,
	"next": null,
	"previous": null,
	"results": []
}
				

1. "count" แสดงจำนวนของผลลัพธ์ทั้งหมดที่กรองได้ กรณีที่ไม่ได้กรองด้วย query parameters เซิร์ฟเวอร์จะตอบสนองข้อมูลมาทั้งหมดโดยแบ่งเป็นข้อมูลหน้าละ 100 รายการ ซึ่งสามารถเปลี่ยนจำนวนข้อมูลที่ตอบสนองได้โดยใช้พารามิเตอร์ page_size
2. "next" แสดง URL ของข้อมูลที่ถูกกรองหน้าถัดไป กรณีที่ไม่มีข้อมูลหน้าถัดไปจะแสดงเป็น null
3. "previous" แสดง URL ของข้อมูลที่ถูกกรองก่อนหน้านี้ 1 หน้า กรณีที่ไม่มีข้อมูลก่อนหน้าจะแสดงเป็น null
4. "results" แสดงชุดข้อมูล JSON ซ้อนใน [] โดยจะแบ่งข้อมูลหน้าละ 10 รายการ ท่านสามารถใช้พารามิเตอร์ page_size ได้ 1 - 1,000 รายการหรือ 1 - 10,000 รายการสำหรับบัญชีประเภทหน่วยงานรัฐบาล ดังตัวอย่างต่อไปนี้

การเพิ่มจำนวนข้อมูลที่ตอบสนอง โดยใช้ page_size

ตัวอย่างการแสดงข้อมูลจังหวัดทั้ง 77 จังหวัด ที่ endpoint https://hcode.moph.go.th/api/province/ โดยกำหนด page_size=3 ให้ตอบสนองหน้าละ 3 รายการ https://hcode.moph.go.th/api/province/?page_size=3

{
	"count": 77,
	"next": "https://hcode.moph.go.th/api/province/?page=2&page_size=3",
	"previous": null,
	"results": [
		{
			"id": 1,
			"code": "10",
			"name": "กรุงเทพมหานคร",
			"en_name": "Bangkok",
			"province_type": "เขตปกครองพิเศษ",
			"country": "ไทย",
			"region": "ภาคกลาง",
			"health_zone": "เขตสุขภาพที่ 13",
			"utm_zone": "48N"
		},
		{
			"id": 2,
			"code": "11",
			"name": "สมุทรปราการ",
			"en_name": "Samut Prakan",
			"province_type": "จังหวัด",
			"country": "ไทย",
			"region": "ภาคกลาง",
			"health_zone": "เขตสุขภาพที่ 6",
			"utm_zone": "48N"
		},
		{
			"id": 3,
			"code": "12",
			"name": "นนทบุรี",
			"en_name": "Nonthaburi",
			"province_type": "จังหวัด",
			"country": "ไทย",
			"region": "ภาคกลาง",
			"health_zone": "เขตสุขภาพที่ 4",
			"utm_zone": "47N"
		}
	]
}
				

การเปลี่ยนเลขหน้าข้อมูลที่กรอง โดยใช้ page

เราสามารถกรองหน้าเพิ่มเติมได้ใช้พารามิเตอร์ page ตัวอย่างด้านล่างนี้เป็นการกรองข้อมูลเพิ่มเติมจากข้างต้นไปที่ หน้า 2 โดยเพิ่มพารามิเตอร์ page=2 ซึ่งเป็น URL เดียวกันกับ key ที่ชื่อ "next" ท่านอาจทดลองเปลี่ยนเป็นเลขหน้าอื่น ๆ แทนได้
https://hcode.moph.go.th/api/province/?page=2&page_size=3

{
	"count": 77,
	"next": "https://hcode.moph.go.th/api/province/?page=3&page_size=3",
	"previous": "https://hcode.moph.go.th/api/province/?page_size=3",
	"results": [
		{
			"id": 4,
			"code": "13",
			"name": "ปทุมธานี",
			"en_name": "Pathum Thani",
			"province_type": "จังหวัด",
			"country": "ไทย",
			"region": "ภาคกลาง",
			"health_zone": "เขตสุขภาพที่ 4",
			"utm_zone": "47N"
		},
		{
			"id": 5,
			"code": "14",
			"name": "พระนครศรีอยุธยา",
			"en_name": "Phra Nakhon Si Ayutthaya",
			"province_type": "จังหวัด",
			"country": "ไทย",
			"region": "ภาคกลาง",
			"health_zone": "เขตสุขภาพที่ 4",
			"utm_zone": "47N"
		},
		{
			"id": 6,
			"code": "15",
			"name": "อ่างทอง",
			"en_name": "Ang Thong",
			"province_type": "จังหวัด",
			"country": "ไทย",
			"region": "ภาคกลาง",
			"health_zone": "เขตสุขภาพที่ 4",
			"utm_zone": "48N"
		}
	]
}
				

ตัวอย่างข้างต้นนี้แสดงรายการจังหวัดทั้งหมดโดยแบ่งข้อมูลใน "results" เป็นหน้าละ 3 รายการ โดยซ้อนเป็น JSON ใน [] หากต้องการขอข้อมูลหน้าถัดไปให้ใช้ URL จาก "next" ซึ่งต่างกันเพียงมีพารามิเตอร์ page ในการแบ่งเลขหน้า เช่น กรณีที่ท่านแบ่ง 77 จังหวัดให้แสดงด้วยพารามิเตอร์ page_size=5 จำนวนหน้าทั้งหมดที่ท่านกรองจะมี 16 หน้า โดยหน้าสุดท้ายมี 2 รายการ -> (15 x 5) + 2 = 77 จังหวัด

การกรองข้อมูลโดยใช้ query parameter

ข้อมูลหน่วยงานบริการสุขภาพสามารถกรองได้โดยใช้ query parameter ข้อมูลประเภท boolean จะใช้ "1" หรือ "True" แสดงตรรกะ "จริง" และใช้ "0" หรือ "False" แสดงตรรกะ "เท็จ"
query parameter ที่ใช้งานได้กับหน่วยงานบริการสุขภาพ สามารถตรวจสอบได้ที่
https://hcode.moph.go.th/api_documentation/endpoint_and_queryparameter/
ตัวอย่างนี้จะใช้ GET โดยส่ง access-token ไปที่
endpoint https://hcode.moph.go.th/api/health_office/ พร้อมกรองด้วย query parameter "name" และ "code9"
-> https://hcode.moph.go.th/api/health_office/?name=มิตรไมตรีคลินิกเวชกรรม(สุขสวัสดิ์)&code9=004162000
จะได้ผลลัพธ์ออกมา 1 รายการใน key "results" ดังนี้
หมายเหตุ: ฟิลด์ "address" และ "display_address" อาจจะแสดงข้อมูลไม่ตรงกันเนื่องจากฐานข้อมูลเดิมก่อนวันที่ 1 กันยายน พ.ศ.2566 ไม่ได้แยกฟิลด์ เลขที่, หมู่, หมู่บ้าน, ซอย, ถนน, อาคาร, ห้อง, ชั้น และชั้นลอย ทำให้ระบบใหม่ต้องทำฟิลด์ "details" รองรับข้อมูลที่อยู่เดิมใน "address" ซึ่งมีรูปแบบไม่ตายตัว จึงไม่สามารถ Serialize ข้อมูลให้เหมือนกันได้
ให้ท่าน"อ้างอิงที่อยู่โดยใช้ address เท่านั้น"
หาก "details" ใน "address" ไม่เป็น null รูปแบบข้อมูลใน "display_address" จะเป็น details + moo + subdistrict + district + province + zipcode

update 27/02/2024 ฟิลด์ "display_address" ถูกนำออกเพื่อลด loop ฟังก์ชัน และทำให้เกิดความเข้าใจผิดกับฟิลด์ "address"

{
	"count": 1,
	"next": null,
	"previous": null,
	"results": [
		{
			"id": 5050,
			"name": "มิตรไมตรีคลินิกเวชกรรม(สุขสวัสดิ์)",
			"code9": "004162000",
			"code5": "41620",
			"private_code": "11101006162",
			"organization_type": "เอกชน",
			"health_office_type": "คลินิกเอกชน",
			"hospital_level": null,
			"organization": "เอกชน",
			"department": null,
			"active": true,
			"address": {
				"id": 5050,
				"number": null,
				"moo": "2",
				"village": null,
				"street": null,
				"alley": null,
				"building": null,
				"room": null,
				"floor": null,
				"is_double_space": false,
				"subdistrict": "ในคลองบางปลากด",
				"subdistrict_code": "110505",
				"district": "พระสมุทรเจดีย์",
				"district_code": "1105",
				"province": "สมุทรปราการ",
				"province_code": "11",
				"province_type": "จังหวัด",
				"region": "ภาคกลาง",
				"utm_zone": "48N",
				"zipcode": "10290",
				"details": "168/6-7   ถนนสุขสวัสดิ์"
			},
			"host_agency": null,
			"established_date": "2019-04-23",
			"closed_date": null,
			"bed": null,
			"hdc": true,
			"is_client_hospital": false,
			"send_hdc_with_agency": false,
			"client_health_office_type": null,
			"contact": [
				{
					"id": 9353,
					"contact_type": "โทรศัพท์",
					"employee_contact": null,
					"name": "xx-xxxxxxx"
				},
				{
					"id": 9354,
					"contact_type": "โทรศัพท์",
					"employee_contact": {
						"id": 4595,
						"name": "xxxxx xxxxx",
						"nickname": null,
						"jobtitle": null,
						"office": "มิตรไมตรีคลินิกเวชกรรม",
						"active": true
					},
					"name": "xxx-xxxxxxx"
				},
				{
					"id": 9355,
					"contact_type": "อีเมล",
					"employee_contact": {
						"id": 4595,
						"name": "xxxxx xxxxx",
						"nickname": null,
						"jobtitle": null,
						"office": "มิตรไมตรีคลินิกเวชกรรม",
						"active": true
					},
					"name": ""
				}
			],
			"notes": [
				{
					"id": 59,
					"note_category": "HDC",
					"name": "HDC",
					"details": "ขอส่งข้อมูลเอง"
				}
			]
		}
	]
}