คู่มือการใช้งาน Data.go.th API - CKAN

เอกสารเผยแพร่

คู่มือการใช้งาน Data.go.th API

คู่มือการใช้งาน Data.go.th API

  • การสมัครขอรับ API Key ในการเรียกใช้งาน API
  • CKAN Data API และตัวอย่าง Code
  • Open-D Data API และตัวอย่าง Code
  • CKAN Data Catalog API
  • Data Visualization

การสมัครขอรับ API Key ในการเรียกใช้งาน API

ตามนโยบายการใช้งาน API ของ Data.go.th ผู้ใช้จะต้องลงทะเบียนเพื่อขอใช้บริการ API ก่อน จึงจะได้รับ API Key ของตนเอง เพื่อใช้ในการเข้าถึง API ของชุดข้อมูลได้ ทั้งนี้นโยบายดังกล่าวกำหนดขึ้นเพื่อป้องกันการเรียกใช้ API อย่างไม่ถูกต้อง เช่น การ attack server หรือ การเรียกใช้ API ในปริมาณที่มากเกินไป ซึ่งจะมีผลต่อประสิทธิภาพโดยรวมของระบบ นอกจากนี้ผู้ดูแลระบบยังต้องการทราบ profile พื้นฐานของนักพัฒนา เพื่อให้สามารถนำมาใช้ในการปรับปรุงบริการให้ตรงกับความต้องการของผู้ใช้แต่ละกลุ่มมากยิ่งขึ้นในอนาคต

ขั้นตอนการลงทะเบียนขอใช้บริการ API มีดังนี้

  1. จากเมนูของเว็บไซต์ https://data.go.th คลิกที่ลิงก์ “สำหรับนักพัฒนา” หรือ สามารถเข้าตรงไปที่เว็บไซต์ https://opend.data.go.th
  2. คลิกที่ลิงก์ “สมัครเป็นผู้ใช้”
  3. กรอกข้อมูลส่วนตัว และตั้งชื่อผู้ใช้และรหัสผ่าน และคลิกที่ปุ่ม “ลงทะเบียน”
  4. ระบบจะส่ง email ยืนยันการสมัคร เมื่อผู้สมัครคลิกที่ลิงก์ ยืนยัน จากอีเมล์ดังกล่าว ก็จะสามารถ login เข้าสู่ระบบ login ได้

Data.go.th API Homepage

register api key

ขั้นตอนการยืนยันตัวตนเพื่อดูข้อมูล API Key มีดังนี้

  1. จากเมนูของเว็บไซต์ https://data.go.th คลิกที่ลิงก์ “สำหรับนักพัฒนา” หรือ สามารถเข้าตรงไปที่เว็บไซต์ https://opend.data.go.th
  2. คลิกที่ลิงก์ “เข้าใช้งาน”
  3. ระบุชื่อผู้ใช้หรืออีเมล์ และรหัสผ่าน และคลิกที่ปุ่ม “เข้าใช้งาน"
  4. ท่านจะเห็น API key ของท่าน ในส่วนของ "User Token" ดังรูป ซึ่ง User Token ดังกล่าว สามารถใช้ในการเข้าถึง data API ทั้งหมดบนเว็บ Data.go.th

view API key

เพื่อความปลอดภัยและการรักษาความลับของ API Key ของท่านไม่ให้ผู้อื่นนำไปใช้ จึงควรระบุ API Key ลงในส่วนของ HTTP Header โดยใช้ method แบบ GET หรือ POST ในตัวอย่างนี้จะใช้โปรแกรม Postman (https://www.getpostman.com/downloads/) ในการสาธิตการเข้าถึง API โดยการระบุ parameter ชื่อ api-key และระบุค่า API Key ของผู้ใช้แต่ละคนในส่วน value

Example API Request

example API result

 

CKAN Data API และตัวอย่าง Code

CKAN Data API เป็นการค้นคืนข้อมูลที่อยู่ในไฟล์ชุดข้อมูล ด้วยเงื่อนไขการสืบค้นต่างๆ โดย CKAN Data API จะสามารถใช้งานได้กับไฟล์ทรัพยากรชุดข้อมูลที่เป็นไฟล์ขนิด CSV, XLS, XLSX และข้อมูลต้องอยู่ในรูปแบบตารางเท่านั้น ทั้งนี้ไฟล์ทรัพยากรที่สามารถเรียกใช้ CKAN Data API ได้ระบบจะแสดงตาราง preview ข้อมุลควบคู่กันด้วย หากไฟล์ทรัพยากรใดที่ระบบไม่สามารถแสดงตาราง preview ได้ จะไม่สามารถเรียกใช้ CKAN Data API ได้

วิธีการเรียกใช้งาน CKAN Data API สำหรับชุดข้อมูลนั้น ทำได้โดยคลิกที่ปุ่ม “Data API” เหนือตาราง preview จากนั้นจะปรากฏหน้าต่างแสดงคำอธิบายการใช้งาน และตัวอย่างการเรียกใช้งาน เช่น

ค้นคืนข้อมูลทั้งหมดโดยจำกัดจำนวนผลลัพธ์ 5 รายการ:

https://opend.data.go.th/get-ckan/datastore_search?resource_id=<resource_id>&limit=5

ค้นคืนข้อมูลเฉพาะแถวที่ปรากฏคำค้นที่ระบุเท่านั้น

https://opend.data.go.th/get-ckan/datastore_search?q=<keyword>&resource_id=<resource_id>;

ckan api

ตัวอย่างการเรียกใช้ CKAN Data API โดยใช้โปรแกรม CURL และภาษา PHP

โปรแกรม CURL

curl -v -L -H 'api-key: <user token>' -X GET 'https://opend.data.go.th/get-ckan/datastore_search?resource_id=93f74e67-6f76-4b25-8f5d-b485083100b6&limit=5';

PHP

  1. <?php
  2.  
  3. $curl = curl_init();
  4.  
  5. curl_setopt_array($curl, array(
  6. CURLOPT_URL => "https://opend.data.go.th/get-ckan/datastore_search?resource_id=93f74e67-6f76-4b25-8f5d-b485083100b6&limit=5";,
  7. CURLOPT_RETURNTRANSFER => true,
  8. CURLOPT_ENCODING => "",
  9. CURLOPT_MAXREDIRS => 10,
  10. CURLOPT_TIMEOUT => 30,
  11. CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  12. CURLOPT_CUSTOMREQUEST => "GET",
  13. CURLOPT_HTTPHEADER => array(
  14. "api-key: <user token>"
  15. )
  16. ));
  17.  
  18. $response = curl_exec($curl);
  19. $err = curl_error($curl);
  20.  
  21. curl_close($curl);
  22.  
  23. if ($err) {
  24. echo "cURL Error #:" . $err;
  25. } else {
  26. echo $response;
  27. }
  28. ?>

Open-D Data API และตัวอย่าง code

เนื่องจาก CKAN Data API จะสามารถใช้ได้กับไฟล์ชุดข้อมูลที่อยู่ในรูปแบบตารางที่ถูกต้องเท่านั้น หากรูปแบบตารางในไฟล์มีความผิดพลาดเพียงเล็กน้อย จะไม่สามารถใช้ Data API ในการเข้าถึงชุดข้อมูลนั้นได้ อย่างไรก็ดีหากผู้ใช้พบว่ามีปุ่ม "Visualization" แต่ไม่มีปุ่ม Data API ก็สามารถใช้ Data API ผ่านโปรแกรม Open-D API ได้เช่นกัน

Open-D เป็นระบบที่พัฒนาขึ้นโดยศูนย์เทคโนโลยีอิเล็กทรอนิกส์และคอมพิวเตอร์แห่งชาติ(เนคเทค) เพื่อเสริมความสามารถของ CKAN ในเรื่องของ Data Preview Data API และ Data Visualization และ Data Cleasing โดยชุดข้อมูลที่มีรูปแบบตารางผิดพลาดเล็กน้อยจะถูกทำ Data Cleasing โดยระบบ Open-D ทำให้สามารถใช้งาน Data Preview Data API และ Data Visualization ผ่านระบบ Open-D ได้โดยคลิกที่ปุ่ม "Visualization" ดังรูป

Open-D Button

 

Open-D Data Explorer Screen

Open-D Data API เป็นการค้นคืนข้อมูลที่อยู่ในไฟล์ชุดข้อมูล ด้วยเงื่อนไขการสืบค้นต่างๆ เช่นเดียวกับ CKAN Data API และจะสามารถใช้งานได้กับไฟล์ทรัพยากรชุดข้อมูลที่เป็นไฟล์ขนิด CSV, XLS, XLSX ที่ข้อมูลอยู่ในรูปแบบตารางเท่านั้นเช่นเดียวกัน ทั้งนี้ Open-D Data API มีข้อแตกต่างจาก CKAN Data API ดังนี้

  1. Open-D Data API มีส่วนของการทำ data cleansing แบบพื้นฐาน จึงรองรับการนำเข้าข้อมูลในแบบตารางได้มากกว่า CKAN ทำให้ไฟล์ทรัพยากรชุดข้อมูลบางไฟล์ที่ไม่สามารถ preview หรือใช้งาน CKAN Data API ได้ สามารถเรียกใช้งานผ่าน Open-D Data API ได้
  2. Open-D Data API รองรับการสร้าง API request โดยวิธี Query By Example (QBE) โดยผู้ใช้มิจำเป็นต้องรู้จัก syntax ของ API request แต่สามารถใส่เงื่อนไขการสืบค้นที่ต้องการ และคลิกที่ “Get API” ดังรูป จะปรากฏ API request ที่สามารถนำไปใช้งานได้ทันที

 

 

การสร้าง URL สำหรับเรียกใช้งาน API ผ่านระบบ Open-D

รายละเอียดวิธีการใช้งานหน้าสืบค้นข้อมูลและการสร้าง URL สำหรับเรียกใช้งาน API ผ่านระบบ Open-D  มีขั้นตอนดังนี้

ส่วนประกอบของหน้าจอสืบค้นข้อมูล ประกอบด้วย 2 ส่วน ได้แก่ ส่วนของการค้นหาข้อมูลและการสร้าง URL สำหรับเรียกใช้งาน API

1. ส่วนของการค้นหาข้อมูล : ผู้ใช้สามารถค้นหาข้อมูลที่ต้องการได้ด้วยตนเอง โดยมีฟังก์ชันการค้นหาข้อมูล 2 รูปแบบ ได้แก่ 1) แบบระบุเงื่อนไข (field search) และ 2) แบบสรุปรายงาน (aggregation)

1.1. การค้นหาข้อมูลแบบระบุเงื่อนไข (field search): ผู้ใช้งานสามารถกำหนดเงื่อนไขที่ต้องการสืบค้นได้ โดยเลือกคอลัมน์ที่ต้องการค้นหา (Properties), เครื่องหมาย (Operators) และข้อมูลที่ต้องการค้นหา (Values)

กรณีที่ข้อมูลที่ต้องการค้นหามีชนิดข้อมูลตัวอักษร (string) สามารถกำหนดเครื่องหมายได้ 2 รูปแบบ คือ Contains และ S_EQUALS

  • Contains – ใช้กรณีที่ต้องการเปรียบเทียบข้อความเพียงบางส่วน เช่น ค้นหาข้อมูลวัฒนธรรมของจังหวัดที่มีคำว่า "เชียง" ระบบจะแสดงข้อมูลของจังหวัด "เชียงใหม่” และ "เชียงราย” เป็นต้น
  • S_EQUALS - ใช้กรณีที่ต้องการเปรียบเทียบข้อความแบบตรงกันหมด เช่น ค้นหาข้อมูลรูปภาพที่มีรหัสวัฒนธรรม "MOC-136739"

กรณีที่ต้องการค้นหามีชนิดข้อมูลตัวเลข (number) สามารถกำหนดเครื่องหมายได้ 5 รูปแบบ คือ =, <, <=,>, >=

1.2. การค้นหาข้อมูลแบบสรุปรายงาน (aggregation): ผู้ใช้งานสามารถค้นหาข้อมูลแบบสรุปรายงานได้ โดยเลือกฟังก์ชันการคำนวณ (Aggregation Function), การแบ่งกลุ่ม (Group by) และการเรียงลำดับของข้อมูล (Order by) ฟังก์ชันการคำนวณ (Aggregation Function) มี 5 ฟังก์ชัน ได้แก่ จำนวน (count), จำนวนไม่ซ้ำ (distinct), ผลรวม (sum), ค่าเฉลี่ย (average), ค่าสูงสุด (max), ค่าต่ำสุด (min)

2. ส่วนของการสร้าง URL เพื่อเรียกใช้งาน API : เป็นส่วนที่ระบบจะสร้าง URL เพื่อเรียกใช้งาน API แบบอัตโนมัติจากฟอร์มที่ผู้ใช้กำหนดเงื่อนไขในการค้นหาข้อมูล

ข้อมูลการใช้งาน API

Service Type: REST/JSON

Method: GET

ตัวอย่างการเรียกใช้งาน

เงื่อนไขสำหรับ field search: ค้นหารายชื่อนิติบุคคลที่มีที่อยู่ในจังหวัดเชียงใหม่

https://opend.data.go.th/opend-search/vir_1480_1579254770/query?dsname=vir_1480_1579254770&path=vir_1480_1579254770&property=col_8&operator=CONTAINS&valueLiteral=เชียงใหม่&loadAll=1&type=json&limit=100&offset=0

 

- เงื่อนไขสำหรับ aggregation : แสดงจำนวนนิติบุคคลที่มีทุนจดทะเบียนมากกว่า 10 ล้านบาท แบ่งกลุ่มตามวัตถุประสงค์การจัดตั้ง

https://opend.data.go.th/opend-search/vir_1480_1579254770/agg?dsname=vir_1480_1579254770&path=vir_1480_1579254770&aggf=count&agg_prop=col_2&groupby=col_7&property=col_5&operator=GT&valueLiteral=10000000&loadAll=1&type=json&limit=100&offset=0

Parameters ของ API

ชื่อ

ชื่อพารามิเตอร์

คำอธิบาย

1

dsname

รหัสชุดข้อมูล

2

path

ชื่อตารางของชุดข้อมูล

3

property

คอลัมน์ที่ต้องการค้นหา

4

operator

เครื่องหมาย ประกอบด้วย Contains, S_EQUALS, EQUALS, LT, LE, GT, GE

5

valueLiteral

ค่าที่ต้องการค้นหา

6

aggf

ฟังก์ชันการคำนวณ ประกอบด้วย count, distinct, sum, average, min, max

7

agg_prop

คอลัมน์ที่ต้องการคำนวณ

8

groupby

คอลัมน์ที่ใช้ในการแบ่งกลุ่มข้อมูล

9

orderby

รูปแบบการเรียงลำดับ มี 2แบบ คือ มากไปน้อย (desc) และ น้อยไปมาก (asc)

10

limit

จำกัดจำนวนแถวผลลัพธ์

11

offset

แถวที่เริ่มต้น

 

รูปแบบของผลลัพธ์ (Output)

ผลลัพธ์ที่ได้จากระบบ API จะอยู่ในรูปแบบของ JSON ดังแสดงในรูป มีองค์ประกอบดังนี้

  • numData: จำนวนผลลัพธ์
  • data: ข้อมูลผลลัพธ์ที่ตรงกับเงื่อนไขการค้นคืน
  • message:
    • Success,
  • status:
    • 200

ตัวอย่างการเรียกใช้ Open-D Data API โดยใช้โปรแกรม CURL และภาษา PHP

โปรแกรม CURL

curl -v -L -X GET -H "api-key: <user token>" "https://opend.data.go.th/opend-search/vir_3250_1584586227/query?dsname=vir_3250_1584586227&path=vir_3250_1584586227&loadAll=1&type=json&limit=100&offset=0;

 

PHP

  1. <?php
  2.  
  3. $curl = curl_init();
  4.  
  5. curl_setopt_array($curl, array(
  6. CURLOPT_URL => "https://opend.data.go.th/opend-search/vir_3250_1584586227/query?dsname=vir_3250_1584586227&path=vir_3250_1584586227&loadAll=1&type=json&limit=100&offset=0";,
  7. CURLOPT_RETURNTRANSFER => true,
  8. CURLOPT_ENCODING => "",
  9. CURLOPT_MAXREDIRS => 10,
  10. CURLOPT_TIMEOUT => 30,
  11. CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  12. CURLOPT_CUSTOMREQUEST => "GET",
  13. CURLOPT_HTTPHEADER => array(
  14. "api-key: <user token>"
  15. )
  16. ));
  17.  
  18. $response = curl_exec($curl);
  19. $err = curl_error($curl);
  20.  
  21. curl_close($curl);
  22.  
  23. if ($err) {
  24. echo "cURL Error #:" . $err;
  25. } else {
  26. echo $response;
  27. }
  28. ?>

CKAN Data Catalog API

รายละเอียดวิธีการใช้งาน CKAN Data Catalog API

CKAN Data Catalog API เป็น API สำหรับการเข้าถึงข้อมูลเมทาดาตาของชุดข้อมูลเปิดภาครัฐบนเว็บ Data.go.th โดยข้อมูลเมทาดาตาแบ่งเป็น 2 ระดับคือ

  1. ระดับชุดข้อมูล (package) – ชุดข้อมูล 1 ชุดข้อมูลสามารถประกอบด้วยไฟล์ทรัพยากรหลายไฟล์ได้ ดังตัวอย่างในรูป เช่น ชุดข้อมูล ข้อมูลการจดทะเบียนนิติบุคคล พ.ศ. 2529 ประกอบด้วย ไฟล์ทรัพยากร 3 ไฟล์ ได้แก่ 1) ข้อมูลการจดทะเบียนนิติบุคคล – กุมภาพันธ์-2559-XLS (.xls) 2) ข้อมูลการจดทะเบียนนิติบุคคล – มีนาคม-2559-CSV (.csv) 3) Metadata-ข้อมูลการจดทะเบียนนิติบุคคล-พฤษภาคม-2559 (.pdf) เป็นต้น
  2. ระดับไฟล์ทรัพยากร (resource) – ไฟล์ทรัพยากรของชุดข้อมูล คือไฟล์ที่ผู้ใช้สามารถดาวน์โหลดไปใช้งานได้ ในรูปตัวอย่าง แสดงเมทาดาตาของไฟล์ทรัพยากร ข้อมูลการจดทะเบียนนิติบุคคล – กุมภาพันธ์-2559-XLS เป็นต้น

API สำหรับเรียกดูข้อมูลของชุดข้อมูล เช่น

API สำหรับเรียกดูข้อมูลของไฟล์ทรัพยากรชุดข้อมูล เช่น

 

Data Visualization

ผู้ใช้สามารถทำ Data Visualization กับชุดข้อมูลที่มีปุ่ม "Visualization" ได้ โดยเมื่อคลิกที่ปุ่ม "Visualization" แลัว จะเข้าสู่หน้าจอ Preview โดยผู้ใช้สามารถคลิกที่ปุ่ม "ค้นหา" เพื่อดูข้อมูลทั้งหมดก่อนเพื่อดูโครงสร้างข้อมูลและตัวอย่างข้อมูล เพื่อจะได้วางแผนการวิเคราะห์ข้อมูลต่อไป

จากนั้นระบุเงื่อนไขการค้นหา (optional) และ คลิกที่ปุ่ม "รายงาน" และเลือกเงื่อนไขของ Aggregation function (จำนวน (count) จำนวนไม่ซ้ำ (count distinct) ผลรวม (sum) ค่าเฉลี่ย (avg) ค่าสูงสุด (max) ค่าต่ำสุด (min)) ระบุชื่อฟิลด์ที่จะให้คำนวณ ระบุฟิลด์ที่จะใช้แบ่งกลุ่ม (Group By) และ รูปแบบการจัดเรียง (Order By) และกด "ค้นหา" จากนั้น คลิกที่ไอคอนกราฟที่เกี่ยวข้อง ดังรูป โดยกราฟที่สามารถแสดงผลได้จะสามารถคลิกได้ และกราฟที่ไม่เกี่ยวข้องจะปรากฏเป็นสีเทาและไม่สามารถคลิกได้