Nusantara API

🗺️ Library ringan untuk data wilayah Indonesia - Provinsi, Kabupaten, Kecamatan, Kelurahan/Desa

Data sesuai Kepmendagri No 300.2.2-2138 Tahun 2025 dengan 91,162 wilayah terupdate.

---

📦 Instalasi

Via NPM (Untuk Node.js)

npm install nusantara-api

Via CDN (Untuk Browser/Frontend)

Tidak perlu instalasi! Langsung fetch data dari CDN.

👉 Lihat dokumentasi CDN lengkap

const CDN = 'https://cdn.jsdelivr.net/gh/ibnushahraa/nusantara-api@cdn/data'

// Fetch provinsi (~885 bytes)
const provinces = await fetch(`${CDN}/provinces/index.json`).then(r => r.json())
// Returns: [["11","Aceh"], ["12","Sumatera Utara"], ...]

Keunggulan CDN:

• ✅ Tidak perlu install npm package
• ✅ Ukuran file sangat kecil (76% lebih kecil)
• ✅ Lazy loading - hanya load yang dibutuhkan
• ✅ Global CDN - cepat di seluruh dunia

🚀 Cara Pakai

Penggunaan Dasar (CommonJS)

const WilayahIndonesia = require('nusantara-api');

// Inisialisasi
const wilayah = new WilayahIndonesia();

// Cari berdasarkan kode
const aceh = wilayah.findById('11');
console.log(aceh);
// Output: { kode: '11', nama: 'Aceh' }

// Ambil nama saja
const nama = wilayah.getName('31.71');
console.log(nama);
// Output: "Kota Jakarta Pusat"

// Autocomplete / Pencarian
const hasil = wilayah.autocomplete('jakarta', 5);
console.log(hasil);
// Output: [
//   { kode: '31.71', nama: 'Kota Jakarta Pusat' },
//   { kode: '31.72', nama: 'Kota Jakarta Utara' },
//   ...
// ]

Penggunaan dengan ES Module

import WilayahIndonesia from 'nusantara-api';

const wilayah = new WilayahIndonesia();
const jakarta = wilayah.findById('31');

Penggunaan dengan TypeScript

import WilayahIndonesia, { Wilayah } from 'nusantara-api';

const wilayah = new WilayahIndonesia();
const result: Wilayah | null = wilayah.findById('11');

---

🎯 Fitur Lengkap

1️⃣ Cari Wilayah

// Cari berdasarkan kode
wilayah.findById('11');           // { kode: '11', nama: 'Aceh' }
wilayah.findById('31.71');        // { kode: '31.71', nama: 'Kota Jakarta Pusat' }

// Ambil nama saja
wilayah.getName('11');            // "Aceh"

2️⃣ Autocomplete & Pencarian

// Cari wilayah dengan nama
wilayah.autocomplete('jakarta', 5);
wilayah.autocomplete('bandung', 10);

// Pencarian dengan cache (lebih cepat)
wilayah.search('surabaya', 5);

3️⃣ Ambil Data Berdasarkan Level

// Semua provinsi
const provinsi = wilayah.getProvinces();
console.log(provinsi.length); // 38 provinsi

// Semua kabupaten di Aceh
const kabupaten = wilayah.getKabupaten('11');

// Semua kecamatan di Kabupaten Aceh Selatan
const kecamatan = wilayah.getKecamatan('11.01');

// Semua kelurahan di Kecamatan Bakongan
const kelurahan = wilayah.getKelurahan('11.01.01');

4️⃣ Navigasi Hierarki

// Ambil anak langsung dari suatu wilayah
const children = wilayah.getChildren('11');
// Returns: Semua kabupaten di Aceh

// Ambil berdasarkan level
// Level 1 = Provinsi
// Level 2 = Kabupaten/Kota
// Level 3 = Kecamatan
// Level 4 = Kelurahan/Desa
const allKabupaten = wilayah.getByLevel(2);

5️⃣ Statistik

const stats = wilayah.getStats();
console.log(stats);
// Output:
// {
//   total: 91162,
//   provinsi: 38,
//   kabupaten: 514,
//   kecamatan: 7255,
//   kelurahan: 83355
// }

---

📋 Daftar Method

Method	Kegunaan	Contoh
findById(kode)	Cari wilayah berdasarkan kode	findById('11')
getName(kode)	Ambil nama wilayah	getName('31.71')
autocomplete(query, limit)	Pencarian otomatis	autocomplete('jakarta', 5)
search(query, limit)	Pencarian dengan cache	search('bandung', 10)
getProvinces()	Ambil semua provinsi	getProvinces()
getKabupaten(kodeProvinsi)	Ambil kabupaten di provinsi	getKabupaten('11')
getKecamatan(kodeKabupaten)	Ambil kecamatan di kabupaten	getKecamatan('11.01')
getKelurahan(kodeKecamatan)	Ambil kelurahan di kecamatan	getKelurahan('11.01.01')
getChildren(kode)	Ambil wilayah anak langsung	getChildren('11')
getByLevel(level)	Ambil berdasarkan level (1-4)	getByLevel(2)
getStats()	Ambil statistik	getStats()
clearCache()	Bersihkan cache pencarian	clearCache()

---

💡 Contoh Penggunaan

Dropdown Bertingkat (Cascading)

// User pilih provinsi
const provinsiKode = '11'; // Aceh
const daftarKabupaten = wilayah.getKabupaten(provinsiKode);

// User pilih kabupaten
const kabupatenKode = '11.01';
const daftarKecamatan = wilayah.getKecamatan(kabupatenKode);

// User pilih kecamatan
const kecamatanKode = '11.01.01';
const daftarKelurahan = wilayah.getKelurahan(kecamatanKode);

Validasi Kode Wilayah

function validasiKode(kode) {
    const wilayahData = wilayah.findById(kode);
    return wilayahData !== null;
}

console.log(validasiKode('11'));      // true
console.log(validasiKode('99.99'));   // false

Tampilkan Alamat Lengkap

function alamatLengkap(kode) {
    const bagian = kode.split('.');
    const alamat = [];

    for (let i = 1; i <= bagian.length; i++) {
        const kodeSebagian = bagian.slice(0, i).join('.');
        const nama = wilayah.getName(kodeSebagian);
        if (nama) alamat.push(nama);
    }

    return alamat.join(', ');
}

console.log(alamatLengkap('11.01.01.2001'));
// Output: "Keude Bakongan, Bakongan, Kabupaten Aceh Selatan, Aceh"

---

🛠️ Contoh Integrasi

Express.js API

Lihat file lengkap di examples/express-api.js

const express = require('express');
const WilayahIndonesia = require('nusantara-api');

const app = express();
const wilayah = new WilayahIndonesia();

app.get('/provinces', (req, res) => {
    const provinces = wilayah.getProvinces();
    res.json({ data: provinces });
});

app.get('/search', (req, res) => {
    const { q, limit = 10 } = req.query;
    const results = wilayah.search(q, parseInt(limit));
    res.json({ data: results });
});

app.listen(3000);

---

⚡ Performa

• Ukuran: Hanya 420 KB (terkompresi brotli)
• Data: 91,162 wilayah lengkap
• Kecepatan:
  • Cari by ID: O(1) - instan
  • Autocomplete: O(n) dengan early termination
  • Search (cached): O(1) setelah pencarian pertama
• Memory: ~420 KB compressed → ~2.5 MB saat di-load
• Load time: ~100-200ms (otomatis decompress)

---

✨ Keunggulan

✅ Lengkap - Data terbaru sesuai Kepmendagri 2025 dengan 91K+ wilayah

✅ Ringan - Hanya 420 KB (brotli compressed)

✅ Cepat - Pencarian O(1) untuk find by ID

✅ Modern - Support CommonJS, ES Module, TypeScript

✅ Mudah - API sederhana dan jelas

✅ Fleksibel - Bisa untuk Node.js, Express, NestJS, Fastify, dll

✅ No Dependencies - Pure Node.js built-in modules

✅ Teruji - 68 unit tests dengan coverage 80%

---

📚 Dokumentasi Lengkap

• Contoh Penggunaan
• CHANGELOG
• TypeScript Definitions

---

🤝 Kontribusi

Kontribusi sangat diterima! Silakan buat issue atau pull request.

---

📝 Lisensi

MIT License - Bebas digunakan untuk proyek pribadi maupun komersial.

---

🙏 Credits

Data wilayah dari cahyadsn/wilayah

---

💬 Support

Jika ada pertanyaan atau masalah, silakan buat issue di GitHub.

---

Dibuat dengan ❤️ untuk developer Indonesia