@devnovaa-id/bmkg

Professional BMKG library for weather and earthquake data - ESM, TypeScript, fetch

Fitur • Instalasi • Penggunaan Cepat • API • Contoh

✨ Fitur

• ⚡ Cepat & Ringan – Tanpa dependensi eksternal, menggunakan native fetch
• 🌍 Universal – Bekerja di Node.js 18+, browser modern, React, Next.js, dan Deno
• 📦 Dual Format – Mendukung ESM dan CommonJS
• 🔄 Retry & Timeout – Exponential backoff dan timeout configurable
• 💾 Caching – In-memory cache opsional untuk performa lebih baik
• 🛡️ TypeScript – Full type definitions untuk autocomplete dan keamanan tipe
• 🧩 Modular – Import hanya yang dibutuhkan (/cuaca, /gempa)
• 🧪 Real API Tested – Diuji langsung dengan endpoint BMKG resmi

📦 Instalasi

npm install @devnovaa-id/bmkg

Atau menggunakan yarn/pnpm:

yarn add @devnovaa-id/bmkg
pnpm add @devnovaa-id/bmkg

🚀 Penggunaan Cepat

Wilayah (Provinsi, Kabupaten, Kecamatan, Desa)

import { getProvinsi, getKabupaten, getKecamatan, getDesa } from '@devnovaa-id/bmkg';

// Dapatkan semua provinsi
const provinsi = await getProvinsi();
console.log(provinsi[0]); // { id: "11", name: "ACEH" }

// Dapatkan kabupaten di Lampung (id=18)
const kabupaten = await getKabupaten('18');

// Dapatkan kecamatan di Way Kanan (id=1808)
const kecamatan = await getKecamatan('1808');

// Dapatkan desa di Negara Batin (id=180811)
const desa = await getDesa('180811');

Cuaca

import { getCuacaByAdm4, searchDesa, getCuacaByQuery } from '@devnovaa-id/bmkg/cuaca';

// Cari desa berdasarkan nama
const hasilPencarian = await searchDesa('marga jaya');
console.log(hasilPencarian.results);

// Prakiraan cuaca menggunakan kode ADM4
const cuaca = await getCuacaByAdm4('18.08.11.2009');
console.log(cuaca.data.data[0].cuaca[0][0].weather_desc);

// Prakiraan cuaca dengan pencarian otomatis
const cuaca2 = await getCuacaByQuery('marga jaya');

Gempa

import { getGempaTerkini, getGempaList, getGempaDirasakan, getGempaByMagnitude } from '@devnovaa-id/bmkg/gempa';

// Gempa terkini
const gempaTerkini = await getGempaTerkini();
console.log(`${gempaTerkini.Magnitude} - ${gempaTerkini.Wilayah}`);

// Daftar gempa terbaru
const daftarGempa = await getGempaList();

// Gempa yang dirasakan
const gempaDirasakan = await getGempaDirasakan();

// Filter gempa dengan magnitude >= 5.0
const gempaBesar = await getGempaByMagnitude(5.0);

⚙️ Konfigurasi

Anda dapat mengatur perilaku library secara global:

import { configure } from '@devnovaa-id/bmkg';

configure({
  timeout: 10000,        // Timeout 10 detik (default: 15000)
  retries: 3,            // Jumlah percobaan ulang (default: 2)
  enableCache: true,     // Aktifkan cache (default: false)
  cacheTTL: 120000,      // Masa berlaku cache 2 menit (default: 60000)
  logErrors: true,       // Log error ke console (default: true)
});

📚 API Reference

Wilayah

| Fungsi | Parameter | Kembalian | Deskripsi | |--------|-----------|-----------|------------| | getProvinsi() | - | Promise<Provinsi[]> | Semua provinsi | | getKabupaten(provinceId) | string (2 digit) | Promise<Kabupaten[]> | Kabupaten/kota dalam provinsi | | getKecamatan(regencyId) | string (4 digit) | Promise<Kecamatan[]> | Kecamatan dalam kabupaten | | getDesa(districtId) | string (6 digit) | Promise<Desa[]> | Desa dalam kecamatan |

Cuaca

| Fungsi | Parameter | Kembalian | Deskripsi | |--------|-----------|-----------|------------| | getCuacaByAdm4(adm4) | string (format: XX.XX.XX.XXXX) | Promise<CuacaResponse> | Prakiraan cuaca berdasarkan kode ADM4 | | searchDesa(query) | string | Promise<SearchDesaResponse> | Mencari desa berdasarkan kata kunci | | getCuacaByQuery(query) | string | Promise<CuacaResponse> | Prakiraan cuaca untuk desa pertama yang cocok |

Gempa

| Fungsi | Parameter | Kembalian | Deskripsi | |--------|-----------|-----------|------------| | getGempaTerkini() | - | Promise<GempaTerkini> | Gempa bumi terkini | | getGempaList() | - | Promise<GempaListItem[]> | Daftar 15-20 gempa terbaru | | getGempaDirasakan() | - | Promise<GempaDirasakan[]> | Gempa yang dirasakan masyarakat | | getGempaByMagnitude(magnitude, source?) | number, 'list' \| 'dirasakan' | Promise<GempaListItem[]> | Filter gempa berdasarkan magnitude |

Konfigurasi & Utility

| Fungsi | Parameter | Deskripsi | |--------|-----------|------------| | configure(config) | Partial<ClientConfig> | Mengatur timeout, retry, cache, dll | | clearCache() | - | Membersihkan semua cache |

🧩 Contoh Lengkap

React (Next.js)

'use client';
import { useEffect, useState } from 'react';
import { getGempaList, GempaListItem } from '@devnovaa-id/bmkg/gempa';

export default function GempaPage() {
  const [gempa, setGempa] = useState<GempaListItem[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    getGempaList()
      .then(setGempa)
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <div>Memuat data gempa...</div>;

  return (
    <ul>
      {gempa.map((g, idx) => (
        <li key={idx}>
          {g.Tanggal} - M{g.Magnitude} - {g.Wilayah}
        </li>
      ))}
    </ul>
  );
}

Node.js CLI

#!/usr/bin/env node
import { getCuacaByQuery } from '@devnovaa-id/bmkg/cuaca';

const query = process.argv[2];
if (!query) {
  console.error('Gunakan: node cuaca.js <nama_desa>');
  process.exit(1);
}

const cuaca = await getCuacaByQuery(query);
const data = cuaca.data.data[0].cuaca[0][0];
console.log(`
Lokasi: ${cuaca.data.lokasi.desa}, ${cuaca.data.lokasi.kecamatan}
Cuaca: ${data.weather_desc}
Suhu: ${data.t}°C
Kelembaban: ${data.hu}%
Angin: ${data.ws} m/s (${data.wd})
`);

Browser (ESM)

<script type="module">
  import { getGempaTerkini } from 'https://unpkg.com/@devnovaa-id/bmkg/dist/gempa/index.js';
  const gempa = await getGempaTerkini();
  document.body.innerHTML = `<h1>Gempa: ${gempa.Magnitude} - ${gempa.Wilayah}</h1>`;
</script>

🛠️ Error Handling

Library menggunakan custom error classes untuk memudahkan debugging:

import { BMKGError, ValidationError, NotFoundError } from '@devnovaa-id/bmkg';

try {
  await getCuacaByAdm4('invalid');
} catch (err) {
  if (err instanceof ValidationError) {
    console.log('Format input salah:', err.message);
  } else if (err instanceof NotFoundError) {
    console.log('Data tidak ditemukan');
  } else if (err instanceof BMKGError) {
    console.log(`Error BMKG: ${err.code} - ${err.message}`);
  }
}

📄 Lisensi

MIT © Devnova ID

🙏 Sumber Data

Data disediakan oleh Badan Meteorologi, Klimatologi, dan Geofisika (BMKG) melalui API devnova.icu.