Ditinjau oleh Kalau kamu sedang membangun form alamat, checkout, atau sistem logistik, kamu butuh data kode pos Indonesia yang lengkap dan selalu akurat. Cara paling praktis untuk itu bukan lagi file Excel atau hasil scraping, tapi lewat api kode pos indonesia yang bisa kamu query langsung dari aplikasi.
Masalah data kode pos manual (Excel, hardcode, scraping)
Banyak tim developer mulai dengan cara paling sederhana: unduh data kode pos dari internet, taruh di spreadsheet, lalu hardcode ke aplikasi. Cara ini kelihatan cepat di awal, tapi punya dua masalah yang baru terasa setelah aplikasi jalan beberapa bulan.
Pertama, data kode pos gampang basi. Pemekaran wilayah, perubahan batas kecamatan, atau penyesuaian kode administratif terjadi terus di Indonesia. File Excel yang kamu unduh hari ini bisa saja sudah tidak akurat enam bulan kemudian, dan tidak ada yang mengingatkanmu untuk memperbaruinya.
Kedua, data statis sulit dipelihara untuk aplikasi yang terus tumbuh. Setiap kali ada perubahan wilayah, kamu harus cari sumber data baru, bersihkan formatnya, lalu deploy ulang. Untuk form alamat checkout, sistem logistik, atau database pelanggan yang butuh validasi kode pos, proses manual seperti ini jadi beban operasional yang berulang.
Kenapa pakai API untuk data kode pos, bukan file statis
Dengan API, data kode pos selalu ter-update tanpa kamu perlu maintenance manual. Kamu tidak perlu menyimpan database wilayah sendiri, tidak perlu jadwal pembaruan, dan tidak perlu khawatir data yang kamu pakai sudah kedaluwarsa. Kamu tinggal query langsung dari aplikasi setiap kali butuh, dan hasilnya konsisten dengan sumber data terbaru.
Pola ini juga mengurangi beban infrastruktur. Alih-alih menyimpan puluhan ribu baris data wilayah di server sendiri, kamu cukup memanggil endpoint saat dibutuhkan, misalnya saat pengguna mengisi form alamat atau saat sistem logistik memvalidasi tujuan pengiriman.
Cara dapat API key
Untuk mulai pakai api kode pos indonesia dari api.co.id, kamu daftar akun di dashboard api.co.id dan ambil API key. Setiap request wajib menyertakan API key ini lewat header x-api-co-id, tanpa header ini permintaanmu akan ditolak dengan status 401 Unauthorized. Detail tier dan kuota bisa kamu cek di halaman pricing, karena skema harga bisa berubah sewaktu-waktu.
Ada dua jalur akses yang perlu kamu bedakan sejak awal. Kalau kamu hanya butuh mencocokkan kode pos ke data kelurahan/kecamatan satu per satu, endpoint non-premium villages sudah cukup dan gratis kamu pakai dengan API key biasa. Tapi kalau kamu butuh menarik seluruh dataset kode pos sekaligus untuk disimpan di sistemmu sendiri, kamu perlu upgrade ke subscription premium dulu lewat halaman pricing.
Contoh request ambil data kode pos
API Wilayah Indonesia dari api.co.id memakai base URL https://use.api.co.id, dan semua endpoint di bawah menyertakan prefix /regional/indonesia. Autentikasi wajib lewat header x-api-co-id berisi API key kamu.
Endpoint utama untuk dataset kode pos lengkap adalah GET /regional/indonesia/postal-codes. Endpoint ini termasuk premium, jadi butuh subscription premium untuk mengaksesnya. Kalau kamu belum premium, tetap ada jalan non-premium: GET /regional/indonesia/villages dengan query param postal_code bisa kamu pakai untuk memfilter data kelurahan/desa berdasarkan kode pos tertentu, tanpa perlu subscription premium.
Contoh request pakai cURL, mengambil kode pos berdasarkan kode desa:
curl -X GET "https://use.api.co.id/regional/indonesia/postal-codes?village_code=3273010001" \
-H "x-api-co-id: API_KEY_KAMU"Contoh yang sama dalam Node.js:
const res = await fetch(
"https://use.api.co.id/regional/indonesia/postal-codes?village_code=3273010001",
{ headers: { "x-api-co-id": "API_KEY_KAMU" } }
);
const result = await res.json();
console.log(result.data);Kalau kamu justru punya kode pos dan mau tahu wilayah mana saja yang tercakup di dalamnya, pakai reverse lookup GET /regional/indonesia/postal-codes/{postal_code}. Endpoint ini juga premium, dan mengembalikan daftar desa/kelurahan yang berada di kode pos tersebut.
Contoh response JSON data kode pos
Semua endpoint (kecuali Search) memakai format response yang sama: is_success, message, data, dan paging. Untuk endpoint postal-codes, setiap item di data berisi field id, postal_code, village_code, village, district_code, district, regency_code, regency, province_code, dan province.
{
"is_success": true,
"message": "Success",
"data": [
{
"id": 1,
"postal_code": "40115",
"village_code": "3273010001",
"village": "Cihapit",
"district_code": "327301",
"district": "Bandung Wetan",
"regency_code": "3273",
"regency": "Kota Bandung",
"province_code": "32",
"province": "Jawa Barat"
}
],
"paging": { "page": 1, "size": 100, "total_item": 87657, "total_page": 877 }
}Perhatikan bahwa hasilnya dipaginasi 100 item per halaman, jadi kalau kamu butuh dataset kode pos lengkap sebanyak 87.657 record itu, kamu perlu menaikkan parameter page secara berurutan sampai seluruh 877 halaman terambil, atau menjadwalkan proses tarik data secara berkala di sisi sistemmu. Kalau lewat endpoint non-premium villages, bentuk field-nya sedikit berbeda: code, name, district_code, district, regency_code, regency, province_code, province, postal_codes (array), dan is_courier_support yang menandai apakah wilayah itu terjangkau kurir.
Cakupan data kode pos se-Indonesia
Data kode pos ini terhubung ke hierarki wilayah administratif lengkap, mulai dari 34 provinsi, 514 kota/kabupaten, 7.213 kecamatan, sampai 83.916 kelurahan/desa. Dari situ, data kode pos yang tercatat mencapai 87.657 record. Artinya kamu tidak hanya dapat satu kode pos per kelurahan, karena satu wilayah bisa punya lebih dari satu kode pos tergantung pembagian area layanan pos di lapangan.
Endpoint provinsi, kota/kabupaten, kecamatan, dan kelurahan sifatnya standar, tidak butuh premium. Yang butuh subscription premium khusus dataset kode pos (list lengkap dan reverse lookup) serta fitur pencarian lintas wilayah.
Use case integrasi data kode pos
Ada beberapa skenario umum yang biasa dipakai tim developer untuk data kode pos lewat API:
- Form alamat checkout e-commerce, kode pos otomatis terisi begitu pengguna memilih kelurahan atau kecamatan tujuan.
- Sistem logistik dan pengiriman yang perlu memvalidasi kode pos tujuan sebelum menghitung ongkos kirim atau area layanan kurir.
- Database pelanggan yang butuh standarisasi alamat, supaya data yang masuk konsisten formatnya dan gampang dicocokkan dengan wilayah administratif resmi.
Data kode pos manual vs API, pembanding singkat
Kalau kamu bandingkan jujur, mengelola data kode pos sendiri lewat file Excel atau hasil scraping berarti kamu yang menanggung beban memperbarui, memvalidasi, dan menyimpan datanya. Dengan API, data itu terus diperbarui di sisi penyedia, dan kamu cukup query saat butuh tanpa perlu simpan dan rawat data sendiri.
Kalau kamu masih membandingkan beberapa penyedia API wilayah secara umum, bukan cuma untuk kode pos, kamu bisa cek pembanding penyedia API wilayah Indonesia lainnya sebagai bacaan lanjutan.
Mulai pakai data kode pos lewat API
Data kode pos yang akurat dan selalu terbarui jadi fondasi penting untuk form alamat, checkout, dan sistem logistik yang andal. Daripada bergantung pada file statis yang butuh pembaruan manual, kamu bisa ambil data kode pos langsung lewat API Wilayah Indonesia dari api.co.id, yang sudah dipakai sebagai bagian dari platform yang melayani 7.000+ pengguna dengan uptime 99,9% dan memproses lebih dari 5.000.000 API call.
Coba Regional API gratis dan ambil data kode pos pertamamu dalam hitungan menit.
