Dokumentasi API

Pengantar

API ini menyajikan data yang sudah diinput di halaman admin SIMPANDU dan sudah disahkan: penilaian State of the Coast (SOC), dokumen ICM Plan, dan progres triwulan ICM. Bentuknya JSON, hanya dapat dibaca (metode GET, HEAD, dan OPTIONS), dan seluruh titik akhirnya berada di bawah /api/v1.

Hanya dokumen berstatus Terpublikasi yang tampil, yaitu data yang memang sudah tayang di situs publik. Draf, dokumen yang masih diajukan atau diverifikasi, dan dokumen yang diarsipkan tidak pernah muncul. Tidak ada data pribadi: tanpa surel, nama pengguna, pelapor, kontak, atau peran.

Setiap respons sukses berbentuk {"metadata": {...}, "data": ...}, ditambah meta dan links pada daftar. Kunci JSON berbahasa Indonesia snake_case. Angka skor mentah dibulatkan dua desimal, persen satu desimal, dan nilai yang tidak ada bernilai null (bukan 0).

Autentikasi

Tidak ada. API terbuka tanpa kunci, token, maupun cookie. Cukup kirim permintaan GET.

Batas laju

Setiap alamat IP dibatasi 60 permintaan per menit. Setiap respons membawa header X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset (detik epoch). Bila terlampaui, API menjawab status 429 dengan header Retry-After (detik) dan galat terlalu_banyak_permintaan.

Respons sukses membawa Cache-Control: public, max-age=300 dan ETag. Kirim ETag itu pada If-None-Match untuk mendapat 304 tanpa isi bila data belum berubah. Simpan hasil di sisi Anda alih-alih menarik berulang.

Paginasi

Daftar dokumen (/soc, /icm-plan, /icm-progres) berpaginasi dengan parameter halaman (mulai 1) dan per_halaman (bawaan 25, maksimum 100). Blok meta memuat halaman, per_halaman, total, dan jumlah_halaman. Blok links memuat self, first, last, prev, dan next (null bila tidak ada). Ikuti next sampai null.

Kode galat

Galat selalu JSON: {"galat": {"kode": "...", "pesan": "..."}}.

Titik akhir

Semua titik akhir memakai metode GET. Jalur relatif terhadap https://simpandu.liveapp.web.id/api/v1.

GET /

Penemuan. Nama, versi, daftar titik akhir, lisensi, kontak, dan tautan dokumentasi.

GET /openapi.json

Spesifikasi OpenAPI. Berkas spesifikasi OpenAPI 3.1 untuk API ini.

GET /wilayah

Daftar wilayah. Provinsi, kabupaten, dan kota, urut tampil.

GET /wilayah/{kode_bps}

Detail wilayah. Satu wilayah menurut kode BPS, beserta tautan ke data wilayah itu.

GET /instrumen/soc

Struktur instrumen SOC. Aspek, elemen, indikator, dan parameter instrumen penilaian pada satu tahun, beserta bobot menurut tahun itu.

GET /soc

Daftar dokumen SOC. Dokumen SOC terpublikasi (versi tertinggi per wilayah dan tahun) beserta skor ringkas. Urut tahun menurun lalu wilayah.

GET /soc/{kode_bps}/{tahun}

Detail dokumen SOC. Skor per aspek, elemen, dan parameter, metadata dokumen, serta tautan halaman publik.

GET /skor-wilayah

Skor wilayah. Skor ringkas tiap wilayah pesisir dan rekap provinsi pada satu tahun, identik dengan dasbor publik.

GET /icm-plan

Daftar ICM Plan. Dokumen ICM Plan terpublikasi (versi tertinggi per wilayah dan tahun) beserta metadata yang aman.

GET /icm-plan/{kode_bps}/{tahun}

Detail ICM Plan. Satu dokumen ICM Plan terpublikasi, tanpa tautan berkas unduhan.

GET /icm-progres

Progres triwulan ICM. Capaian triwulan wilayah pesisir. Status memakai ambang progres 70 dan 55.

Contoh penggunaan

Detail satu wilayah

curl -s https://simpandu.liveapp.web.id/api/v1/wilayah/33.74

{
  "metadata": {"versi": "v1", "waktu": "2026-10-28T09:00:00+07:00", "lisensi": "...", "sumber": "SIMPANDU Provinsi Jawa Tengah"},
  "data": {
    "kode_bps": "33.74", "nama": "Kota Semarang", "tingkat": "kota", "pesisir": true,
    "lintang": -6.9667, "bujur": 110.4167, "urutan": 9,
    "tautan": {"soc": ".../api/v1/soc?kode_bps=33.74", "icm_plan": "...", "icm_progres": "..."}
  }
}

Skor satu dokumen SOC

curl -s https://simpandu.liveapp.web.id/api/v1/soc/33.74/2025

{
  "metadata": {"versi": "v1", "waktu": "...", "lisensi": "...", "sumber": "SIMPANDU Provinsi Jawa Tengah"},
  "data": {
    "wilayah": {"kode_bps": "33.74", "nama": "Kota Semarang", "tingkat": "kota"},
    "tahun": 2025, "versi": 1, "tanggal_terbit": "2025-12-19",
    "skor": {
      "tata_kelola": {"skor_mentah": 61.11, "skor_maksimum": 100, "persen": 61.1, "status": "sedang", "status_label": "Sedang", "parameter_terisi": 23, "parameter_total": 23},
      "pembangunan": {"skor_mentah": 61.5, "skor_maksimum": 100, "persen": 61.5, "status": "sedang", "status_label": "Sedang", "parameter_terisi": 52, "parameter_total": 52},
      "overall": {"skor_mentah": 122.61, "skor_maksimum": 200, "persen": 61.3, "status": "sedang", "status_label": "Sedang", "parameter_terisi": 75, "parameter_total": 75}
    },
    "elemen": [{"kode": "A.I", "nama": "Kebijakan, strategi dan rencana", "skor_mentah": 12.5, "skor_maksimum": 16.67,
      "parameter": [{"kode": "A.I.1", "nama": "...", "bobot": 2.083333, "skor": 0, "label": "Tidak Ada", "nilai_akhir": 0}]}]
  }
}

Skor overall adalah jumlah Tata Kelola dan Pembangunan (maksimum 200), bukan rerata. Persen adalah skor dibagi maksimum dikali 100.

Menelusuri daftar dengan paginasi

curl -s "https://simpandu.liveapp.web.id/api/v1/soc?tahun=2025&per_halaman=10&halaman=2"

Memakai ETag

curl -si https://simpandu.liveapp.web.id/api/v1/skor-wilayah | grep -i etag
curl -si -H 'If-None-Match: "ETAG-DARI-ATAS"' https://simpandu.liveapp.web.id/api/v1/skor-wilayah | head -1
# HTTP/2 304

Dari JavaScript

const r = await fetch('https://simpandu.liveapp.web.id/api/v1/skor-wilayah?tahun=2025');
const {data} = await r.json();
console.log(data.provinsi.persen_total);

Lisensi dan penggunaan wajar

Data terbuka. Cantumkan "SIMPANDU Provinsi Jawa Tengah" sebagai sumber. Lisensi formal menunggu penetapan pemilik data.

• Cantumkan sumber data dan tanggal pengambilan pada tampilan Anda.
• Simpan hasil (cache) dan gunakan ETag; jangan menarik data yang sama berulang dalam hitungan detik.
• Tetap di bawah batas laju. Untuk kebutuhan lebih besar, hubungi kami lebih dulu.
• Skor adalah hasil penilaian pada tanggal terbit dokumen. Dokumen baru dapat menggantikan versi lama.