JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 185
  • Score
    100M100P100Q66224F
  • License MIT

πŸ—ΊοΈ Lightweight library untuk data wilayah Indonesia (Provinsi, Kabupaten, Kecamatan, Kelurahan)

Package Exports

  • nusantara-api

Readme

Nusantara API

npm version npm downloads license CI coverage file size data

πŸ—ΊοΈ 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

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


🀝 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