BMKG API
Memeriksa API ID EN

Menjalankan instance sendiri

Instance publik dipakai bersama dan dibatasi. Instance sendiri punya batasnya sendiri, dan seluruh API berjalan dalam satu container.

Docker

Image dibangun untuk amd64 dan arm64 dari branch utama, dan sudah memuat situs ini.

Menjalankan image 
docker run -d --name bmkg-api -p 8099:8099 ghcr.io/dhanyyudi/bmkg-api:latest

curl http://localhost:8099/health

Docker Compose dengan Redis

Berkas docker-compose.yml di repository menambahkan Redis supaya cache bertahan saat container dimulai ulang. Stack itu bergabung ke network eksternal bernama private_network dan tidak membuka port host, cocok untuk reverse proxy atau tunnel. Untuk akses langsung, tambahkan entri ports.

Clone lalu jalankan 
git clone https://github.com/dhanyyudi/bmkg-api.git
cd bmkg-api
cp .env.example .env
docker compose up -d

Development lokal

Python 3.12 atau lebih baru untuk API, Node 22 atau lebih baru untuk situs.

Dari source code 
git clone https://github.com/dhanyyudi/bmkg-api.git
cd bmkg-api
make setup
source venv/bin/activate
make dev        # API di http://localhost:8099

# Situs dibangun terpisah, hasilnya ditulis ke ./landing
make web

Konfigurasi

Semua pengaturan berupa environment variable, dibaca dari .env bila ada.

VariabelDefaultKegunaan
REDIS_URLredis://localhost:6379Backend cache. Tanpa Redis, API memakai cache di dalam proses.
RATE_LIMIT_ANONYMOUS30/minuteRequest yang diizinkan per client, per endpoint.
CLIENT_IP_HEADER(kosong)Header pembawa IP client yang sebenarnya di belakang proxy, misalnya CF-Connecting-IP. Dibiarkan kosong kecuali semua request datang lewat proxy itu.
UPSTREAM_MAX_PER_MINUTE50Jumlah request terbanyak per menit ke tiap host BMKG. Nilai 0 menghapus batas.
CACHE_TTL_EARTHQUAKE_LATEST60Detik gempa terbaru di-cache.
CACHE_TTL_EARTHQUAKE_LIST300Detik daftar gempa di-cache.
CACHE_TTL_NOWCAST120Detik peringatan dini di-cache.
CACHE_TTL_WEATHER900Detik satu prakiraan di-cache.
CACHE_TTL_WILAYAH86400Masa cache yang dikirim untuk data wilayah.

Membukanya ke internet

Instance publik cepat atau lambat akan dibanjiri request. Tiga hal menjaganya tetap hidup:

  • Cache di CDN. Setiap response /v1 membawa Cache-Control sesuai umur datanya. Dengan CDN di depan yang mematuhi header itu, request berulang tidak sampai ke server.
  • Rate limit per client yang sebenarnya. Di belakang proxy, CLIENT_IP_HEADER perlu diisi. Tanpa itu semua pengunjung terhitung sebagai proxy.
  • Batas ke BMKG. UPSTREAM_MAX_PER_MINUTE mencegah penyalahgunaan instance berujung pada pemblokiran IP server oleh BMKG.

Server MCP

Image yang sama menjalankan endpoint MCP: container kedua dengan perintah python -m mcp_server.http_server, dan BMKG_API_BASE_URL diarahkan ke API.

Panduan setup MCP