API data.gov.my dari CFML: Cuaca, Banjir dan GTFS Transit

Guna data.gov.my dari CFML: cuaca, banjir dan GTFS

Portal data.gov.my kini mendedahkan Open API baharu yang boleh dicapai tanpa kunci API, dan ia berfungsi terus dari cfhttp Lucee. Artikel ini menunjukkan tiga kes guna sebenar: menarik ramalan cuaca tujuh hari, membaca data paras air banjir, dan memuat turun jadual transit awam GTFS. Jawapan pantas kepada soalan paling penting: had kadar rasmi ialah 4 permintaan seminit untuk setiap API, jadi anda mesti menyimpan keputusan dalam cache dan tidak memanggil endpoint pada setiap permintaan pelawat.

Kenapa data terbuka kerajaan penting untuk aplikasi CFML

Data terbuka membolehkan aplikasi Lucee memaparkan maklumat awam tanpa menandatangani kontrak komersial atau membina pengikis halaman yang rapuh. Cuaca, paras air banjir dan jadual transit adalah data yang berubah secara berkala dan berguna untuk papan pemuka, aplikasi mudah alih dan laman komuniti. Data ini datang daripada agensi seperti MET Malaysia dan operator transit, jadi anda mendapat maklumat rasmi tanpa perlu menyelenggara sumber sendiri. Dengan cfhttp dan deserializeJSON, integrasi ini boleh disiapkan dalam satu fungsi tanpa pustaka luar.

Portal data.gov.my dan Open API yang baharu

Open API baharu menggunakan URL asas https://api.data.gov.my dan didokumenkan di https://developer.data.gov.my dalam bahasa Inggeris dan Melayu. Ia tidak memerlukan token API; portal hanya mengenakan had kadar untuk mengelak penyalahgunaan. Had rasmi ialah 4 permintaan seminit untuk setiap API, merangkumi Data Catalogue, OpenDOSM, Weather, GTFS Static dan GTFS Realtime. Ini bermakna aplikasi anda patut merancang panggilan sebagai sumber yang jarang disegarkan, bukan panggilan per permintaan pelawat.

Sediakan persekitaran: cfhttp, redirect dan had 4 seminit

Setiap endpoint memulangkan redirect HTTP 301 yang menambah garis condong di hujung URL. Contohnya /weather/forecast dialih ke /weather/forecast/. Dua cara menanganinya: sertakan garis condong pada URL, atau tetapkan redirect true pada cfhttp supaya Lucee mengikut pengalihan secara automatik. Sentiasa guna https dan tetapkan timeout yang munasabah. Amalan asas memanggil API luar dibincangkan dalam panduan cfhttp dan panggilan API luar.

Cuaca: ramalan 7 hari dari MET Malaysia

Endpoint GET https://api.data.gov.my/weather/forecast/ memulangkan ramalan tujuh hari daripada MET Malaysia. Semasa ujian, endpoint ini membalas HTTP 200 dengan 3,080 rekod, dan setiap rekod membawa medan location, date, morning_forecast, afternoon_forecast, night_forecast, summary_forecast, summary_when, min_temp dan max_temp. Medan location ialah struktur bersarang dengan location_id dan location_name:

// Ramalan cuaca tujuh hari dari MET Malaysia
cfhttp(url = "https://api.data.gov.my/weather/forecast/?limit=5",
       method = "GET",
       result = "resp",
       timeout = 30,
       redirect = true);

forecasts = deserializeJSON(resp.filecontent);

for (f in forecasts) {
    writeOutput(f.location.location_name & ": "
        & f.summary_forecast & " ("
        & f.min_temp & "-" & f.max_temp & " C)<br>");
}

Gunakan parameter limit untuk mengurangkan beban dan hormati had kadar; tanpa limit, respons memulangkan keseluruhan set 3,080 rekod. deserializeJSON menukar respons menjadi tatasusunan struct yang boleh anda gelungkan terus, dengan min_temp dan max_temp sebagai nilai berangka. Sumber data ialah MET Malaysia.

Amaran cuaca dan gempa bumi

Endpoint GET https://api.data.gov.my/weather/warning/ memulangkan amaran cuaca aktif, contohnya amaran angin kencang dan laut bergelora. Setiap rekod membawa warning_issue dengan issued, title_bm dan title_en, serta valid_from, valid_to dan teks heading, body dan arahan dalam bahasa Inggeris dan Melayu. Setiap amaran membawa medan heading_bm, text_bm dan instruction_bm untuk paparan bahasa Melayu, jadi anda boleh memilih bahasa yang sepadan dengan laman anda. Endpoint berasingan untuk gempa bumi juga tersedia. Amaran ini berguna untuk laman komuniti yang memaparkan notis keselamatan.

Banjir: baca paras air dan semak kesegaran

Endpoint GET https://api.data.gov.my/flood-warning/ memulangkan rekod paras air daripada stesen sungai. Medan penting termasuk station_name, district, state, water_level_current dan water_level_indicator yang bernilai NORMAL, ALERT, DANGER atau ERROR, bersama paras normal, alert dan bahaya. Setiap rekod turut membawa station_id, latitude dan longitude stesen, sub_basin, main_basin dan water_level_trend, di samping medan hujan. Semasa ujian, endpoint memulangkan 1,276 rekod merangkumi 16 negeri dengan campuran keempat-empat indikator itu.

Ada satu kaveat yang mesti anda fahami: semua rekod yang dipulangkan meliputi tarikh sehingga 2024, menjadikan endpoint ini arkib peristiwa banjir lampau dan bukannya telemetri masa nyata. Sentiasa semak medan water_level_update_datetime sebelum memaparkan data sebagai semasa, dan paparkan tarikh itu bersama data supaya pembaca tidak tersilap anggap ia live.

GTFS Static: muat turun jadual transit awam

Endpoint GTFS Static memulangkan fail ZIP binari, bukan JSON. Kod yang disokong termasuk ktmb, prasarana dan pelbagai mybas mengikut bandar. Muat turun fail ke cakera dan unzip dengan cfzip, kemudian baca stops.txt dan routes.txt sebagai CSV:

<cfhttp url="https://api.data.gov.my/gtfs-static/ktmb/"
        method="get" result="resp" timeout="60" redirect="true"
        path="/tmp" file="gtfs_ktmb.zip">
</cfhttp>

<cfzip action="unzip" file="/tmp/gtfs_ktmb.zip"
       destination="/tmp/gtfs_ktmb/" overwrite="true">

<cfset stops = fileRead("/tmp/gtfs_ktmb/stops.txt")>

Fail stops.txt membawa lajur stop_id, stop_name, stop_lat dan stop_lon yang boleh anda hurai sebagai CSV untuk membina carian hentian atau peta. Zip itu turut mengandungi agency.txt dengan nama agensi seperti Keretapi Tanah Melayu, routes.txt, trips.txt, stop_times.txt, calendar.txt dan calendar_dates.txt, iaitu tujuh fail GTFS standard yang anda boleh simpan dan hurai satu persatu.

Data Catalogue: baca set data berstruktur

Selain data masa nyata, portal menyediakan Data Catalogue untuk set data berstruktur. Endpoint GET https://api.data.gov.my/data-catalogue/ memerlukan parameter id yang wajib; tanpa id ia memulangkan status 400 dengan mesej bahawa parameter id diperlukan. Nilai id merujuk set data tertentu, contohnya fuelprice untuk harga bahan api, dan senarai lengkap id tersedia di halaman Data Catalogue portal. Corak cfhttp dan deserializeJSON yang sama terpakai, dengan penjagaan cache yang sama kerana had kadar turut dikenakan pada Data Catalogue.

Corak cache: simpan keputusan, jangan panggil setiap pelawat

Dengan had 4 permintaan seminit, memanggil endpoint pada setiap permintaan pelawat akan menghabiskan kuota serta-merta dan memperlahankan laman anda. Corak yang betul ialah menyimpan keputusan dalam cache aplikasi dan menyegarkannya pada selang masa yang munasabah:

// Simpan keputusan dalam cache; segarkan paling kerap setiap 30 minit
cacheKey = "dgm_cuaca_forecast";
cached = cacheGet(cacheKey);

if (isNull(cached)) {
    cfhttp(url = "https://api.data.gov.my/weather/forecast/",
           method = "GET", result = "resp", timeout = 30, redirect = true);
    cached = resp.filecontent;
    cachePut(cacheKey, cached, createTimespan(0, 0, 30, 0));
}

forecasts = deserializeJSON(cached);

Tetapkan TTL 15 hingga 30 minit untuk cuaca, dan lebih lama untuk GTFS Static kerana jadual transit jarang berubah dalam sehari. Cache berfungsi mengikut skop yang dijelaskan dalam panduan memahami scope CFML, dan butiran penalaan lanjut ada dalam panduan caching dan prestasi Lucee.

Etika penggunaan dan had kadar

Portal menerbitkan Terma Penggunaan yang patut anda patuhi. Jangan panggil endpoint di dalam gelung per rekod; ambil sekali, simpan dalam cache dan papar. Gunakan parameter limit untuk mengehadkan saiz respons, dan proses senarai dengan gelung yang berkesan seperti diterangkan dalam panduan gelung dan kondisional CFML. Apabila pelayan membalas 429 Too Many Requests, perlahankan aplikasi anda dan tunggu sebelum mencuba semula, bukannya memaksa panggilan tambahan. Jika anda perlu memanggil beberapa endpoint berturut-turut, jarakkan panggilan supaya tidak melebihi 4 permintaan seminit secara keseluruhan.

Soalan Lazim (FAQ)

Perlu kunci API ke?

Tidak. Open API data.gov.my tidak memerlukan token; ia hanya mengenakan had kadar 4 permintaan seminit untuk setiap API.

Kenapa saya mendapat status 301?

API menambah garis condong di hujung URL. Ikut pengalihan dengan redirect true pada cfhttp, atau sertakan garis condong terus dalam URL.

Kenapa data banjir bertarikh 2024?

Endpoint flood-warning memulangkan arkib peristiwa banjir lampau, bukan telemetri langsung. Sentiasa semak water_level_update_datetime sebelum memaparkan data sebagai semasa.

GTFS keluar ZIP, macam mana saya baca dalam CFML?

Muat turun ke fail dengan cfhttp, unzip menggunakan cfzip, kemudian baca stops.txt dan routes.txt sebagai CSV.

Boleh saya panggil banyak stesen sekaligus?

Satu permintaan memulangkan banyak rekod, jadi guna parameter limit dan tapisan dan bukannya gelung panggilan. Jangan melebihi 4 permintaan seminit.