Package Exports

nusantara-api

Readme

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

npm install nusantara-api

🚀 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

// 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);

React Component

Lihat file lengkap di examples/react-app.jsx

import WilayahIndonesia from 'nusantara-api';

function WilayahSelector() {
    const wilayah = new WilayahIndonesia();
    const [selected, setSelected] = useState('');

    const provinces = wilayah.getProvinces();

    return (
        <select onChange={(e) => setSelected(e.target.value)}>
            {provinces.map(p => (
                <option key={p.kode} value={p.kode}>{p.nama}</option>
            ))}
        </select>
    );
}

Vue 3 Component

Lihat file lengkap di examples/vue-components/WilayahSelector.vue

<script setup>
import { ref, computed } from 'vue';
import WilayahIndonesia from 'nusantara-api';

const wilayah = new WilayahIndonesia();
const selected = ref('');

const provinces = computed(() => wilayah.getProvinces());
</script>

<template>
  <select v-model="selected">
    <option v-for="p in provinces" :key="p.kode" :value="p.kode">
      {{ p.nama }}
    </option>
  </select>
</template>

⚡ 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

✅ Ringan - Hanya 420 KB dengan 91K+ data ✅ Cepat - Pencarian O(1) untuk find by ID ✅ Lengkap - Data terbaru sesuai Kepmendagri 2025 ✅ Mudah - API sederhana dan jelas ✅ Modern - Support CommonJS, ES Module, TypeScript ✅ Fleksibel - Bisa untuk Node.js, React, Vue, Express, dll ✅ Teruji - 68 unit tests dengan 100% pass ✅ No Dependencies - Pure Node.js built-in modules

📚 Dokumentasi Lengkap

🤝 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

nusantara-api