# Pengantar
PetaBencana.id adalah platform gratis dan terbuka untuk respon darurat dan penanggulangan bencana di kota-kota besar di Asia Selatan dan Tenggara. Platform ini memanfaatkan penggunaan sosial media yang tinggi saat situasi darurat untuk mengumpulkan, menyortir dan menampilkan informasi bencana terkonfirmasi secara real-time
Berpedoman pada paradigma “manusia adalah sensor terbaik”, dimana laporan terkonfirmasi dikumpulkan langsung dari pengguna yang langsung berada di lokasi kejadian dengan cara menghilangkan biaya mahal dan waktu dalam pemrosesan data. Kerangka ini menghasilkan data yang akurat dan real-time yang langsung dapat dilihat oleh pengguna dan *first responder*.
## API Data PetaBencana
Petabencana didukung oleh API data yang menyajikan sejumlah endpoint (ujung jalur informasi dalam jaringan) yang bersifat publik dan pribadi. Dokumentasi berikut memungkinkan pengembang untuk menjalankan sistem serupa. Proyek ini sepenuhnya terbuka dan kodenya tersedia di [Github PetaBencana](https://github.com/petabencana/). Diagram arsitektur tersedia dalam berbagai format:
* PDF
* [Visio XML](https://github.com/petabencana/petabencana-docs/tree/d8b3cac5b3bc2a65abd49d874bf9c5798e93eb97/petabencana.vdx)
* [OmniGraffle](https://github.com/petabencana/petabencana-docs/tree/d8b3cac5b3bc2a65abd49d874bf9c5798e93eb97/petabencana.graffle.zip)
### Sponsor Kami
#### Mitra Pendanaan
#### Mitra Pendukung
#### Mitra Proyek
#### Mitra Data
.png?alt=media)
# Informasi Umum
Terdapat sejumlah standar umum yang berlaku dari API yang dipanggil dan didokumentasikan di halaman-halaman berikutnya.
# Autentikasi
Petabencana API menyediakan beberapa rute yang diproteksi yang akan membutuhkan autentikasi untuk diakses. Autentikasi dilakukan melalui [JSON Web Token](https://jwt.io/introduction/).
Catatan: Untuk API *key* baru, silakan hubungi tim PetaBencana
# Pembuatan Versi
Versi API dibuat dengan versi string yang ditentukan dalam URL dasar yang dapat ditambahkan secara terpisah dari API lain.
Dianjurkan untuk menggunakan API terbaru yang tersedia.
Perubahan yang dianggap kompatibel dengan versi sebelumnya dan tidak memerlukan string versi untuk ditambahkan, diantaranya:
* Menambahkan properti ke objek JSON
* Menambahkan parameter baru
* Mengubah jumlah item yang dihasilkan dalam satu permintaan pencatatan
* Struktur atau panjang pengenal yang dihasilkan oleh API
* Mengubah pesan kesalahan
Perubahan yang dianggap tidak kompatibel dengan versi sebelumnya dan akan membutuhkan versi string untuk ditambahkan, diantaranya:
* Menghapus properti dari objek JSON
* Mengubah struktur URL API
Versi saat ini adalah v1
# Pembatasan Akses
Petabencana API memberlakukan pembatasan jumlah akses pada suatu permintaan endpoint. Jika Anda melebihi batas kapasitas, permintaan Anda akan dibatasi dan Anda akan menerima respon:
`HTTP 429 Too Many Requests responses from the API.` (terlalu banyak respon dari permintaan akses API)
Anda dianjurkan untuk tidak melebihi kuota yang ditentukan dan mencoba ulang dalam kode Anda.
# CORS
[Cross-Origin Requests](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) didukung tanpa batasan domain untuk memungkinkan kemudahan integrasi ke dalam aplikasi berbasis browser.
# HTTPS
Akses ke semua API melalui HTTPS adalah wajib. Permintaan yang dimulai melalui HTTP secara otomatis ditingkatkan ke HTTPS.
# Koordinat
Sistem referensi spasial yang digunakan adalah [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System).
# Kode Eror
Petabencana menggunakan [Kode Status HTTP](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) standar untuk mengkomunikasikan eror beserta pesan eror berformat json yang memberikan lebih banyak informasi tentang penyebabnya. Kode-kode utama yang digunakan adalah sebagai berikut:
Kode Eror 4xx
Eror yang dimulai dengan angka 4 biasanya menunjukkan masalah dari sisi pengguna yang harus diselesaikan sebelum meminta ulang layanan, diantaranya:
* **400 Bad Request** - biasanya disebabkan oleh parameter kueri yang salah, misalnya `"child \"type\" gagal karena [\"type\"` harus salah satu dari `[floodgates, pumps, waterways]]"`
* **403 Forbidden** - token autentikasi tidak valid
* **404 Not Found** - sumber daya tidak ditemukan, kemungkinan akibat dari endpoint yang salah atau mencoba mengambil catatan misalnya, sebuah laporan, yang tidak ada
* **409 Conflict** - sumber daya ada tetapi jika permintaan itu diizinkan, konflik akan terjadi di dalam sistem, misalnya, mengajukan laporan untuk kartu di mana laporan sudah ada
* **415 Unsupported Media Type** - file yang sedang diunggah tidak didukung oleh sistem - ini biasanya berarti file biner seperti gambar sedang diunggah tetapi Jenis Konten dengan jenis MIME terkait (misalnya `Image / jpeg`) belum didukung
* **429 Too Many Requests** - Anda telah melampaui kuota per detik atau per hari
## Kode Error 5xx
Eror yang dimulai dengan angka 5 biasanya menunjukkan kesalahan dari sisi server, diantaranya:
* **500 Internal Server Error** - kesalahan penampung-semua yang menunjukkan bahwa ada sesuatu yang gagal di sisi server
* **503 Service Unavailable** - layanan tidak aktif dan tidak dapat menanggapi permintaan
# Jenis Konten
Secara default, Petabencana API mengembalikan [JSON](http://www.w3schools.com/json/) untuk semua panggilan dan merespon setiap permintaan POST berformat JSON kecuali ada permintaan format lain. [UTF-8 encoding](https://en.wikipedia.org/wiki/UTF-8) digunakan pada semua permintaan dan respon.
Data geografis yang dipanggil akan dikodekan sebagai [TopoJSON](https://github.com/topojson/topojson/wiki) by default. [GeoJson](http://geojson.org/) juga didukung jika diperlukan, dengan menyertakan `format=topojson dalam panggilan API. Detail lebih lanjut tentang hal ini dapat ditemukan dalam dokumentasi rute API spesifik. Selain TopoJSON dan GeoJSON, kami menyediakan umpan publik dari informasi banjir real-time menggunakan standar` [`Common Alerting Protocol`](https://en.wikipedia.org/wiki/Common_Alerting_Protocol)`.`
# Contoh
Semua fitur API yang berfungsi disertakan dengan contoh panggilan HTTPS. Karena kami perlu memberikan header autentikasi dalam beberapa kasus untuk dapat terhubung, kami tidak dapat menjalankannya di browser web. Setiap contoh menunjukkan perintah [cURL](https://curl.haxx.se/docs/manpage.html) yang tersedia di Windows, Mac atau Linux. Perhatikan bahwa untuk rute yang diproteksi, Anda perlu memasukkan token JWT Anda sendiri agar berfungsi.
Jika Anda tidak terbiasa dengan baris perintah atau lebih memilih antarmuka pengguna, maka [Postman](https://www.getpostman.com/) adalah alat gratis yang baik untuk bereksperimen dengan API.
# Area Didukung
PetaBencana.id aktif dan dapat dimanfaatkan di seluruh provinsi di Indonesia. Kode provinsi dibutuhkan pada beberapa umpan. Berikut ini adalah daftar kode dari masing-masing provinsi:
# Jenis Bencana
PetaBencana.id mendukung 6 jenis bencana, diantaranya:
1. Banjir
2. Gempabumi
3. Angin Kencang
4. Kabut Asap
5. Kebakaran Hutan
6. Gunung Api
# Open API
API Data PetaBencana menyediakan sejumlah endpoint untuk Anda dapat berinteraksi dengan sistem. Ringkasan di bawah ini adalah detail lengkap dari setiap endpoint dan contoh hasil permintaan dapat ditemukan di halaman berikutnya.
## Ringkasan *Endpoint*
Detail dari setiap endpoint adalah sebagai berikut:
| Endpoint | Deskripsi | Metode | Terproteksi |
| ------------------- | ------------------------------------------ | ------- | ----------- |
| /admin | Batas Administrasi | GET | Tidak |
| /floodgauges | Alat Ukur Tinggi
Muka Air
| GET,PUT | Tidak |
| /floods | Genangan Banjir | GET | Sebagian |
| /floods/archive | Arsip Genangan Banjir | GET | Tidak |
| /floods/timeseries | Time Series
Genangan Banjir
| GET | Tidak |
| /infrastructure | Infrastruktur | GET | Tidak |
| /reports | Laporan Urun-daya | GET | Tidak |
| /reports/archive | Arsip Laporan
Urun-daya
| GET | Tidak |
| /reports/timeseries | Time Series Laporan
Urun-daya
| GET | Tidak |
| /stats/\* | Statistik Ringkasan | GET | Tidak |
# Laporan Urun-Daya
Laporan bencana urun daya secara realtime, secara default laporan akan disajikan selama periode satu jam terakhir.
## Format Permintaan
| Parameter Kueri | Deskripsi | Format | Wajib |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----- |
| admin | Area mana yang laporannya ingin disajikan? (lihat [Area Didukung](https://docs.petabencana.id/general/area-didukung)) | String | Tidak |
| format | Format apa yang diperlukan dari hasil yang diberikan? (tersedia secara *default* dalam `json`) | String | Tidak |
| geoformat | Format apa yang diperlukan untuk hasil geografis? (salah satu antara `topojson`, `geojson`, *default* ke `topojson`) | String | Tidak |
| disaster | Jenis bencana apa yang datanya ingin disajikan? (salah satu antara `flood, earthquake, fire, haze, wind volcano, secara default,` secara default menampilkan semua jenis bencana) | String | Tidak |
| timeperiod | Periode waktu berapa lama (dalam detik) yang dibutuhkan untuk menyajikan laporan, harus diantara 1 dan 604800 (1 minggu) | Number | Tidak |
## GET /reports
Daftar semua laporan banjir terkini untuk seluruh Indonesia
Note : Please include a User-Agent header in all of your requests. The User-Agent header helps us identify your requests and troubleshoot any issues you may have. To set the User-Agent header, add the following line to your request headers:
```
curl --user-agent "YOUR-UA-STRING" "https://api.petabencana.id/reports"
```
Daftar semua laporan banjir terkini untuk Jakarta (menerapkan parameter kueri admin, lihat [Kode Wilayah](/general/area-didukung) untuk melihat data dari provinsi lain)
```
curl --user-agent "YOUR-UA-STRING" "https://api.petabencana.id/reports?admin=ID-JK"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"properties": {
"pkey": "5519",
"created_at": "2016-12-09T21:37:00.000Z",
"source": "qlue",
"status": "confirmed",
"url": null,
"image_url": "https://lh3.googleusercontent.com/ByClSrW6QhFkBxUhZo0rFt6eiVdvnEHisSzsgjaC9KxdGAQ6CYksTZRA1rcNP9cBGZiv6s4Vp5D8NzkAjPyrBs6c6R4h=s480-c",
"disaster_type": "flood",
"report_data": null,
"tags": {
"instance_region_code": "jbd",
"local_area_id": "350"
},
"title": " ",
"text": "Perlu penataan dan dirapihkan @ahokbtp semoga bisa lbh baik, bersih dan teratur"
},
"coordinates": [
0,
0
]
}
]
}
},
"arcs": [],
"transform": {
"scale": [
1,
1
],
"translate": [
106.817276,
-6.138229
]
},
"bbox": [
106.817276,
-6.138229,
106.817276,
-6.138229
]
}
}
```
# Laporan Urun-Daya/Timeseries
Rangkaian waktu laporan banjir (lihat dokumentasi *endpoint* [Laporan Urun-Daya](https://docs.petabencana.id/routes/laporan-urun-daya)), disajikan sebagai penghitungan laporan banjir setiap jam dalam periode waktu tertentu. Hitungan dicatat di samping stempel waktu per jam dalam format ISO8601 pada UTC + 0.
## Format Permintaan
| Parameter Kueri | Deskripsi | Format | Wajib |
| --------------- | -------------------------------- | ------------------------------------------------------ | ----- |
| start | Waktu mulai periode *timeseries* | String dalam format ISO 8601 (YYYY-MM-DDTHH:mm:ss+ZZZZ | Ya |
| end | Waktu akhir periode *timeseries* | String dalam format ISO 8601 (YYYY-MM-DDTHH:mm:ss+ZZZZ | Ya |
Perhatikan bahwa zona waktu harus ditentukan sebagai perbedaan waktu +/- UTC yang memerlukan pengkodean karakter HTML (mis. +0700 menjadi% 2B0700).
## Get /reports/timeseries
Note : Please include a User-Agent header in all of your requests. The User-Agent header helps us identify your requests and troubleshoot any issues you may have. To set the User-Agent header, add the following line to your request headers:
GET (mendapatkan) hitungan laporan banjir dalam periode waktu tertentu.
```
curl --user-agent "YOUR-UA-STRING" "https://api.petabencana.id/reports?timeperiod=2592000"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": [
{
"ts": "2017-11-26T05:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-26T06:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-26T07:00:00.000Z",
"count": "2"
},
{
"ts": "2017-11-26T08:00:00.000Z",
"count": "3"
}
]
}
```
# Area Banjir
Informasi banjir realtime - berdasarkan kota dan status banjir (jika diperlukan). Mendukung *endpoint* /states yang non-geografis dan hanya memberikan status wilayah terdampak banjir serta *endpoint* geografis yang akan memberikan wilayah tergenang dengan *minimum\_state* atau semua wilayah dengan status banjirnya saat ini. Selain [topojson](https://github.com/topojson/topojson/wiki) dan [geojson](http://geojson.org/), titik akhir ini mendukung [Common Alerting Protocol (CAP)](https://en.wikipedia.org/wiki/Common_Alerting_Protocol).
Perhatikan bahwa status banjir dalam format CAP memiliki waktu kadaluarsa *default* 6 jam sejak permintaan API dibuat.
## Kode Status Banjir
Kode numerik yang digunakan untuk merepresentasikan kondisi banjir adalah sebagai berikut:
| Kode | Keparahan | Deskripsi |
| ---- | ---------- | ----------------------------------------------- |
| 1 | *Unknown* | KETINGGIAN BANJIR TIDAK DIKETAHUI - HATI-HATI - |
| 2 | *Minor* | BANJIR ANTARA 10 hingga 70 SENTIMETER |
| 3 | *Moderate* | BANJIR ANTARA 71 hingga 150 SENTIMETER |
| 4 | *Severe* | BANJIR LEBIH DARI 150 SENTIMETER |
## Format Permintaan
| Parameter Kueri | Deskripsi | Format | Wajib |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- | ------ | ----- |
| admin | Area mana yang laporannya ingin disajikan? (saat ini hanya mendukung`ID-JK`) | String | Tidak |
| format | Format apa yang diperlukan dari hasil yang disajikan? (salah satu `json`, `xml`, default ke `json`) | String | Tidak |
| geoformat | Format apa yang diperlukan untuk hasil geografis? (salah satu antara `topojson`, `geojson`, `cap`, default ke `topojson`) | String | Tidak |
| minimum\_state | Berapa status banjir minimal yang ingin ditampilkan? (min: `1`, maks: `4`) | Number | Tidak |
## GET /floods
{% tabs %}
{% tab title="https" %}
Daftar semua wilayah terdampak banjir di Jakarta dengan status banjir 1 atau lebih tinggi.
```
curl "https://data.petabencana.id/floods?admin=ID-JK&minimum_state=1"
```
{% endtab %}
{% tab title="https" %}
Daftar semua wilayah terdampak banjir di Jakarta dengan status banjir 1 atau lebih tinggi dalam format CAP.
```
curl "https://data.petabencana.id/floods?admin=ID-JK&minimum_state=1&format=xml&geoformat=cap"
```
{% endtab %}
{% endtabs %}
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Polygon",
"properties": {
"area_id": "5",
"geom_id": "3174040004009000",
"area_name": "RW 09",
"parent_name": "GROGOL",
"city_name": "Jakarta",
"state": 1,
"last_updated": "2016-12-19T13:53:52.274Z"
},
"arcs": [
[
0
]
]
}
]
}
},
"arcs": [
[
[
9999,
7847
],
[
-507,
-6
],
[
-695,
-70
],
[
-317,
-221
],
[
-761,
-18
],
[
-516,
98
],
[
-641,
-61
],
[
-649,
-119
],
[
-169,
-762
],
[
-181,
-519
],
[
48,
-602
],
[
-130,
-162
],
[
64,
-1235
],
[
81,
-2351
],
[
136,
-1098
],
[
15,
-675
],
[
-1250,
-40
],
[
-879,
-6
],
[
-924,
217
],
[
-924,
425
],
[
-1800,
138
],
[
830,
1540
],
[
565,
1455
],
[
764,
1975
],
[
1018,
2079
],
[
384,
788
],
[
389,
1061
],
[
1398,
-76
],
[
296,
-25
],
[
360,
6
],
[
392,
-9
],
[
360,
-9
],
[
377,
12
],
[
323,
25
],
[
354,
76
],
[
296,
89
],
[
211,
42
],
[
290,
52
],
[
217,
28
],
[
341,
110
],
[
43,
-67
],
[
57,
-174
],
[
109,
-159
],
[
154,
-257
],
[
115,
-370
],
[
99,
-346
],
[
124,
-357
],
[
133,
-422
]
]
],
"transform": {
"scale": [
0.0000003311331833192323,
0.00000032713269326930546
],
"translate": [
106.7917869997,
-6.158925
]
},
"bbox": [
106.7917869997,
-6.158925,
106.7950980004,
-6.1556540002
]
}
}
```
Hasilnya adalah sebagai berikut:
```markup
https://data.petabencana.id/floods
petabencana.id Flood Affected Areas
2016-12-19T23:08:52+07:00
petabencana.id
https://petabencana.id/
https://data.petabencana.id/floods?parent_name=GROGOL&area_name=RW%2009&time=2016-12-19T22:41:35+07:00
GROGOL.RW_09.2016-12-19T22:41:35+07:00 Flood Affected Area
2016-12-19T22:41:35+07:00
GROGOL.RW_09.2016-12-19T22:41:35+07:00
BPBD.JAKARTA.GOV.ID
2016-12-19T22:41:35+07:00
Actual
Alert
Public
Met
FLOODING
Immediate
Minor
Observed
JAKARTA EMERGENCY MANAGEMENT AGENCY
FLOOD WARNING
AT 22:41 WIB THE JAKARTA EMERGENCY MANAGEMENT AGENCY OBSERVED FLOODING OF BETWEEN 10 and 70 CENTIMETERS IN GROGOL, RW 09.
https://petabencana.id/
RW 09, GROGOL
-6.1563580003,106.7950980004 -6.1563600004,106.7949299998 -6.1563829997,106.7947 -6.1564550003,106.7945949997 -6.1564609997,106.7943429997 -6.156429,106.7941719999 -6.156449,106.7939600001 -6.156488,106.793745 -6.1567369998,106.7936890001 -6.1569070004,106.7936290001 -6.1571040005,106.7936449999 -6.1571570003,106.7936019997 -6.157561,106.7936229998 -6.1583300004,106.7936500001 -6.1586889999,106.7936950004 -6.1589100002,106.7936999998 -6.1589229999,106.7932860005 -6.158925,106.7929949996 -6.1588540003,106.7926889999 -6.1587150002,106.7923830002 -6.1586699999,106.7917869997 -6.158166,106.7920619998 -6.1576899997,106.7922490003 -6.1570440005,106.7925020003 -6.1563639997,106.7928389996 -6.1561060004,106.7929660001 -6.1557589997,106.7930949997 -6.1557839999,106.7935580004 -6.1557920003,106.7936560004 -6.1557900002,106.7937749996 -6.1557930003,106.7939050002 -6.1557960005,106.7940240003 -6.1557920003,106.7941489998 -6.1557839999,106.7942560002 -6.1557589997,106.7943730002 -6.1557300001,106.7944710002 -6.1557160004,106.7945409999 -6.1556990005,106.7946369998 -6.1556900001,106.7947090004 -6.1556540002,106.7948220002 -6.1556760003,106.794836 -6.1557330003,106.794855 -6.155785,106.7948909998 -6.1558690002,106.7949420004 -6.1559900004,106.7949800003 -6.1561030002,106.7950130001 -6.1562200002,106.7950540001 -6.1563580003,106.7950980004
```
## GET /floods/states
Daftar semua status area terdampak banjir di Jakarta dengan status banjir 1 atau lebih tinggi.
```
curl "https://data.petabencana.id/floods/states?city=jbd&minimum_state=1"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": [
{
"area_id": "5",
"state": 1,
"last_updated": "2016-12-19T13:53:52.274Z"
}
]
}
```
## PUT /floods/:localAreaId
PUT (Menambahkan) status banjir baru dalam sistem untuk area lokal tertentu (aman, memerlukan token otorisasi).
```
curl -X PUT -H "Content-Type: application/json" -d '{
"state": 2
}' "https://data.petabencana.id/floods/5"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"localAreaId": 5,
"state": 2,
"updated": true
}
```
## DELETE /floods/:localAreaId
Menghapus seluruh status banjir untuk area lokal tertentu (aman, memerlukan token otorisasi).
```
curl -X DELETE "https://data.petabencana.id/floods/5"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"localAreaId": 5,
"state": null,
"updated": true
}
```
# Area Banjir/Arsip
Arsip area banjir (lihat dokumentasi [*endpoint* Area Banjir](https://docs.petabencana.id/routes/areabanjir)), disajikan sebagai status banjir maksimum yang tercatat untuk semua daerah yang terdampak banjir dalam periode waktu tertentu. Status maksimum area banjir dicatat di samping id area. Gunakan *endpoint* Area Banjir untuk mendapatkan batas geospasial dari masing-masing wilayah.
Saat ini data yang tersedia hanya untuk wilayah Jakarta.
## Format Permintaan
| Parameter Kueri | Deskripsi | Format | Wajib |
| --------------- | ------------------------- | ------------------------------------------------------ | ----- |
| start | Waktu mulai periode arsip | String dalam format ISO 8601 (YYYY-MM-DDTHH:mm:ss+ZZZZ | Ya |
| end | Waktu akhir periode arsip | String dalam format ISO 8601 (YYYY-MM-DDTHH:mm:ss+ZZZZ | Ya |
Perhatikan bahwa zona waktu harus ditentukan sebagai perbedaan waktu +/- UTC yang memerlukan pengkodean karakter HTML (mis. +0700 menjadi %2B0700).
## Get /floods/archive
## GET /floods
Daftar semua area terdampak banjir di Jakarta dengan status banjir 1 atau lebih tinggi.
```
curl "https://data.petabencana.id/floods/archive?start=2017-06-07T00:00:00%2B0700&end=2017-06-08T23:00:00%2B0700"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": [
{
"area_id": "509",
"last_updated": "2017-11-03T22:57:01.387Z",
"max_state": 1
},
{
"area_id": "510",
"last_updated": "2017-11-03T22:57:10.463Z",
"max_state": 4
}
]
}
```
# Area Banjir/Timeseries
Timeseries area terdampak banjir (lihat dokumentasi [*endpoint* Area Banjir](https://docs.petabencana.id/routes/areabanjir)), disajikan sebagai penghitungan area terdampak banjir setiap jam dalam periode waktu tertentu. Hitungan dicatat dengan stempel waktu per jam dalam format ISO8601 pada UTC + 0.
Saat ini data yang tersedia hanya untuk wilayah Jakarta.
## Format Permintaan
| Parameter Kueri | Deskripsi | Format | Wajib |
| --------------- | -------------------------------- | --------------------------------------------------- | ----- |
| start | Waktu mulai periode *timeseries* | String in ISO 8601 format (YYYY-MM-DDTHH:mm:ss+ZZZZ | Ya |
| end | Waktu akhir periode *timeseries* | String in ISO 8601 format (YYYY-MM-DDTHH:mm:ss+ZZZZ | Ya |
Perhatikan bahwa zona waktu harus ditentukan sebagai perbedaan waktu +/- UTC yang memerlukan pengkodean karakter HTML (mis. +0700 menjadi% 2B0700).
## Get /floods/timeseries
## GET /floods
Daftar semua area terdampak banjir di Jakarta dengan status banjir 1 atau lebih tinggi.
```
curl "https://data.petabencana.id/floods/timeseries?start=2017-11-20T11%3A00%3A00-0500&end=2017-11-20T15%3A00%3A00-0500"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": [
{
"ts": "2017-11-20T16:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-20T17:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-20T18:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-20T19:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-20T20:00:00.000Z",
"count": "0"
}
]
}
```
# Pemantauan TMA
Laporan pemantauan tinggi muka air secara *live*, secara default laporan akan ditampilkan untuk satu jam terakhir.
## Format Permintaan
| Parameter Kueri | Deskripsi | Format | Wajib |
| --------------- | ------------------------------------------------------------------------------------------------------------------ | ------ | ----- |
| admin | Area mana yang infrastrukturnya ingin disediakan? (saat ini hanya mendukung`ID-JK`) | String | Tidak |
| format | Format apa yang diperlukan dari hasil yang diberikan? (tersedia secara default dalam `json`) | String | Tidak |
| geoformat | Format apa yang diperlukan untuk hasil geografis? (salah satu antara `topojson`, `geojson`, default ke `topojson`) | String | Tidak |
## GET /floodgauges
Daftar semua laporan alat ukur tinggi muka air saat ini untuk Jakarta.
```
curl "https://data.petabencana.id/floodgauges?admin=ID-JK"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"properties": {
"gaugeid": "TMA00001",
"gaugenameid": "Bendung Katulampa",
"observations": [
{
"f1": "2016-12-09T04:00:00+00:00",
"f2": 30,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T05:00:00+00:00",
"f2": 30,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T06:00:00+00:00",
"f2": 30,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T07:00:00+00:00",
"f2": 30,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T08:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T09:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T10:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T11:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T12:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T13:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
}
]
},
"coordinates": [
6271,
0
]
},
{
"type": "Point",
"properties": {
"gaugeid": "TMA00002",
"gaugenameid": "Pos Depok",
"observations": [
{
"f1": "2016-12-09T04:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T05:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T06:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T07:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T08:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T09:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T10:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T11:00:00+00:00",
"f2": 95,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T12:00:00+00:00",
"f2": 95,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T13:00:00+00:00",
"f2": 95,
"f3": 4,
"f4": "SIAGA IV "
}
]
},
"coordinates": [
5354,
3943
]
},
// etc. etc. //
{
"type": "Point",
"properties": {
"gaugeid": "TMA00012",
"gaugenameid": "Waduk Pluit",
"observations": [
{
"f1": "2016-12-09T04:00:00+00:00",
"f2": -165,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T05:00:00+00:00",
"f2": -170,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T06:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T07:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T08:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T09:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T10:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T11:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T12:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T13:00:00+00:00",
"f2": -170,
"f3": 4,
"f4": "SIAGA IV "
}
]
},
"coordinates": [
4559,
9999
]
}
]
}
},
"arcs": [],
"transform": {
"scale": [
0.00002272427242724299,
0.000052198219821982215
],
"translate": [
106.69416,
-6.63304
]
},
"bbox": [
106.69416,
-6.63304,
106.92138,
-6.11111
]
}
}
```
# Infrastruktur
Lokasi infrastruktur lokal seperti pintu air (`floodgates`), pompa (`pumps`) dan saluran air (`waterways`).
## Format Permintaan
| Parameter URL | Deskripsi | Format | Wajib |
| ------------- | ------------------------------------------------------------------------------------------------------------- | ------ | ----- |
| type | Tipe infrastruktur apa yang ingin diperoleh daftarnya? (salah satu antara `floodgates`, `pumps`, `waterways`) | String | Tidak |
| Parameter Kueri | Deskripsi | Format | Wajib |
| --------------- | -------------------------------------------------------------------------------------------------------------------- | ------ | ----- |
| city | Area mana yang ingin diperoleh data infrastrukturnya? (saat ini hanya mendukung `ID-JK`) | String | Tidak |
| format | Format apa yang diperlukan dari hasil yang diberikan? (tersedia secara *default* dalam `json`) | String | Tidak |
| geoformat | Format apa yang diperlukan untuk hasil geografis? (salah satu antara `topojson`, `geojson`, *default* ke `topojson`) | String | Tidak |
## GET /infrastructure/:type
Menyajikan daftar pompa di Jakarta.
```
curl "https://data.petabencana.id/infrastructure/pumps?admin=ID-JK"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"properties": {
"name": "PA Marina"
},
"coordinates": [
7164,
7352,
0
]
},
{
"type": "Point",
"properties": {
"name": "Pompa Waduk Setia Budi Barat"
},
"coordinates": [
5312,
5077,
0
]
},
// etc. etc. //
{
"type": "Point",
"properties": {
"name": "Pompa UP Senen"
},
"coordinates": [
6143,
6544,
0
]
}
]
}
},
"arcs": [],
"transform": {
"scale": [
0.000020651319451945148,
0.000020217245084508508
],
"translate": [
106.7188310623,
-6.3060956581
]
},
"bbox": [
106.7188310623,
-6.3060956581,
106.9253236055,
-6.1039434245
]
}
}
```
# Statistik
Beberapa rangkuman statistik:
* [/stats/floodedRegionsSummary](/routes/statistik/floodedregionssummary) : rangkuman wilayah RW yang terdampak banjir berdasarkan status tinggi banjir
* [/stats/floodedRWsSummary](/routes/statistik/floodedrwssummary) : rangkuman jumlah RW terdampak banjir
* [/stats/reportsSummary](/routes/statistik/reportssummary) : rangkuman laporan urun daya
# Stats - Rangkuman Laporan Urun-Daya
Perhitungan laporan urun daya berdasarkan sumber ("qlue" untuk Qlue, "detik" untuk Detik (Pasangmata), atau "grasp" untuk laporan dari kombinasi Twitter, Facebook, Telegram dan Website PetaBencana.id), secara default laporan akan disajikan untuk satu jam terakhir.
## Format Permintaan
| Parameter Kueri | Deskripsi | Format | Wajib |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ----- |
| admin | Area mana yang laporannya ingin disajikan? (lihat [Area Didukung](https://docs.petabencana.id/general/area-didukung)) | String | Tidak |
| timeperiod | Periode waktu berapa lama (dalam detik) yang dibutuhkan untuk menyajikan laporan, harus diantara 1 dan 604800 (1 minggu) | Number | Tidak |
## GET /stats/getReportsSummary.md
```
curl "https://data.petabencana.id/stats/reportsSummary?city=jbd"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"properties": {
"pkey": "5519",
"created_at": "2016-12-09T21:37:00.000Z",
"source": "qlue",
"status": "confirmed",
"url": null,
"image_url": "https://lh3.googleusercontent.com/ByClSrW6QhFkBxUhZo0rFt6eiVdvnEHisSzsgjaC9KxdGAQ6CYksTZRA1rcNP9cBGZiv6s4Vp5D8NzkAjPyrBs6c6R4h=s480-c",
"disaster_type": "flood",
"report_data": null,
"tags": {
"instance_region_code": "jbd",
"local_area_id": "350"
},
"title": " ",
"text": "Perlu penataan dan dirapihkan @ahokbtp semoga bisa lbh baik, bersih dan teratur"
},
"coordinates": [
0,
0
]
}
]
}
},
"arcs": [],
"transform": {
"scale": [
1,
1
],
"translate": [
106.817276,
-6.138229
]
},
"bbox": [
106.817276,
-6.138229,
106.817276,
-6.138229
]
}
}
```
# Stats - Rangkuman RW Banjir
Perhitungan semua RW terdampak banjir berdasarkan status tinggi banjir.
## Format Permintaan
| Parameter Kueri | Deskripsi | Format | Wajib |
| --------------- | ---------------------------------------------------------------------------- | ------ | ----- |
| admin | Area mana yang laporannya ingin disajikan? (saat ini hanya mendukung`ID-JK`) | String | Tidak |
## GET /stats/floodedRWsSummary
```
curl "https://data.petabencana.id/stats/floodedRWsSummary?city=jbd"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"# hati-hati RWs": 0,
"# 10-70cm RWs": 9,
"# 71-150cm RWs": 0,
"# 151cm+ RWs": 0
}
```
# Stats - Rangkuman Wilayah
Daftar seluruh wilayah administrasi yang RWnya saat ini terdampak banjir.
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | ---------------------------------------------------------------------------- | ------ | -------- |
| admin | Area mana yang laporannya ingin disajikan? (saat ini hanya mendukung`ID-JK`) | String | Tidak |
## GET /stats/floodedRegionsSummary
```
curl "https://data.petabencana.id/stats/floodedRegionsSummary?admin=ID-JK"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"total number of regions with flooded RWs": 4,
"regions with flooded RWs": [
"KAPUK",
"RAWA TERATE",
"CIPINANG MELAYU",
"CENGKARENG BARAT"
]
}
```
# API Terauntentikasi
API Data PetaBencana menyediakan sejumlah endpoint untuk Anda dapat berinteraksi dengan sistem. Ringkasan di bawah ini adalah detail lengkap dari setiap endpoint yang membutuhkan autentikasi dan contoh hasil permintaan dapat ditemukan di halaman berikutnya.
## Ringkasan *Endpoint*
Detail dari setiap endpoint adalah sebagai berikut:
| Endpoint | Deskripsi | Metode | Terproteksi |
| -------- | ------------- | ------- | ----------- |
| /cards | Kartu Laporan | GET,PUT | Ya |
| /feeds | Umpan | GET,PUT | Ya |
# Kartu Laporan
Kartu laporan PetaBencana untuk kejadian bencana. Catatan: [autentikasi](https://docs.petabencana.id/general/authentication) diperlukan untuk membuat pembaruan pada kartu.
## Format Permintaan
| Parameter URL | Deskripsi | Format | Wajib |
| ------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------- | ----- |
| cardId | Pengenal unik dari kartu yang ingin kita gunakan, dihasilkan oleh sistem ketika kartu awal dibuat (wajib) | String (7 sampai 14 karakter) | Ya |
| Atribut | Deskripsi | Format | Wajib |
| ----------- | ---------------------------------------------------- | --------------------------------------------------------------------- | ----- |
| card\_data | Data pengguna yang dikumpulkan dalam antarmuka kartu | JSON | Ya |
| text | Deskripsi dari kejadian bencana | String | Tidak |
| image\_id | Pengenal gambar kartu terkait | String | Tidak |
| created\_at | Tanggal dan jam kartu dibuat | Date ([ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm)) | Ya |
| location | Lokasi geografis dari kejadian bencana | Lat/Long in [ESPG:4326](http://spatialreference.org/ref/epsg/wgs-84/) | Ya |
### Catatan untuk card\_data
Data kartu membutuhkan objek `report_type` untuk ada. Dimana`disaster_type` diatur ke 'flood' dan objek `flood_depth` juga harus ada di sebelah `report_type`. Jika `disaster_type` adalah 'prep' maka `report_type` harus menjadi salah satu jenis seperti yang ditentukan di server config.js.
Misalnya kartu dengan data banjir termasuk flood\_depth:
```javascript
"disaster_type": "flood",
"card_data":{
"report_type": "flood",
"flood_depth": 50
}
```
Atau, kartu dengan laporan data pra-banjir tentang saluran pembuangan.
```javascript
"disaster_type": "prep",
"card_data":{
"report_type":"drain"
}
```
## GET /cards/:cardId
Dapatkan detail kartu:
Berikut adalah panggilan sederhana untuk GET kartu:
```
curl -X GET -H "X-Api-Key: API_KEY_GOES_HERE" "https://data.petabencana.id/cards/abcdefg"
```
Kartu telah ditemukan:
```javascript
{
"statusCode": 200,
"result": {
"pkey": "2",
"card_id": "abcdefg",
"username": "user",
"network": "test",
"language": "en",
"received": true,
"report_id": "1"
}
}
```
Kartu tidak ada:
```javascript
{
"statusCode": 404,
"found": false,
"result": null
}
```
## PUT /cards/:cardId
Memperbarui kartu dengan detail laporan kejadian bencana:
Berikut adalah panggilan sederhana untuk PUT kartu:
```
curl -X PUT -H "X-Api-Key: API_KEY_GOES_HERE" -d '{
"text": "test card",
"disaster_type": "flood"
"card_data":
{
"report_type": "flood",
"flood_depth": 101
},
"created_at":"2016-12-09T11:32:52.011Z",
"location": {
"lat": -6.149531,
"lng": 106.869342
}
}' "https://data.petabencana.id/cards/abcdefg"
```
Kartu telah berhasil dibuat:
```javascript
{
"statusCode": 200,
"cardId": "abcdefg",
"created": true
}
```
Kartu tidak ada:
```javascript
{
"statusCode": 404,
"cardId": "abcdefg",
"message": "No card exists with id 'abcdefg'"
}
```
Laporan sudah ada untuk kartu:
```javascript
{
"statusCode": 409,
"cardId": "abcdefg",
"message": "Report already received for card 'abcdefg'"
}
```
## GET /cards/:cardId/images
GET URL S3 yang ditandai untuk mengunggah laporan kartu, ini harus dilakukan setelah laporan kartu dibuat dan hanya satu gambar yang ada untuk kartu tertentu.
CATATAN: Setelah gambar dikirim, proses sisi server mengkompres gambar ke ukuran standar dan mungkin ada sedikit jeda waktu beberapa detik sebelum gambar tampil secara "live".
Berikut ini panggilan sederhana GET untuk URL S3 baru yang telah ditandai untuk unggahan gambar:
```
curl -X GET \
https://api-server-dev.riskmap.in/cards/HJID8CWN-/images
```
URL S3 yang telah ditandai berhasil dibuat:
```javascript
{"signedRequest":"https://riskmap-image-uploads.s3.ap-south-1.amazonaws.com/originals/BJbTHR-Vb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJFMR3NR7BXZ5X7DA%2F20170629%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20170629T012002Z&X-Amz-Expires=900&X-Amz-Signature=ad10a53555205fa18ecfa07da52eb0349ed1c8bda66fe2de0fa9c445c61b7c62&X-Amz-SignedHeaders=host","url":"https://s3.ap-south-1.amazonaws.com/riskmap-image-uploads/originals/BJbTHR-Vb.jpg"}
```
# Umpan
Petabencana memanfaatkan umpan data dari sejumlah sumber pihak ketiga. Endpoint ini memungkinkan pembuatan data ke dalam sistem untuk pengguna yang berwenang. Catatan: [autentikasi](https://docs.petabencana.id/general/authentication) diperlukan untuk mengirim data melalui endpoint /feeds (/umpan).
## POST /feeds/qlue
Menambahkan laporan ke sistem dari [Qlue](https://www.qlue.co.id/). Atribut-atribut yang didukung untuk laporan Qlue:
| Atribut | Deskripsi | Format | Wajib |
| -------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----- |
| post\_id | Pengenal unik untuk laporan Qlue | Integer | Ya |
| created\_at | Tanggal dan jam kartu dibuat | Date ([ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm)) | Ya |
| title | Judul laporan yang dimasukkan | String | Tidak |
| text | Deskripsi dari kejadian bencana | String | Tidak |
| image\_url | URL dari gambar terkait | String | Tidak |
| qlue\_city | Dari area mana laporan berasal? (lihat Area Didukung) | String | Ya |
| disaster\_type | Jenis bencana apa yang dilaporkan? (Saat ini hanya mendukung bencana `flood /`banjir) | String | Ya |
| location | Lokasi geografis dari kejadian bencana | Lat/Long in [ESPG:4326](http://spatialreference.org/ref/epsg/wgs-84/) | Ya |
Berikut adalah panggilan sederhana untuk POST laporan baru dari Qlue:
```
curl -X POST -H "X-Api-Key: API_KEY_GOES_HERE" -d '{
"post_id":1234567802,
"created_at":"2016-12-09T11:32:52.011Z",
"image_url":"http://myimg",
"qlue_city":"jabodetabek",
"disaster_type":"flood",
"text":"A big flood",
"location": {
"lat": -6.149531,
"lng": 106.869342
}
}' "https://data.petabencana.id/feeds/qlue"
```
Laporan telah berhasil dibuat:
```javascript
{
"post_id": 1234567802,
"created": true
}
```
Permintaan telah berhasil namun laporannya sudah ada:
```javascript
{
"post_id": 1234567802,
"created": false,
"message": "1234567802 already exists in reports table"
}
```
# Laporan Urun-Daya/Arsip
Arsip laporan bencana
\
Catatan: [autentikasi](/general/authentication) diperlukan untuk mengakses data arsip
## Format Permintaan
| Parameter Kueri | Deskripsi | Format | Wajib |
|---|
| start | Waktu mulai periode arsip | String dalam format ISO 8601 (YYYY-MM-DDTHH:mm:ss+ZZZZ | Ya |
| end | Waktu akhir periode arsip | String dalam format ISO 8601 (YYYY-MM-DDTHH:mm:ss+ZZZZ | Ya |
| disaster | Jenis bencana apa yang datanya ingin disajikan? (salah satu antara flood, earthquake, fire, haze, wind, volcano, tidak memfilter secara default) | String | Tidak |
| admin | Area mana yang laporannya ingin disajikan? (lihat Area Didukung) | | |
| geoformat | Format apa yang diperlukan untuk hasil geografis? (salah satu antara topojson, geojson, default ke topojson) | String | Tidak |
Perhatikan bahwa zona waktu harus ditentukan sebagai perbedaan waktu +/- UTC yang memerlukan pengkodean karakter HTML (mis. +0700 menjadi% 2B0700).
## Get /reports/archive
Catatan : Harap sertakan header User-Agent di semua permintaan Anda. Header User-Agent membantu kami mengidentifikasi permintaan Anda dan memecahkan masalah apa pun yang mungkin Anda alami. Untuk menyetel header User-Agent, tambahkan baris berikut ke header permintaan Anda:
Daftar laporan bencana yang diterima dalam jangka waktu tertentu
```
curl --user-agent "YOUR-UA-STRING" -H "X-Api-Key: API_KEY_GOES_HERE" "https://api.petabencana.id/archive/reports?start=2017-12-04T00%3A00%3A00%2B0700&end=2017-12-06T05%3A00%3A00%2B0700&geoformat=geojson"
```
Hasilnya adalah sebagai berikut:
```javascript
{
"statusCode": 200,
"result": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
106.815842,
-6.183179
]
},
"properties": {
"pkey": "0001",
"created_at": "2017-12-04T09:51:00.000Z",
"source": "qlue",
"status": "confirmed",
"url": null,
"image_url": null,
"disaster_type": "flood",
"report_data": null,
"tags": {
"instance_region_code": "jbd",
"local_area_id": "782"
},
"title": " ",
"text": "#flood report"
}
}
]
}
}
```
# Informasi Lisensi Data
Data ini dilisensikan dengan model lisensi ganda untuk mendukung akses publik dan keberlanjutan.
* **CC BY-NC 4.0 (Non-Komersial)**: Gratis untuk penggunaan non-komersial dengan atribusi.
* **CC BY 4.0 (Komersial)**: Tersedia untuk penggunaan komersial dengan atribusi dan berdasarkan perjanjian lisensi komersial.
Dengan mengakses atau menggunakan data ini, Anda setuju untuk mematuhi syarat lisensi yang berlaku. Silakan hubungi kami jika Anda memiliki pertanyaan tentang lisensi yang sesuai dengan kebutuhan Anda.
# Penggunaan Non-Komersial (CC BY-NC 4.0)
Data ini tersedia untuk tujuan non-komersial di bawah Lisensi **Creative Commons Atribusi-NonKomersial 4.0 Internasional (CC BY-NC 4.0).**
**Atribusi**: Anda harus memberikan kredit yang sesuai kepada PetaBencana.id, menyediakan tautan ke lisensi, dan menyebutkan jika ada perubahan yang dilakukan. Pengguna non-komersial tidak boleh menggunakan materi untuk tujuan komersial. Pastikan teks mudah dibaca dan dipahami, dengan mempertimbangkan ukuran font, warna, kontras, posisi, dan durasi tampilannya. Kami menyarankan mengikuti panduan aksesibilitas seperti WCAG dan peraturan relevan setempat.
Format Atribusi:
"Data disediakan oleh PetaBencana.id, dilisensikan di bawah CC BY-NC 4.0."
**Untuk Pengguna Non-Komersial**: Jika Anda adalah lembaga publik, organisasi kemanusiaan, peneliti, atau individu yang menggunakan data ini untuk tujuan pendidikan atau non-profit, Anda dapat menggunakannya di bawah lisensi CC BY-NC.
# Penggunaan Komersial (CC BY 4.0)
Untuk **pengguna komersial**, diperlukan **Lisensi Komersial CC BY 4.0**. Lisensi ini memberikan izin untuk menggunakan data dalam tujuan komersial, dengan ketentuan:
* Atribusi diberikan kepada PetaBencana.id
* Biaya lisensi atau perjanjian telah diatur dengan tim kami untuk penggunaan komersial yang sah.
**Untuk Akses Lisensi Komersial**: Silakan hubungi kami untuk mendapatkan data di bawah lisensi CC BY untuk tujuan komersial. Pengguna komersial akan mendapatkan hak untuk menggunakan data sesuai dengan ketentuan CC BY, termasuk untuk aplikasi berbayar atau integrasi dalam produk komersial.
**Format Atribusi**:\
Data disediakan oleh PetaBencana.id, dilisensikan di bawah CC BY 4.0.
Pastikan teks mudah dibaca dan dipahami, dengan mengikuti pedoman aksesibilitas seperti WCAG dan peraturan relevan setempat.
# Perjanjian Lisensi Pengguna
Perjanjian Lisensi Pengguna ("Perjanjian") ini adalah perjanjian yang mengikat secara hukum antara Anda ("Pemegang Lisensi" atau "Pengguna") dan Yayasan Peta Bencana ("Pemberi Lisensi") terkait penggunaan data PetaBencana.id, termasuk namun tidak terbatas pada semua kumpulan data dan materi yang menyertainya ("Data").
1. **Pemberian Lisensi**
* **1.1 Penggunaan Non-Komersial**: Untuk tujuan non-komersial, Data dilisensikan di bawah lisensi **Creative Commons Atribusi-NonKomersial 4.0 Internasional (CC BY-NC 4.0).** Di bawah lisensi ini, pengguna non-komersial dapat menggunakan, berbagi, dan mengadaptasi Data dengan bebas untuk menyesuaikannya dengan kebutuhan atau konteks tertentu, asalkan memberikan atribusi yang sesuai kepada PetaBencana.id.
* **1.2 Penggunaan Komersial**: Untuk penggunaan komersial, Data dilisensikan di bawah lisensi **Creative Commons Atribusi 4.0 Internasional (CC BY 4.0)**. Pengguna komersial harus mendapatkan lisensi komersial dengan menghubungi Yayasan Peta Bencana dan diizinkan menggunakan Data dalam operasional bisnis mereka dengan atribusi yang sesuai kepada PetaBencana.id.
2. **Pembatasan Penggunaan**
* **2.1 Penggunaan yang Dilarang**: Pengguna tidak boleh:
* Menggunakan Data untuk tujuan yang melanggar hukum atau tidak sah.
* Mendistribusikan atau melisensikan ulang Data untuk tujuan komersial tanpa izin eksplisit di bawah lisensi Penggunaan Komersial.
* Mengubah atau membuat karya turunan yang mempengaruhi akurasi Data.
* **2.2 Kewajiban Atribusi**: Pengguna non-komersial dan komersial harus memberikan kredit kepada PetaBencana.id saat menggunakan Data di ruang publik, mengikuti pedoman atribusi yang disediakan di Bagian 4.
3. **Integritas Data dan Pembaruan**
* **3.1 Akurasi**: Yayasan Peta Bencana berupaya memastikan akurasi Data, namun Data disediakan "apa adanya" tanpa jaminan atau garansi terkait kelengkapan, keandalan, atau kecocokan untuk tujuan tertentu.
* **3.2 Pembaruan**: Pengguna akan menerima pembaruan Data yang disediakan oleh Yayasan Peta Bencana. Yayasan Peta Bencana berhak mengubah atau menghentikan akses ke Data sesuai kebijakannya.
4. **Kewajiban Atribusi**
* **4.1 Penggunaan Non-Komersial**: Saat menggunakan Data, pengguna non-komersial harus menyertakan atribusi sebagai berikut: "Data disediakan oleh PetaBencana.id, dilisensikan di bawah CC BY-NC 4.0." dengan tautan ke situs organisasi atau sumber lain yang ditentukan.
* **4.2 Penggunaan Komersial**: Pengguna komersial harus menghubungkan Data ke \[Nama Organisasi Anda] sebagai berikut:
* "Data disediakan oleh PetaBencana.id, dilisensikan di bawah CC BY 4.0," dengan opsi untuk menambahkan logo organisasi, jika memungkinkan, untuk konsistensi pengakuan.
5. **Batasan Tanggung Jawab**
* **5.1 Tanggung Jawab**: Sejauh diizinkan oleh hukum, Yayasan Peta Bencana tidak bertanggung jawab atas kerusakan, kerugian, atau kewajiban yang timbul dari atau terkait dengan penggunaan atau ketidakmampuan untuk menggunakan Data, baik dalam kontrak, gugatan, atau lainnya.
6. **Pengakhiran**
* **6.1 Pengakhiran untuk Pelanggaran**: Yayasan Peta Bencana berhak untuk mengakhiri lisensi ini jika Pemegang Lisensi gagal mematuhi ketentuan Perjanjian ini. Setelah pengakhiran, Pemegang Lisensi harus menghentikan semua penggunaan Data dan menghapus salinan yang ada dalam kepemilikan mereka.
* **6.2 Kelanjutan**: Bagian 5 dan 6 dari Perjanjian ini akan tetap berlaku meskipun Perjanjian ini berakhir atau kadaluwarsa.
7. **Ketentuan Lain-lain**
* **7.1 Hukum yang Berlaku**: Perjanjian ini akan diatur dan ditafsirkan sesuai dengan hukum Indonesia.
* **7.2 Keseluruhan Perjanjian**: Perjanjian ini merupakan keseluruhan perjanjian antara Yayasan Peta Bencana dan Pemegang Lisensi terkait penggunaan Data dan menggantikan perjanjian sebelumnya.
\
**Dengan menggunakan atau mengakses Data, Anda mengakui bahwa Anda telah membaca, memahami, dan menyetujui untuk terikat oleh Perjanjian ini.**
# Introduction
PetaBencana.id is a free and transparent platform for emergency response and disaster management in megacities in South and Southeast Asia. The platform harnesses the heightened use of social media during emergency events to gather, sort, and display confirmed hazard information in real-time.
The platform adopts a “people are the best sensors” paradigm, where confirmed reports are collected directly from the users at street level in a manner that removes expensive and time-consuming data processing. This framework creates accurate, real-time data which is immediately made available for users and first responders.
PetaBencana.id gathers, sorts, and visualizes data using specially developed Situational Intelligence Open Source Software (Siti OSS), to transform the noise of social and digital media into critical information for residents, communities, and government agencies.
## Petabencana Data API
Petabencana is backed by a data [API](https://en.wikipedia.org/wiki/Application_programming_interface) exposing a number of public and private endpoints. The documentation that follows allows developers to get up and running. The project is fully open source and the code is available in the [PetaBencana GitHub](https://github.com/petabencana/). The architectural diagram is available in different formats:
* [PDF](https://github.com/petabencana/petabencana-docs/tree/d8b3cac5b3bc2a65abd49d874bf9c5798e93eb97/petabencana.pdf)
* [Visio XML](https://github.com/petabencana/petabencana-docs/tree/d8b3cac5b3bc2a65abd49d874bf9c5798e93eb97/petabencana.vdx)
* [OmniGraffle](https://github.com/petabencana/petabencana-docs/tree/d8b3cac5b3bc2a65abd49d874bf9c5798e93eb97/petabencana.graffle.zip)
# General
There are a number of general standards which apply regardless of the API being called and these are documented in the pages that follow.
# Authentication
The Petabencana API exposes some protected routes which will require authentication to access few API endpoints (see [Authenticated API](https://app.gitbook.com/s/-MPDZ_lSLJEcu9sJTiy--887967055/~/changes/FHZxzleBDEXMkDTZ4YeM/routes-1)). Authentication is via a [JSON Web Token](https://jwt.io/introduction/)
Note: For a new API key, please reach out to PetaBencana team
# Versioning
The API is versioned with a version string specified in the base URL that can be incremented independently from other APIs.
Using the newest available API is always encouraged.
These changes are considered backwards compatible and will not require the version string to be incremented:
* Adding properties to JSON objects
* Adding new parameters
* Changing the number of items returned in a single listing request
* The structure or length of identifiers generated by the API
* Changing error messages
These changes are considered backwards incompatible and will require the version string to be incremented:
* Removing properties from JSON objects
* Changing an API's URL structure
The current version is v1
# Rate Limits
The Petabencana API employs rate limiting that cap the number of requests that can be made against an endpoint. If you exceed a rate limit, your request will be throttled and you will receive `HTTP 429 Too Many Requests responses from the API.`
You are encouraged to always stay within your allocated quota and implement retries in your code where applicable.
# CORS
[Cross-Origin Requests](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) are supported with no domain restrictions to allow for ease of integration into browser based applications.
# HTTPS
Access to all APIs over HTTPS is mandatory. Requests initiated over HTTP are automatically upgraded to HTTPS.
# Coordinates
The default spatial reference system used is [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System).
# Error Codes
Petabencana uses the standard [HTTP Status Codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) to communicate errors together with a json formatted error message giving more information as to the root cause of the error. The main codes used are as follows:
## 4xx Errors
Errors starting with a 4 generally indicate a client side issue that must be resolved before re-querying the service such as:
* **400 Bad Request** - normally caused by an incorrect query parameter e.g. `"child \"type\" fails because [\"type\" must be one of [floodgates, pumps, waterways]]"`
* **403 Forbidden** - the authentication token is invalid
* **404 Not Found** - the resource was not found, this may indicate an incorrect endpoint or trying to retrieve a record for example, a report, which does not exist
* **409 Conflict** - the resource exists but if the request was allowed a conflict would be created in the system, for example, filing a report for a card where a report already exists
* **415 Unsupported Media Type** - the file being uploaded is not supported by the system - this usually means a binary file such as an image is being uploaded but the Content-Type header with the associated MIME type (e.g. \`image/jpeg\`) has not been supplied
* **429 Too Many Requests** - you have exceeded your per second or per day quota of requests
## 5xx Errors
Errors starting with a 5 generally indicate a server side fault and should be immediately:
* **500 Internal Server Error** - a catch-all error indicating that something has failed server side
* **503 Service Unavailable** - the service is down and cannot respond to requests
# Content Types
By default the Petabencana API returns [JSON](http://www.w3schools.com/json/) for all calls and expects any POST requests to supply JSON formatted bodies unless otherwise advised. [UTF-8 encoding](https://en.wikipedia.org/wiki/UTF-8) is used on all requests and responses.
Where Geographic data is returned this is will be encoded as [TopoJSON](https://github.com/topojson/topojson/wiki) by default. [GeoJson](http://geojson.org/) is also supported if required, by supplying `format=topojson in the API call. More details of this can be found in the specific API route documentation. In addition to TopoJSON and GeoJson we provide a public feed of real-time flood information using the`[`Common Alerting Protocol`](https://en.wikipedia.org/wiki/Common_Alerting_Protocol)`standard.`
# Examples
The APIs all feature worked examples with sample HTTPS calls. As we need to pass authentication headers in some cases to be able to connect we cannot run these in a web browser. Each example shows a [cURL](https://curl.haxx.se/docs/manpage.html) command which is available on Windows, Mac or Linux. Note that for protected routes you will need to insert your own JWT token for these to work.
If you are not comfortable with the command line or generally prefer a user interface then [Postman](https://www.getpostman.com/) is a fantastic free tool for experimenting with APIs.
# Supported Area
PetaBencana.id is active and can be utilized in all provinces in Indonesia. Provincial codes are required on some feeds. The following is a list of codes for each province:
# Supported Hazards
PetaBencana.id supports six types of disasters, as follow:
1. Flood
2. Earthquake
3. Extreme Wind
4. Forest Fire
5. Haze
6. Volcano
For the scope of this documentation, the disasters will have the following information
| Disaster Type | report\_type | Attribute details |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Flood | flood | flood\_depth: flood severity based on depth in cm
< 70 cm : Minor
70 - 150 cm : Moderate
150 cm : Severe
|
| Earthquake | road | accessabilityFailure: the level of road damage affected by earthquake
0 : < 0,5 m (No Vehicle Access)
1 : 0,6 - 1 m (2-Wheel Vehicle Access)
2 or 3 : 1.1 - 1.8 m (4-Wheel Vehicle Access)
4 : >1,9 m (Large Vehicle Access)
|
| Earthquake | structure | structureFailure: the level of structure damage affected by earthquake
0 : Cracking
1 : Partially Collapse
2 : Fully Collapse
|
| Extreme Wind | wind | impact: level of disruption caused by extreme wind
0 : Low Disruption
1 : Medium Disruption
2 : High Disruption
|
| Haze | haze | visibility: the distance one can see as determined by light and weather conditions
0: can see but need to wear a mask
1: can see but not clean enough to drive
2: can barely see, too dangerous to go out
airQuality: described by symptoms felt by humans
0 or 1: Poor Air Quality
2: Severe Air Quality
3 or 4 : Hazardous Air Quality
|
| Forest Fire | fire | fireRadius: the radius of a forest fire estimated by the human eye |
| Volcano | volcano | volcanicSigns: described by symptoms felt by humans
0 : Significant Temperature Increases,
1 : Drought / Vegetation Death,
2: Unusual Animal Behaviour,
3: Frequent Earthquake Tremors,
4: Frequent Rumbling Sounds
evacuationNumber: Number of people in your village
< 50
5 - 50
> 50
evacuationArea: Do you know where to evacuate to?
|
# Open API
The Petabencana Data API provides a number of endpoints for interacting with the system. These are summarised below, full details of the open endpoints together with worked examples can be found in the pages that follow.
## Summary of Endpoints
Details of each endpoint are as follows.
| Endpoint | Description | Methods | Protected |
| ------------------- | ------------------- | ------- | --------- |
| /cards | GRASP Cards | GET,PUT | Yes |
| /feeds | Feeds | GET,PUT | Yes |
| /floodgauges | Flood Gauges | GET,PUT | No |
| /floods | Floods | GET | Partial |
| /floods/archive | Floods Archive | GET | No |
| /floods/timeseries | Floods Time Series | GET | No |
| /infrastructure | Infrastructure | GET | No |
| /reports | Reports | GET | No |
| /reports/archive | Reports Archive | GET | No |
| /reports/timeseries | Reports Time Series | GET | No |
| /stats/\* | Summary Statistics | GET | No |
# Cards
Petabencana report cards for disaster events. Note: [authentication](https://docs.petabencana.id/general/authentication.html) is required to make updates to cards.
## Request Format
| URL Parameter | Description | Format | Required |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------- |
| cardId | Unique identifier of the card we wish to work with, this is generated by the system when the initial card is created (required) | String (7 to 14 characters) | Yes |
| Attribute | Description | Format | Required |
| ----------- | ----------------------------------------- | --------------------------------------------------------------------- | -------- |
| card\_data | User data collected in card interface | JSON | Yes |
| text | Description of the disaster event | String | No |
| image\_id | Identifier of the associated card image | String | No |
| created\_at | Date and time the card was created | Date ([ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm)) | Yes |
| location | Geographic location of the disaster event | Lat/Long in [ESPG:4326](http://spatialreference.org/ref/epsg/wgs-84/) | Yes |
### Note on card\_data
Card data requires the object `report_type` to exist. Where `disaster_type` is set to 'flood' then the object `flood_depth` should also exist adjacent to `report_type`. Where the `disaster_type` is 'prep' then `report_type` should be one of the types as specified in server config.js.
| Disaster Type | report\_type | Attribute details |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Flood | flood | flood\_depth: flood severity based on depth in cm
< 70 cm : Minor
70 - 150 cm : Moderate
150 cm : Severe
|
| Earthquake | road | accessabilityFailure: the level of road damage affected by earthquake
0 : < 0,5 m (No Vehicle Access)
1 : 0,6 - 1 m (2-Wheel Vehicle Access)
2 or 3 : 1.1 - 1.8 m (4-Wheel Vehicle Access)
4 : >1,9 m (Large Vehicle Access)
|
| Earthquake | structure | structureFailure: the level of structure damage affected by earthquake
0 : Cracking
1 : Partially Collapse
2 : Fully Collapse
|
| Extreme Wind | wind | impact: level of disruption caused by extreme wind
0 : Low Disruption
1 : Medium Disruption
2 : High Disruption
|
| Haze | haze | visibility: the distance one can see as determined by light and weather conditions
0: can see but need to wear a mask
1: can see but not clean enough to drive
2: can barely see, too dangerous to go out
airQuality: described by symptoms felt by humans
0 or 1: Poor Air Quality
2: Severe Air Quality
3 or 4 : Hazardous Air Quality
|
| Forest Fire | fire | **fireRadius**: the radius of a forest fire estimated by the human eye |
For example a card with flood data including flood\_depth:
```javascript
"disaster_type": "flood",
"card_data":{
"report_type": "flood",
"flood_depth": 50
}
```
Or, a card with pre-flood data report regarding a drain.
```javascript
"disaster_type": "prep",
"card_data":{
"report_type":"drain"
}
```
## GET /cards/:cardId
Retrieve details of a card:
Here is a simple call to GET a card:
```
curl -X GET -H "X-Api-Key: API_KEY_GOES_HERE" "https://data.petabencana.id/cards/abcdefg"
```
The card was found:
```javascript
{
"statusCode": 200,
"result": {
"pkey": "2",
"card_id": "abcdefg",
"username": "user",
"network": "test",
"language": "en",
"received": true,
"report_id": "1"
}
}
```
The card does not exist:
```javascript
{
"statusCode": 404,
"found": false,
"result": null
}
```
## PUT /cards/:cardId
Update a card with details a disaster event report:
Here is a simple call to PUT a card:
```
curl -X PUT -H "X-Api-Key: API_KEY_GOES_HERE" -d '{
"text": "test card",
"disaster_type": "flood"
"card_data":
{
"report_type": "flood",
"flood_depth": 101
},
"created_at":"2016-12-09T11:32:52.011Z",
"location": {
"lat": -6.149531,
"lng": 106.869342
}
}' "https://data.petabencana.id/cards/abcdefg"
```
Card was successfully created:
```javascript
{
"statusCode": 200,
"cardId": "abcdefg",
"created": true
}
```
The card does not exist:
```javascript
{
"statusCode": 404,
"cardId": "abcdefg",
"message": "No card exists with id 'abcdefg'"
}
```
The report already exists for the card:
```javascript
{
"statusCode": 409,
"cardId": "abcdefg",
"message": "Report already received for card 'abcdefg'"
}
```
## GET /cards/:cardId/images
GET a signed S3 URL to upload a card report, this must be done after the card report has been created and only one image can exist for a given card.
NOTE: After an image is submitted a server-side process shrinks the image to a standard size and there may be a small time lag of a few seconds before the image goes "live".
Here is a simple call to GET a new signed S3 URL for image upload:
```
curl -X GET \
https://api-server-dev.riskmap.in/cards/HJID8CWN-/images
```
Signed S3 URL successfully generated:
```javascript
{"signedRequest":"https://riskmap-image-uploads.s3.ap-south-1.amazonaws.com/originals/BJbTHR-Vb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJFMR3NR7BXZ5X7DA%2F20170629%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20170629T012002Z&X-Amz-Expires=900&X-Amz-Signature=ad10a53555205fa18ecfa07da52eb0349ed1c8bda66fe2de0fa9c445c61b7c62&X-Amz-SignedHeaders=host","url":"https://s3.ap-south-1.amazonaws.com/riskmap-image-uploads/originals/BJbTHR-Vb.jpg"}
```
# Feeds
Petabencana utilises data feeds from a number of third party sources. This endpoint allows the creation of data into the system for authorised users. Note: [authentication](https://docs.petabencana.id/general/authentication.html) is required to post data through the /feeds endpoint.
## POST /feeds/qlue
Add a report to the system from [Qlue](http://www.qlue.co.id/). The following attributes are supported for Qlue reports:
| Attribute | Description | Format | Required |
| -------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------- |
| post\_id | Unique qlue identifier for the report | Integer | Yes |
| created\_at | Date and time the card was created | Date ([ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm)) | Yes |
| title | The title of the report being filed | String | No |
| text | Description of the disaster event | String | No |
| image\_url | URL of the associated image | String | No |
| qlue\_city | From which city was the report generated (must be one of `jabodetabek`, `bandung`, `surabaya`) | String | Yes |
| disaster\_type | What type of disaster is being reported (currently only `flood`is supported) | String | Yes |
| location | Geographic location of the disaster event | Lat/Long in [ESPG:4326](http://spatialreference.org/ref/epsg/wgs-84/) | Yes |
Here is a simple call to POST a new Qlue report:
```
curl -X POST -H "X-Api-Key: API_KEY_GOES_HERE" -d '{
"post_id":1234567802,
"created_at":"2016-12-09T11:32:52.011Z",
"image_url":"http://myimg",
"qlue_city":"jabodetabek",
"disaster_type":"flood",
"text":"A big flood",
"location": {
"lat": -6.149531,
"lng": 106.869342
}
}' "https://data.petabencana.id/feeds/qlue"
```
Report was successfully created:
```javascript
{
"post_id": 1234567802,
"created": true
}
```
The request was successful however the report already exists:
```javascript
{
"post_id": 1234567802,
"created": false,
"message": "1234567802 already exists in reports table"
}
```
# Flood Gauges
Live flood gauge reports, by default reports will be returned for the last hour.
Currently this data is only available for Jakarta.
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| city | Which [province](https://docs.petabencana.id/v/master/general/supported-area) do we wish to return infrastructure for? (currently available for `ID-JK`) | String | No |
| format | Which format should we return results in? (one of `json`, defaults to `json`) | String | No |
| geoformat | What format should geographic results use (one of `topojson`, `geojson` defaults to `topojson`) | String | No |
## GET /floodgauges
List all current flood gauge reports for Jakarta.
```
curl "https://data.petabencana.id/floodgauges?admin=ID-JK"
```
Results are as follows:
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"properties": {
"gaugeid": "TMA00001",
"gaugenameid": "Bendung Katulampa",
"observations": [
{
"f1": "2016-12-09T04:00:00+00:00",
"f2": 30,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T05:00:00+00:00",
"f2": 30,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T06:00:00+00:00",
"f2": 30,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T07:00:00+00:00",
"f2": 30,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T08:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T09:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T10:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T11:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T12:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T13:00:00+00:00",
"f2": 40,
"f3": 4,
"f4": "SIAGA IV "
}
]
},
"coordinates": [
6271,
0
]
},
{
"type": "Point",
"properties": {
"gaugeid": "TMA00002",
"gaugenameid": "Pos Depok",
"observations": [
{
"f1": "2016-12-09T04:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T05:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T06:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T07:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T08:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T09:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T10:00:00+00:00",
"f2": 100,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T11:00:00+00:00",
"f2": 95,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T12:00:00+00:00",
"f2": 95,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T13:00:00+00:00",
"f2": 95,
"f3": 4,
"f4": "SIAGA IV "
}
]
},
"coordinates": [
5354,
3943
]
},
// etc. etc. //
{
"type": "Point",
"properties": {
"gaugeid": "TMA00012",
"gaugenameid": "Waduk Pluit",
"observations": [
{
"f1": "2016-12-09T04:00:00+00:00",
"f2": -165,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T05:00:00+00:00",
"f2": -170,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T06:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T07:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T08:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T09:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T10:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T11:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T12:00:00+00:00",
"f2": -175,
"f3": 4,
"f4": "SIAGA IV "
},
{
"f1": "2016-12-09T13:00:00+00:00",
"f2": -170,
"f3": 4,
"f4": "SIAGA IV "
}
]
},
"coordinates": [
4559,
9999
]
}
]
}
},
"arcs": [],
"transform": {
"scale": [
0.00002272427242724299,
0.000052198219821982215
],
"translate": [
106.69416,
-6.63304
]
},
"bbox": [
106.69416,
-6.63304,
106.92138,
-6.11111
]
}
}
```
# Flooded Area
Live flood information - by city, by flood state (if required). Supports a /states endpoint which is non-geographic and simply gives the state of flooded areas as well as a geographic endpoint which will give flooded areas subject to a minimum\_state or all areas together with their current flood status. In addition to [topojson](https://github.com/topojson/topojson/wiki) and [geojson](http://geojson.org/) this endpoint supports the [Common Alerting Protocol (CAP)](https://en.wikipedia.org/wiki/Common_Alerting_Protocol).
Note that flood states in CAP format have a default expiry time of 6 hours from the time that the API request is made.
Currently this data is only available for Jakarta.
## Flood State Codes
Numeric codes are used to represent flood states, these are as follows:
| Code | Severity | Description |
| ---- | -------- | -------------------------------------------- |
| 1 | Unknown | AN UNKNOWN LEVEL OF FLOODING - USE CAUTION - |
| 2 | Minor | FLOODING OF BETWEEN 10 and 70 CENTIMETERS |
| 3 | Moderate | FLOODING OF BETWEEN 71 and 150 CENTIMETERS |
| 4 | Severe | FLOODING OF OVER 150 CENTIMETERS |
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| admin | Which [province](https://docs.petabencana.id/v/master/general/supported-area) do we wish to return the reports for? (currently available for `ID-JK`) | String | No |
| format | Which format should we return results in? (one of `json`, `xml`, defaults to `json`) | String | No |
| geoformat | What format should geographic results use (one of `topojson`, `geojson`, `cap` defaults to `topojson`) | String | No |
| minimum\_state | The minimum flood state that should be returned? (min: `1`, max: `4`) | Number | No |
## GET /floods
{% tabs %}
{% tab title="Geo" %}
List all flooded areas in Jakarta with a flood state of 1 or higher.
```
curl "https://data.petabencana.id/floods?admin=ID-JK&minimum_state=1"
```
{% endtab %}
{% tab title="CAP" %}
List all flooded areas in Jakarta with a flood state of 1 or higher in CAP format.
```
curl "https://data.petabencana.id/floods?city=jbd&minimum_state=1&format=xml&geoformat=cap"
```
{% endtab %}
{% endtabs %}
Results are as follows:
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Polygon",
"properties": {
"area_id": "5",
"geom_id": "3174040004009000",
"area_name": "RW 09",
"parent_name": "GROGOL",
"city_name": "Jakarta",
"state": 1,
"last_updated": "2016-12-19T13:53:52.274Z"
},
"arcs": [
[
0
]
]
}
]
}
},
"arcs": [
[
[
9999,
7847
],
[
-507,
-6
],
[
-695,
-70
],
[
-317,
-221
],
[
-761,
-18
],
[
-516,
98
],
[
-641,
-61
],
[
-649,
-119
],
[
-169,
-762
],
[
-181,
-519
],
[
48,
-602
],
[
-130,
-162
],
[
64,
-1235
],
[
81,
-2351
],
[
136,
-1098
],
[
15,
-675
],
[
-1250,
-40
],
[
-879,
-6
],
[
-924,
217
],
[
-924,
425
],
[
-1800,
138
],
[
830,
1540
],
[
565,
1455
],
[
764,
1975
],
[
1018,
2079
],
[
384,
788
],
[
389,
1061
],
[
1398,
-76
],
[
296,
-25
],
[
360,
6
],
[
392,
-9
],
[
360,
-9
],
[
377,
12
],
[
323,
25
],
[
354,
76
],
[
296,
89
],
[
211,
42
],
[
290,
52
],
[
217,
28
],
[
341,
110
],
[
43,
-67
],
[
57,
-174
],
[
109,
-159
],
[
154,
-257
],
[
115,
-370
],
[
99,
-346
],
[
124,
-357
],
[
133,
-422
]
]
],
"transform": {
"scale": [
0.0000003311331833192323,
0.00000032713269326930546
],
"translate": [
106.7917869997,
-6.158925
]
},
"bbox": [
106.7917869997,
-6.158925,
106.7950980004,
-6.1556540002
]
}
}
```
Results are as follows:
```markup
https://data.petabencana.id/floods
petabencana.id Flood Affected Areas
2016-12-19T23:08:52+07:00
petabencana.id
https://petabencana.id/
https://data.petabencana.id/floods?parent_name=GROGOL&area_name=RW%2009&time=2016-12-19T22:41:35+07:00
GROGOL.RW_09.2016-12-19T22:41:35+07:00 Flood Affected Area
2016-12-19T22:41:35+07:00
GROGOL.RW_09.2016-12-19T22:41:35+07:00
BPBD.JAKARTA.GOV.ID
2016-12-19T22:41:35+07:00
Actual
Alert
Public
Met
FLOODING
Immediate
Minor
Observed
JAKARTA EMERGENCY MANAGEMENT AGENCY
FLOOD WARNING
AT 22:41 WIB THE JAKARTA EMERGENCY MANAGEMENT AGENCY OBSERVED FLOODING OF BETWEEN 10 and 70 CENTIMETERS IN GROGOL, RW 09.
https://petabencana.id/
RW 09, GROGOL
-6.1563580003,106.7950980004 -6.1563600004,106.7949299998 -6.1563829997,106.7947 -6.1564550003,106.7945949997 -6.1564609997,106.7943429997 -6.156429,106.7941719999 -6.156449,106.7939600001 -6.156488,106.793745 -6.1567369998,106.7936890001 -6.1569070004,106.7936290001 -6.1571040005,106.7936449999 -6.1571570003,106.7936019997 -6.157561,106.7936229998 -6.1583300004,106.7936500001 -6.1586889999,106.7936950004 -6.1589100002,106.7936999998 -6.1589229999,106.7932860005 -6.158925,106.7929949996 -6.1588540003,106.7926889999 -6.1587150002,106.7923830002 -6.1586699999,106.7917869997 -6.158166,106.7920619998 -6.1576899997,106.7922490003 -6.1570440005,106.7925020003 -6.1563639997,106.7928389996 -6.1561060004,106.7929660001 -6.1557589997,106.7930949997 -6.1557839999,106.7935580004 -6.1557920003,106.7936560004 -6.1557900002,106.7937749996 -6.1557930003,106.7939050002 -6.1557960005,106.7940240003 -6.1557920003,106.7941489998 -6.1557839999,106.7942560002 -6.1557589997,106.7943730002 -6.1557300001,106.7944710002 -6.1557160004,106.7945409999 -6.1556990005,106.7946369998 -6.1556900001,106.7947090004 -6.1556540002,106.7948220002 -6.1556760003,106.794836 -6.1557330003,106.794855 -6.155785,106.7948909998 -6.1558690002,106.7949420004 -6.1559900004,106.7949800003 -6.1561030002,106.7950130001 -6.1562200002,106.7950540001 -6.1563580003,106.7950980004
```
## GET /floods/states
List all flooded area states in Jakarta with a flood state of 1 or higher.
```
curl "https://data.petabencana.id/floods/states?city=jbd&minimum_state=1"
```
Results are as follows:
```javascript
{
"statusCode": 200,
"result": [
{
"area_id": "5",
"state": 1,
"last_updated": "2016-12-19T13:53:52.274Z"
}
]
}
```
## PUT /floods/:localAreaId
PUT a new flood state in the system for a given local area (secure, requires authorisation token).
```
curl -X PUT -H "Content-Type: application/json" -d '{
"state": 2
}' "https://data.petabencana.id/floods/5"
```
Results are as follows:
```javascript
{
"localAreaId": 5,
"state": 2,
"updated": true
}
```
## DELETE /floods/:localAreaId
Clears the flood state entirely for a given local area (secure, requires authorisation token).
```
curl -X DELETE "https://data.petabencana.id/floods/5"
```
Results are as follows:
```javascript
{
"localAreaId": 5,
"state": null,
"updated": true
}
```
# Flooded Area/Archive
Archive of flooded areas (see [Floods endpoint](/master-1/routes/flooded-area) documentation), presented as the maximum flood state recorded for all flood affected areas within the specified time period. Maximum state is recorded alongside area id. Use the Floods endpoint to get geospatial boundaries of individual areas.
Currently this data is only available for Jakarta.
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | ----------------------------- | --------------------------------------------------- | -------- |
| start | Start time for archive period | String in ISO 8601 format (YYYY-MM-DDTHH:mm:ss+ZZZZ | Yes |
| end | End time for archive period | String in ISO 8601 format (YYYY-MM-DDTHH:mm:ss+ZZZZ | Yes |
Note that time zone must be specified as +/- UTC offset which will require HTML character encoding (e.g. +0700 becomes %2B0700).
## Get /floods/archive
## GET /floods
List all flooded areas in Jakarta with a flood state of 1 or higher.
```
curl "https://data.petabencana.id/floods/archive?start=2017-06-07T00:00:00%2B0700&end=2017-06-08T23:00:00%2B0700"
```
Results are as follows:
```javascript
{
"statusCode": 200,
"result": [
{
"area_id": "509",
"last_updated": "2017-11-03T22:57:01.387Z",
"max_state": 1
},
{
"area_id": "510",
"last_updated": "2017-11-03T22:57:10.463Z",
"max_state": 4
}
]
}
```
# Flooded Area/Timeseries
Time series of flooded areas (see [Floods endpoint](/master-1/routes/flooded-area) documentation), presented as the count of flood affected areas every hour within the specified time period. Count is recorded alongside an hourly timestamp in ISO8601 format at UTC+0.
Currently this data is only available for Jakarta.
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | -------------------------------- | --------------------------------------------------- | -------- |
| start | Start time for timeseries period | String in ISO 8601 format (YYYY-MM-DDTHH:mm:ss+ZZZZ | Yes |
| end | End time for timeseries period | String in ISO 8601 format (YYYY-MM-DDTHH:mm:ss+ZZZZ | Yes |
Note that time zone must be specified as +/- UTC offset which will require HTML character encoding (e.g. +0700 becomes %2B0700).
## Get /floods/timeseries
## GET /floods
List all flooded areas in Jakarta with a flood state of 1 or higher.
```
curl "https://data.petabencana.id/floods/timeseries?start=2017-11-20T11%3A00%3A00-0500&end=2017-11-20T15%3A00%3A00-0500"
```
Results are as follows:
```javascript
{
"statusCode": 200,
"result": [
{
"ts": "2017-11-20T16:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-20T17:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-20T18:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-20T19:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-20T20:00:00.000Z",
"count": "0"
}
]
}
```
# Infrastructure
Locations of local infrastructure including flood gates, pumps and waterways.
Currently this data is only available for Jakarta.
## Request Format
| URL Parameter | Description | Format | Required |
| ------------- | -------------------------------------------------------------------------------------------- | ------ | -------- |
| type | What type of infrastructure do we wish to list? (one of `floodgates`, `pumps`, `waterways`) | String | Yes |
| Query Parameter | Description | Format | Required |
| --------------- | ----------------------------------------------------------------------------------------------- | ------ | -------- |
| admin | Which province do we wish to return infrastructure for? (currently available for `ID-JK`) | String | No |
| format | Which format should we return results in? (one of `json`, defaults to `json`) | String | No |
| geoformat | What format should geographic results use (one of `topojson`, `geojson` defaults to `topojson`) | String | No |
## GET /infrastructure/:type
Return a list of pumps in Jakarta.
```
curl "https://data.petabencana.id/infrastructure/pumps?admin=ID-JK"
```
Results are as follows:
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"properties": {
"name": "PA Marina"
},
"coordinates": [
7164,
7352,
0
]
},
{
"type": "Point",
"properties": {
"name": "Pompa Waduk Setia Budi Barat"
},
"coordinates": [
5312,
5077,
0
]
},
// etc. etc. //
{
"type": "Point",
"properties": {
"name": "Pompa UP Senen"
},
"coordinates": [
6143,
6544,
0
]
}
]
}
},
"arcs": [],
"transform": {
"scale": [
0.000020651319451945148,
0.000020217245084508508
],
"translate": [
106.7188310623,
-6.3060956581
]
},
"bbox": [
106.7188310623,
-6.3060956581,
106.9253236055,
-6.1039434245
]
}
}
```
# Crowdsourced Reports
Live disaster reports, by default reports will be returned for the last 3 hour.
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| admin | Which province do we wish to return the reports for? (see [supported area](https://docs.petabencana.id/v/master/general/supported-area)) | String | No |
| format | Which format should we return results in? (one of `json , xml`, defaults to `json`) | String | No |
| disaster | Which [disaster](https://docs.petabencana.id/v/master/general/supported-hazards) should we return the result? (one of`flood, earthquake, fire, haze, wind volcano,`doesn't filter by default) | string | No |
| geoformat | What format should geographic results use (one of `topojson`, `geojson, cap` defaults to `topojson`) | String | No |
| timeperiod | What time period (in seconds) to list reports for, must be strictly between 1 and 604800 (1 week) | Number | No |
## GET /reports
List all current reports from Indonesia
Note : Please include a User-Agent header in all of your requests. The User-Agent header helps us identify your requests and troubleshoot any issues you may have. To set the User-Agent header, add the following line to your request headers:
```javascript
curl --user-agent "YOUR-UA-STRING" "https://api.petabencana.id/reports"
```
List all current reports from Jakarta.
```
curl --user-agent "YOUR-UA-STRING" "https://api.petabencana.id/reports?admin=ID-JK"
```
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"properties": {
"pkey": "5519",
"created_at": "2016-12-09T21:37:00.000Z",
"source": "qlue",
"status": "confirmed",
"url": null,
"image_url": "https://lh3.googleusercontent.com/ByClSrW6QhFkBxUhZo0rFt6eiVdvnEHisSzsgjaC9KxdGAQ6CYksTZRA1rcNP9cBGZiv6s4Vp5D8NzkAjPyrBs6c6R4h=s480-c",
"disaster_type": "flood",
"report_data": null,
"tags": {
"instance_region_code": "ID-JK",
"local_area_id": "350"
},
"title": " ",
"text": "Perlu penataan dan dirapihkan @ahokbtp semoga bisa lbh baik, bersih dan teratur"
},
"coordinates": [
0,
0
]
}
]
}
},
"arcs": [],
"transform": {
"scale": [
1,
1
],
"translate": [
106.817276,
-6.138229
]
},
"bbox": [
106.817276,
-6.138229,
106.817276,
-6.138229
]
}
}
```
# Crowdsourced Reports/Archive
# Crowdsourced Reports/Timeseries
Time series of flood reports (see [Reports endpoint](/master-1/routes/crowdsourced-reports) documentation), presented as the count of flood reports every hour within the specified time period. Count is recorded alongside an hourly timestamp in ISO8601 format at UTC+0.
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | -------------------------------- | --------------------------------------------------- | -------- |
| start | Start time for timeseries period | String in ISO 8601 format (YYYY-MM-DDTHH:mm:ss+ZZZZ | Yes |
| end | End time for timeseries period | String in ISO 8601 format (YYYY-MM-DDTHH:mm:ss+ZZZZ | Yes |
Note that time zone must be specified as +/- UTC offset which will require HTML character encoding (e.g. +0700 becomes %2B0700).
## Get /reports/timeseries
Note : Please include a User-Agent header in all of your requests. The User-Agent header helps us identify your requests and troubleshoot any issues you may have. To set the User-Agent header, add the following line to your request headers:
Get count of flood reports within specified time period.
```
curl --user-agent "YOUR-UA-STRING" "https://api.petabencana.id/reports?timeperiod=2592000"
```
Results are as follows:
```javascript
{
"statusCode": 200,
"result": [
{
"ts": "2017-11-26T05:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-26T06:00:00.000Z",
"count": "0"
},
{
"ts": "2017-11-26T07:00:00.000Z",
"count": "2"
},
{
"ts": "2017-11-26T08:00:00.000Z",
"count": "3"
}
]
}
```
# Stats
Some summary statistics:
* [/stats/floodedRegionsSummary](/master-1/routes/stats/floodedregionssummary) : summary of regions containing flooded RWs
* [/stats/floodedRWsSummary](/master-1/routes/stats/floodedrwssummary) : summary of flooded RWs
* [/stats/reportsSummary](/master-1/routes/stats/reportssummary) : summary of reports
# Stats - Reports Summary
Count of reports by source ("qlue" for Qlue, "detik" for Detik Pasangmata, or "grasp" being combined Twitter and Telegram), by default reports will be returned for the last hour.
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | ------------------------------------------------------------------------------------------------- | ------ | -------- |
| city | Which city do we wish to return infrastructure for? (one of `bdg`, `jbd`, `sby`) | String | No |
| timeperiod | What time period (in seconds) to list reports for, must be strictly between 1 and 604800 (1 week) | Number | No |
## GET /stats/getReportsSummary
```
curl "https://data.petabencana.id/stats/reportsSummary?city=jbd"
```
Results are as follows:
```javascript
{
"statusCode": 200,
"result": {
"type": "Topology",
"objects": {
"output": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"properties": {
"pkey": "5519",
"created_at": "2016-12-09T21:37:00.000Z",
"source": "qlue",
"status": "confirmed",
"url": null,
"image_url": "https://lh3.googleusercontent.com/ByClSrW6QhFkBxUhZo0rFt6eiVdvnEHisSzsgjaC9KxdGAQ6CYksTZRA1rcNP9cBGZiv6s4Vp5D8NzkAjPyrBs6c6R4h=s480-c",
"disaster_type": "flood",
"report_data": null,
"tags": {
"instance_region_code": "jbd",
"local_area_id": "350"
},
"title": " ",
"text": "Perlu penataan dan dirapihkan @ahokbtp semoga bisa lbh baik, bersih dan teratur"
},
"coordinates": [
0,
0
]
}
]
}
},
"arcs": [],
"transform": {
"scale": [
1,
1
],
"translate": [
106.817276,
-6.138229
]
},
"bbox": [
106.817276,
-6.138229,
106.817276,
-6.138229
]
}
}
```
# Stats - Flooded RWs Summary
Count of all RWs by flood height range.
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | -------------------------------------------------------------------------------- | ------ | -------- |
| city | Which city do we wish to return infrastructure for? (one of `bdg`, `jbd`, `sby`) | String | No |
## GET /stats/floodedRWsSummary
```
curl "https://data.petabencana.id/stats/floodedRWsSummary?city=jbd"
```
Results are as follows:
```javascript
{
"# hati-hati RWs": 0,
"# 10-70cm RWs": 9,
"# 71-150cm RWs": 0,
"# 151cm+ RWs": 0
}
```
# Stats - Flooded Regions Summary
List of all regions with currently flooded RWs.
## Request Format
| Query Parameter | Description | Format | Required |
| --------------- | -------------------------------------------------------------------------------- | ------ | -------- |
| city | Which city do we wish to return infrastructure for? (one of `bdg`, `jbd`, `sby`) | String | No |
## GET /stats/floodedRegionsSummary
```
curl "https://data.petabencana.id/stats/floodedRegionsSummary?city=jbd"
```
Results are as follows:
```javascript
{
"total number of regions with flooded RWs": 4,
"regions with flooded RWs": [
"KAPUK",
"RAWA TERATE",
"CIPINANG MELAYU",
"CENGKARENG BARAT"
]
}
```
# Authenticated API
The Petabencana Data API provides a number of endpoints for interacting with the system. These are summarised below, full details of the authenticated endpoints together with worked examples can be found in the pages that follow.
## Summary of Endpoints
Details of each endpoint are as follows.
| Endpoint | Description | Methods | Protected |
| ---------------- | ---------------------------- | ------- | --------- |
| /cards | GRASP Cards | GET,PUT | Yes |
| /feeds | Feeds | GET,PUT | Yes |
| /archive/reports | Crowdsourced Archive reports | GET | Yes |
# Cards
Petabencana report cards for disaster events. Note: [authentication](https://docs.petabencana.id/general/authentication.html) is required to make updates to cards.
## Request Format
| URL Parameter | Description | Format | Required |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------- |
| cardId | Unique identifier of the card we wish to work with, this is generated by the system when the initial card is created (required) | String (7 to 14 characters) | Yes |
| Attribute | Description | Format | Required |
| ----------- | ----------------------------------------- | --------------------------------------------------------------------- | -------- |
| card\_data | User data collected in card interface | JSON | Yes |
| text | Description of the disaster event | String | No |
| image\_id | Identifier of the associated card image | String | No |
| created\_at | Date and time the card was created | Date ([ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm)) | Yes |
| location | Geographic location of the disaster event | Lat/Long in [ESPG:4326](http://spatialreference.org/ref/epsg/wgs-84/) | Yes |
### Note on card\_data
Card data requires the object `report_type` to exist. Where `disaster_type` is set to 'flood' then the object `flood_depth` should also exist adjacent to `report_type`. Where the `disaster_type` is 'prep' then `report_type` should be one of the types as specified in server config.js.
| Disaster Type | report\_type | Attribute details |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Flood | flood | flood\_depth: flood severity based on depth in cm
< 70 cm : Minor
70 - 150 cm : Moderate
150 cm : Severe
|
| Earthquake | road | accessabilityFailure: the level of road damage affected by earthquake
0 : < 0,5 m (No Vehicle Access)
1 : 0,6 - 1 m (2-Wheel Vehicle Access)
2 or 3 : 1.1 - 1.8 m (4-Wheel Vehicle Access)
4 : >1,9 m (Large Vehicle Access)
|
| Earthquake | structure | structureFailure: the level of structure damage affected by earthquake
0 : Cracking
1 : Partially Collapse
2 : Fully Collapse
|
| Extreme Wind | wind | impact: level of disruption caused by extreme wind
0 : Low Disruption
1 : Medium Disruption
2 : High Disruption
|
| Haze | haze | visibility: the distance one can see as determined by light and weather conditions
0: can see but need to wear a mask
1: can see but not clean enough to drive
2: can barely see, too dangerous to go out
airQuality: described by symptoms felt by humans
0 or 1: Poor Air Quality
2: Severe Air Quality
3 or 4 : Hazardous Air Quality
|
| Forest Fire | fire | **fireRadius**: the radius of a forest fire estimated by the human eye |
For example a card with flood data including flood\_depth:
```javascript
"disaster_type": "flood",
"card_data":{
"report_type": "flood",
"flood_depth": 50
}
```
Or, a card with pre-flood data report regarding a drain.
```javascript
"disaster_type": "prep",
"card_data":{
"report_type":"drain"
}
```
## GET /cards/:cardId
Retrieve details of a card:
Here is a simple call to GET a card:
```
curl -X GET -H "X-Api-Key: API_KEY_GOES_HERE" "https://data.petabencana.id/cards/abcdefg"
```
The card was found:
```javascript
{
"statusCode": 200,
"result": {
"pkey": "2",
"card_id": "abcdefg",
"username": "user",
"network": "test",
"language": "en",
"received": true,
"report_id": "1"
}
}
```
The card does not exist:
```javascript
{
"statusCode": 404,
"found": false,
"result": null
}
```
## PUT /cards/:cardId
Update a card with details a disaster event report:
Here is a simple call to PUT a card:
```
curl -X PUT -H "X-Api-Key: API_KEY_GOES_HERE" -d '{
"text": "test card",
"disaster_type": "flood"
"card_data":
{
"report_type": "flood",
"flood_depth": 101
},
"created_at":"2016-12-09T11:32:52.011Z",
"location": {
"lat": -6.149531,
"lng": 106.869342
}
}' "https://data.petabencana.id/cards/abcdefg"
```
Card was successfully created:
```javascript
{
"statusCode": 200,
"cardId": "abcdefg",
"created": true
}
```
The card does not exist:
```javascript
{
"statusCode": 404,
"cardId": "abcdefg",
"message": "No card exists with id 'abcdefg'"
}
```
The report already exists for the card:
```javascript
{
"statusCode": 409,
"cardId": "abcdefg",
"message": "Report already received for card 'abcdefg'"
}
```
## GET /cards/:cardId/images
GET a signed S3 URL to upload a card report, this must be done after the card report has been created and only one image can exist for a given card.
NOTE: After an image is submitted a server-side process shrinks the image to a standard size and there may be a small time lag of a few seconds before the image goes "live".
Here is a simple call to GET a new signed S3 URL for image upload:
```
curl -X GET \
https://api-server-dev.riskmap.in/cards/HJID8CWN-/images
```
Signed S3 URL successfully generated:
```javascript
{"signedRequest":"https://riskmap-image-uploads.s3.ap-south-1.amazonaws.com/originals/BJbTHR-Vb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJFMR3NR7BXZ5X7DA%2F20170629%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20170629T012002Z&X-Amz-Expires=900&X-Amz-Signature=ad10a53555205fa18ecfa07da52eb0349ed1c8bda66fe2de0fa9c445c61b7c62&X-Amz-SignedHeaders=host","url":"https://s3.ap-south-1.amazonaws.com/riskmap-image-uploads/originals/BJbTHR-Vb.jpg"}
```
# Feeds
Petabencana utilises data feeds from a number of third party sources. This endpoint allows the creation of data into the system for authorised users. Note: [authentication](https://docs.petabencana.id/general/authentication.html) is required to post data through the /feeds endpoint.
## POST /feeds/qlue
Add a report to the system from [Qlue](http://www.qlue.co.id/). The following attributes are supported for Qlue reports:
| Attribute | Description | Format | Required |
| -------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------- |
| post\_id | Unique qlue identifier for the report | Integer | Yes |
| created\_at | Date and time the card was created | Date ([ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm)) | Yes |
| title | The title of the report being filed | String | No |
| text | Description of the disaster event | String | No |
| image\_url | URL of the associated image | String | No |
| qlue\_city | From which city was the report generated (must be one of `jabodetabek`, `bandung`, `surabaya`) | String | Yes |
| disaster\_type | What type of disaster is being reported (currently only `flood`is supported) | String | Yes |
| location | Geographic location of the disaster event | Lat/Long in [ESPG:4326](http://spatialreference.org/ref/epsg/wgs-84/) | Yes |
Here is a simple call to POST a new Qlue report:
```
curl -X POST -H "X-Api-Key: API_KEY_GOES_HERE" -d '{
"post_id":1234567802,
"created_at":"2016-12-09T11:32:52.011Z",
"image_url":"http://myimg",
"qlue_city":"jabodetabek",
"disaster_type":"flood",
"text":"A big flood",
"location": {
"lat": -6.149531,
"lng": 106.869342
}
}' "https://data.petabencana.id/feeds/qlue"
```
Report was successfully created:
```javascript
{
"post_id": 1234567802,
"created": true
}
```
The request was successful however the report already exists:
```javascript
{
"post_id": 1234567802,
"created": false,
"message": "1234567802 already exists in reports table"
}
```