01 / RINGKAS

Data Indonesia, BMKG & Utilitas, dipanggil lewat HTTP, dibayar per respons.

Empat belas endpoint. Kunci API tunggal. Tarif Rp1,5 untuk setiap panggilan yang berhasil. Panggilan yang gagal tidak dipotong.

Buat kunci API Lihat contoh panggilan

Katalog layanan aktif
Wilayah (Provinsi & Kab)	38 prov / 514 kab
Kalender Libur SKB 3 Menteri	2025 & 2026
BMKG Gempa Terkini Realtime	M 5.0+ & Dirasakan
Utilitas Indonesia	HP, NIK, NPWP
Endpoint berbayar	14
Tarif per panggilan	Rp1,5

02 / PRODUK

Produk dan harga

Harga sama untuk semua endpoint. Tidak ada biaya minimum bulanan, tidak ada biaya aktivasi.

Endpoint	Isi	Parameter	Harga
GET /v1/wilayah/provinsi	Seluruh provinsi, kode BPS dan nama	-	Rp1,5
GET /v1/wilayah/kabupaten	Kabupaten/kota dalam satu provinsi	province	Rp1,5
GET /v1/kalender/hari-libur	Libur nasional & cuti bersama SKB 3 Menteri	year	Rp1,5
GET /v1/bmkg/gempa-terkini	Gempa realtime M 5.0+ resmi BMKG	-	Rp1,5
GET /v1/bmkg/gempa-dirasakan	Daftar 15 gempa dirasakan terbaru BMKG	-	Rp1,5
GET /v1/utility/phone-parse	Normalisasi nomor HP, E.164, dan operator seluler	phone	Rp1,5
GET /v1/utility/nik-parse	Ekstraksi wilayah & tanggal lahir dari NIK KTP	nik	Rp1,5
GET /v1/utility/npwp-validate	Validasi format & cek 15/16 digit NPWP Indonesia	npwp	Rp1,5
GET /v1/bank/daftar	Daftar 139 bank dan 7 e-wallet Indonesia dengan kode BI	type, q, limit	Rp1,5
GET /v1/bank/validate	Validasi bentuk nomor rekening sesuai panjang digit tiap bank	bank, account	Rp1,5
GET /v1/bank/cek-nama	Nama pemilik rekening atau e-wallet	bank, account	Rp300
GET /v1/wilayah/kecamatan	Daftar kecamatan per kabupaten/kota, 7.285 baris	regency	Rp1,5
GET /v1/bmkg/cuaca	Prakiraan cuaca BMKG per desa/kelurahan, cache 10 menit	adm4	Rp1,5
GET /v1/kurs/harian	Kurs referensi pasar terhadap Rupiah, cache 1 jam	base	Rp1,5
GET /v1/products	Katalog endpoint dan harga berlaku	-	gratis

Katalog gratis ini juga bisa dipakai memantau umur data lewat meta.data_age_seconds pada respons berbayar.

03 / CARA PANGGIL

Satu header, satu URL

Kunci dikirim sebagai Authorization: Bearer. Header X-API-Key juga diterima.

curl -sS https://api.toolkuy.com/v1/wilayah/kabupaten?province=12 \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxx"

Respons di bawah dipotong. Isi aslinya memuat seluruh kabupaten/kota provinsi tersebut.

{
  "data": [
    { "code": "12.01", "province_code": "12", "name": "Kabupaten Tapanuli Tengah" },
    { "code": "12.71", "province_code": "12", "name": "Kota Medan" }
  ],
  "meta": {
    "product": "wilayah.kabupaten",
    "rows": 33,
    "cost_rupiah": 1.5,
    "charged_rupiah": 1.5,
    "balance_rupiah": 998.5,
    "quota": { "limit_minute": 60, "limit_day": 500,
               "minute_remaining": 59, "day_remaining": 499 },
    "data_age_seconds": 3600,
    "source": "wilayah.id",
    "request_id": "6f0c1b1e-2b7a-4a0f-9a52-0f5a1c9d7e11"
  }
}

Yang dibaca mesin

X-Request-Id untuk menelusuri satu panggilan
X-Credits-Charged jumlah yang benar-benar dipotong
X-Balance-Milli saldo dalam satuan mili-rupiah
X-Quota-Remaining-Minute dan -Day
X-Data-Age umur dataset dalam detik

Kuota bawaan

60 panggilan per menit dan 500 per hari untuk setiap kunci. Batas ini per kunci, bukan per akun, jadi beban satu layanan tidak memotong jatah layanan lain.

Sifat idempoten

Kirim X-Request-Id yang sama untuk mengulang panggilan tanpa debit kedua. Balasan kedua ditandai meta.replayed: true.

04 / BIAYA

Hanya respons 200 yang dipotong

Urutan gerbang di server: kunci, produk, kuota, saldo, data, baru debit. Kesalahan pada empat gerbang pertama tidak menyentuh saldo. Debit terjadi setelah data siap, sehingga kegagalan penyusunan data pun tidak dibebankan.

Rp1,5per respons 200

Rp0per respons galat

60panggilan per menit

500panggilan per hari

Saldo disimpan dalam mili-rupiah agar tidak ada pembulatan yang hilang. Setiap debit tercatat di ledger dengan indeks unik per request id.

05 / KODE GALAT

Galat selalu berbentuk sama

Setiap kegagalan mengembalikan {"error":{"code":"...","message":"..."}} dengan kode HTTP yang sesuai. Pesannya berbahasa Indonesia dan menyebut langkah perbaikannya.

HTTP	code	Artinya	Yang harus dilakukan	Debit
400	invalid_parameter	Parameter wajib kosong atau tidak dikenal	Isi `province` dengan kode dua digit	tidak
401	missing_api_key	Header Authorization tidak ada	Kirim Bearer token	tidak
401	invalid_api_key	Kunci tidak dikenal atau sudah dirotasi	Pakai kunci aktif dari member area	tidak
402	insufficient_credits	Saldo kurang dari tarif	Top-up belum dibuka, hubungi pengelola	tidak
404	product_not_found	Path tidak ada di katalog	Baca `GET /v1/products`	tidak
405	method_not_allowed	Bukan GET atau HEAD	Ganti metode	tidak
429	quota_minute_exceeded	Lewat 60 panggilan per menit	Tunggu sesuai header `Retry-After`	tidak
429	quota_day_exceeded	Lewat 500 panggilan per hari	Tunggu pergantian hari, atau pakai kunci lain	tidak
500	internal_error	Data gagal disusun di server	Kirim request id ke pengelola	tidak

06 / MULAI

Buat akun, ambil kunci, panggil

Pendaftaran hanya butuh email dan password. Kunci pertama dibuat dari member area, ditampilkan satu kali, lalu hanya tersimpan sebagai hash di server. Kalau kunci hilang, buat kunci baru dan kunci lama langsung mati.

Kredit awal diberikan sebagai percobaan. Top-up otomatis belum dibuka, jadi penambahan saldo masih manual oleh pengelola.

Sudah punya akun?

Daftar Masuk