+ +

GET /api/v1 / HTTP/1.1 / 200 OK▮

YSS Location
API.

Data wilayah Indonesia dari BPS untuk dropdown berantai di aplikasi YSS. Pilih provinsi, kabupaten/kota muncul. Pilih kabupaten, kecamatan muncul. Tiap wilayah dibekali dua standar kode dan nama sekaligus: BPS dan Kemendagri, jadi aplikasi Dapodik bebas pakai yang mana.

Coba Live Demo Lihat Endpoint

Provinsi

514

Kabupaten / Kota

7.291

Kecamatan

01Overview

Base URL dan bentuk response

Semua endpoint tersimpan di bawah prefix berikut. Ganti host dengan alamat tempat API ini di-deploy.

Base URL

http://localhost:8080/api/v1

Semua response memakai envelope yang sama, baik sukses maupun gagal:

Response envelope

{ "status": "ok", "data": [ ... ] }
{ "status": "error", "message": "..." }

Kode wilayah di semua endpoint bisa memakai kode_bps atau kode_dagri, keduanya diterima. Karena di level provinsi kedua sistem kebetulan memakai kode 2 digit yang bisa kembar (contoh: 95 di BPS berarti Papua Selatan, sedangkan di Kemendagri berarti Papua Pegunungan), pencocokan default mengutamakan kode_bps. Kalau kode yang dipakai dari Kemendagri, tambahkan ?by=dagri (atau ?by=bps untuk memaksa BPS) supaya hasilnya tidak ambigu. Data bersifat statis sehingga response aman di-cache harian.

02Authentication

Token akses

Semua endpoint /api/v1/* wajib menyertakan token lewat salah satu dari dua header berikut (cukup pakai salah satu):

Request header

X-API-Key: <token>
Authorization: Bearer <token>

Token dikeluarkan oleh admin YSS. Tiap aplikasi boleh memakai token masing-masing, jadi saat perlu rotate tinggal ganti satu aplikasi tanpa mengganggu yang lain. Tanpa token yang valid, request dibalas 401.

03Endpoints

Empat endpoint, alur dropdown sampai search

Tiga endpoint pertama dipakai berantai mengikuti pilihan user, endpoint terakhir untuk kotak pencarian lintas level.

GET /api/v1/provinces public / cached

Semua provinsi di Indonesia (38). Biasanya dipakai untuk mengisi dropdown level pertama.

Request

curl -H "X-API-Key: <token>" \
  http://localhost:8080/api/v1/provinces

Response 200

{
  "status": "ok",
  "data": [
    {
      "kode_bps": "11",
      "nama_bps": "ACEH",
      "kode_dagri": "11",
      "nama_dagri": "ACEH"
    },
    {
      "kode_bps": "12",
      "nama_bps": "SUMATERA UTARA",
      "kode_dagri": "12",
      "nama_dagri": "SUMATERA UTARA"
    }
  ]
}

GET /api/v1/provinces/{code}/regencies public / cached

Kabupaten/kota di dalam satu provinsi. Dipanggil saat user memilih provinsi.

Param	Tipe		Keterangan
`code`	path	Wajib	Kode provinsi: `kode_bps` atau `kode_dagri`
`by`	query	Opsional	Maksa sumber kode: `bps` atau `dagri`. Default mengutamakan `kode_bps`

Request

curl -H "X-API-Key: <token>" \
  http://localhost:8080/api/v1/provinces/11/regencies

Response 200

{
  "status": "ok",
  "data": [
    {
      "kode_bps": "1101",
      "nama_bps": "SIMEULUE",
      "kode_dagri": "11.09",
      "nama_dagri": "KAB. SIMEULUE"
    }
  ]
}

GET /api/v1/regencies/{code}/districts public / cached

Kecamatan di dalam satu kabupaten/kota. Dipanggil saat user memilih kabupaten/kota.

Param	Tipe		Keterangan
`code`	path	Wajib	Kode kabupaten/kota: `kode_bps` atau `kode_dagri`
`by`	query	Opsional	Maksa sumber kode: `bps` atau `dagri`. Default mengutamakan `kode_bps`

Request

curl -H "X-API-Key: <token>" \
  http://localhost:8080/api/v1/regencies/1101/districts

Response 200

{
  "status": "ok",
  "data": [
    {
      "kode_bps": "1101010",
      "nama_bps": "TEUPAH SELATAN",
      "kode_dagri": "11.09.07",
      "nama_dagri": "TEUPAH SELATAN"
    }
  ]
}

GET /api/v1/search?q={query}&limit={n} public / cached

Cari wilayah lintas level berdasarkan nama atau awalan kode. Cocok untuk kotak pencarian; hasil yang diawali kata kunci diurutkan paling atas.

Param	Tipe		Keterangan
`q`	query	Wajib	Kata kunci minimal 1 karakter, contoh: `simeulue`
`limit`	query	Opsional	Jumlah hasil maksimal. Default `20`, maksimal `100`

Beda dengan endpoint dropdown, tiap hasil search menyertakan field level plus kode induknya (kode_provinsi, kode_kabupaten) supaya aplikasi langsung tahu posisinya di hierarki:

GET /api/v1/search?q=singkil&limit=5

{
  "status": "ok",
  "data": [
    {
      "kode_bps": "1102",
      "nama_bps": "ACEH SINGKIL",
      "kode_dagri": "11.10",
      "nama_dagri": "KAB. ACEH SINGKIL",
      "level": "kabupaten/kota",
      "kode_provinsi": "11"
    },
    {
      "kode_bps": "1102020",
      "nama_bps": "SINGKIL",
      "kode_dagri": "11.10.04",
      "nama_dagri": "SINGKIL",
      "level": "kecamatan",
      "kode_provinsi": "11",
      "kode_kabupaten": "1102"
    }
  ]
}

04Live Demo

Coba alur dropdown berantai

Isi token dulu, lalu ketik untuk mencari di tiap kolom. Setiap pilihan langsung memanggil endpoint yang sama seperti dipakai aplikasi, dan hasil mentahnya tampil di panel bawah.

demo.dropdown / interactive client-side

API Token

Provinsi

Kabupaten / Kota

Kecamatan

activity.log ▮ idle

Menunggu interaksi pertama...

Response akan tampil di sini.

05Errors

Penanganan error

Semua error memakai envelope yang sama, ditambah field message:

Response 401

{ "status": "error", "message": "token tidak valid" }

daftar status code reference

Status	Arti	Penyebab
`400`	Bad Request	Parameter `q` kosong atau `limit` bukan angka
`401`	Unauthorized	Token tidak ada atau tidak valid
`404`	Not Found	Kode provinsi atau kabupaten/kota tidak dikenal

YSS LocationAPI.

Base URL dan bentuk response

Token akses

Empat endpoint, alur dropdown sampai search

Coba alur dropdown berantai

Penanganan error

YSS Location
API.