Hướng dẫn API cho bên thứ ba — UC-13

Mở rộng khả năng khai thác dữ liệu kịch bản khí hậu cho Bất động sản, Bảo hiểm, Nông nghiệp thông minh

Tài liệu mô tả các API và nguồn dữ liệu hiện có của hệ thống Kịch bản biến đổi khí hậu Việt Nam — truy xuất dữ liệu nguy cơ ngập lụt, thiên tai và biến đổi khí hậu phục vụ đánh giá rủi ro và ra quyết định.

1. Tổng quan

API/Nguồn dữ liệu	Mô tả	Định dạng trả về
`kichban_proxy.php`	Khí quyển, đại dương, cực đoan đô thị	JSON (GeoJSON nhúng)
`air.php`	Chất lượng không khí (PM2.5, PM10...)	JSON
Dữ liệu tĩnh	Nước biển dâng, nguy cơ ngập, sụt lún	JSON, GeoTIFF

Base URL: https://<domain>/kichban/

2. API Khí hậu — kichban_proxy.php

Proxy tới nguồn dữ liệu từ iws-imhen.vn, cung cấp bản đồ khí hậu dạng GeoJSON theo kịch bản, mùa và biến.

2.1 Endpoint

GET /kichban/api/kichban_proxy.php

2.2 Tham số

Tham số	Bắt buộc	Mô tả
`endpoint`	Có	Loại: `met`, `met_ocean`, `met_urban`
`varname`	Có	Mã biến khí hậu (xem bảng dưới)
`season`	Có	Mùa: ANNUAL, DJF, MAM, JJA, SON, hoặc tháng 01–12
`kichban`	Có	Kịch bản: ssp126, ssp245, ssp370
`giaidoan`	Có	Giai đoạn: baseline, 2021-2040, 2041-2060, 2081-2100
`location`	Không	Chỉ met_urban: HCM hoặc HANOI

2.3 Giá trị varname theo endpoint

Khí quyển (met): T2M, TAS_MEAN, Txx, Tnn, FD15, FD13, PR, PR_MONSUM, RX1day, RX5day, CDD, KBDI, HI, TX90p, HWD, HWI, Gió bề mặt...

Đại dương (met_ocean): sst, ssh, swh

Cực đoan đô thị (met_urban): Flood Risk, PR_TOTAL, RX1DAY, RX5DAY, R100MM, R50MM, SU37, SU35, T2M, TMIN, TNn, TMAX, TXx, WBGT, Nông nghiệp, Sức khỏe

2.4 Ví dụ request

GET /kichban/api/kichban_proxy.php?endpoint=met&varname=T2M&season=ANNUAL&kichban=ssp245&giaidoan=2041-2060

GET /kichban/api/kichban_proxy.php?endpoint=met_urban&varname=Flood%20Risk&season=ANNUAL&kichban=ssp245&giaidoan=2041-2060&location=HCM

2.5 Định dạng phản hồi

Thành công (HTTP 200):

{"geojson": "{\"type\":\"FeatureCollection\",\"features\":[...]}"}

geojson là chuỗi JSON — cần JSON.parse() trước khi dùng.

3. API Chất lượng không khí — air.php

Tham số	Mô tả
`var`	pm2p5, pm10, co, ch4, no2 (mặc định: pm2p5)
`file`	metadata.json hoặc step_001.json, step_002.json...

GET /kichban/api/air.php?var=pm2p5&file=metadata.json

4. Dữ liệu tĩnh

Nước biển dâng: /kichban/data/nuocbiendang/{SSP126|SSP245|SSP370|SSP585}_cm.json
Nguy cơ ngập (GeoTIFF): /kichban/data/ngap/{location}_{ssp245|ssp370}_{2050|2100}.tif
Sụt lún: /kichban/data/sutlun/HN_lun.tif
Ranh giới hành chính: DiaPhanTinh2025min.json, DiaPhanXa2025min.json, coastline.json

5. CORS và kỹ thuật

API hỗ trợ CORS (Access-Control-Allow-Origin: *). Hiện tại không yêu cầu xác thực. Khi triển khai API có kiểm soát: API key, ghi log, rate limit.

6. Ví dụ JavaScript

async function getClimateGeoJSON() {
  const url = '/kichban/api/kichban_proxy.php?' + new URLSearchParams({
    endpoint: 'met', varname: 'T2M', season: 'ANNUAL',
    kichban: 'ssp245', giaidoan: '2041-2060'
  });
  const res = await fetch(url);
  const data = await res.json();
  return JSON.parse(data.geojson);
}

7. Mã lỗi HTTP

200	Thành công
400	Tham số không hợp lệ
405	Chỉ hỗ trợ GET
500	Lỗi server / upstream