BMKG API

English | Bahasa Indonesia

🇬🇧 English

Free REST API for Indonesian weather forecasts, earthquake data, weather warnings, and region lookup from BMKG.

🌐 Demo: https://bmkg-restapi.vercel.app

⚠️ Important Notice

This is a demo/public instance with rate limits (30 requests/minute) to ensure fair usage.

For production use with unlimited requests, please self-host.

Features

🌍 Earthquake Data — Latest, recent (M 5.0+), felt earthquakes, nearby search by coordinates
🌤️ Weather Forecast — 3-day forecasts & current weather for any kelurahan/desa in Indonesia
⚠️ Weather Warnings (Nowcast) — Real-time severe weather alerts with affected area polygons
📍 Region Lookup — Indonesian provinces, districts, subdistricts, villages, plus search
📊 Auto-generated Docs — Interactive API documentation at /docs
⚡ Caching — Fast responses with in-memory cache (configurable TTL)
🌐 CORS Enabled — Use from any frontend
🔓 No API Key Required — Simple, anonymous access
📈 Rate Limit Headers — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset on every response
🐳 Docker & GHCR — Automated multi-arch Docker images published to GitHub Container Registry
🤖 MCP Server — Model Context Protocol for AI assistants (Claude, Cursor, etc.)

Quick Start

# Latest earthquake
curl https://bmkg-restapi.vercel.app/v1/earthquake/latest

# Weather forecast for Pejaten Barat, Pasar Minggu, Jakarta Selatan
curl https://bmkg-restapi.vercel.app/v1/weather/31.74.04.1006

# Current weather
curl https://bmkg-restapi.vercel.app/v1/weather/31.74.04.1006/current

# Active weather warnings
curl https://bmkg-restapi.vercel.app/v1/nowcast

# Search regions
curl https://bmkg-restapi.vercel.app/v1/wilayah/search?q=tebet

API Endpoints

🌍 Earthquake

Endpoint	Description
`GET /v1/earthquake/latest`	Latest earthquake
`GET /v1/earthquake/recent`	Recent earthquakes (M 5.0+)
`GET /v1/earthquake/felt`	Felt earthquakes
`GET /v1/earthquake/nearby?lat=&lon=&radius_km=`	Nearby earthquakes

🌤️ Weather

Endpoint	Description
`GET /v1/weather/{adm4_code}`	3-day forecast for a kelurahan/desa
`GET /v1/weather/{adm4_code}/current`	Current weather for a kelurahan/desa

⚠️ Nowcast (Weather Warnings)

Endpoint	Description
`GET /v1/nowcast`	Active weather warnings by province
`GET /v1/nowcast/{alert_code}`	Warning detail with affected area polygons
`GET /v1/nowcast/check?location=`	Check warnings for a specific location

📍 Wilayah (Region)

Endpoint	Description
`GET /v1/wilayah/provinces`	List provinces
`GET /v1/wilayah/districts?province_code=`	List districts
`GET /v1/wilayah/subdistricts?district_code=`	List subdistricts
`GET /v1/wilayah/villages?subdistrict_code=`	List villages
`GET /v1/wilayah/search?q={query}`	Search regions

Full documentation: https://bmkg-restapi.vercel.app/docs

🤖 MCP Server (for AI Assistants)

Use BMKG data directly in Claude Desktop, Cursor, VS Code, Windsurf, Zed, and other MCP-compatible AI assistants.

Deployment Options

We support two deployment modes:

🔌 Option A: HTTP Transport (No Installation Required)

Connect via Smithery or HTTP-compatible MCP clients
No local installation needed
Best for: Web IDEs, cloud environments

💻 Option B: Stdio Transport (Local Install)

Install via pipx/pip and run locally
Best for: Claude Desktop, Cursor, local development

Option A: HTTP Transport (Recommended for Web)

Smithery (smithery.ai) - Easiest:

Go to https://smithery.ai
Search for "bmkg-api-mcp" or visit direct link
Click "Add to Client"
Done! No installation required.

Manual HTTP Configuration:

For MCP clients that support Streamable HTTP transport:

Claude Code:

claude mcp add --transport http bmkg-api https://mcp-bmkg.dhanypedia.it.com/mcp

Claude Desktop (Settings → MCP):

{
  "mcpServers": {
    "bmkg-api": {
      "url": "https://mcp-bmkg.dhanypedia.it.com/mcp"
    }
  }
}

Cursor (Settings → MCP Servers):

Click "Add New MCP Server"
Name: bmkg-api
Type: http
URL: https://mcp-bmkg.dhanypedia.it.com/mcp

VS Code (Cline/Roo Code):

{
  "mcpServers": {
    "bmkg-api": {
      "url": "https://mcp-bmkg.dhanypedia.it.com/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windsurf:

Open Cascade → MCP Servers
Click "+ Add Custom Server"
Select "HTTP Transport"
Enter URL: https://mcp-bmkg.dhanypedia.it.com/mcp

Option B: Stdio Transport (Local Installation)

# Via pipx (recommended)
pipx install bmkg-api-mcp

# Via pip
pip install bmkg-api-mcp

Claude Desktop:

# Edit config file
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add this to your config:

{
  "mcpServers": {
    "bmkg-api": {
      "command": "bmkg-api-mcp"
    }
  }
}

Cursor:

Open Settings → Features → MCP Servers
Click "Add New MCP Server"
Name: bmkg-api, Type: command, Command: bmkg-api-mcp

VS Code (Cline/Roo Code):

{
  "mcpServers": {
    "bmkg-api": {
      "command": "bmkg-api-mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Available Tools (15)

Category	Tools
🌍 Earthquake	`get_latest_earthquake`, `get_recent_earthquakes`, `get_felt_earthquakes`, `get_nearby_earthquakes`
🌤️ Weather	`get_weather_forecast`, `get_current_weather`
⚠️ Nowcast	`get_weather_warnings`, `check_location_warnings`
📍 Region	`search_regions`, `get_provinces`, `get_districts`, `get_subdistricts`, `get_villages`
🔧 Utility	`get_cache_stats`, `debug_ping`

Example Prompts

Try these natural language queries in your AI assistant:

"Gempa terbaru di Indonesia berapa magnitudenya?"
"Cuaca 3 hari ke depan di Jakarta Selatan?"
"Cari kode wilayah untuk Kelapa Gading"
"Ada peringatan cuaca ekstrem di Yogyakarta?"
"Gempa dengan magnitud di atas 5 derajat minggu ini?"
"Bandung ada gempa dekat-dekat sini?"

Features

⚡ Caching — Smart TTL-based caching for optimal performance
🐛 Debug Mode — Run bmkg-api-mcp --debug for verbose logging
🔌 7 Specialized Prompts — Earthquake, weather, region, emergency, travel, research, and daily briefing assistants

📖 Full Setup Guide: See MCP_SETUP.md for detailed configuration for all supported IDEs.

Self-Hosting

Option 1: Docker (Recommended)

# Pull from GitHub Container Registry
docker pull ghcr.io/dhanyyudi/bmkg-api:latest

# Or build and run with Docker Compose
git clone https://github.com/dhanyyudi/bmkg-api.git
cd bmkg-api
docker-compose up -d

Option 2: Local Development

git clone https://github.com/dhanyyudi/bmkg-api.git
cd bmkg-api
make setup
source venv/bin/activate
make dev     # starts server on http://localhost:8099

Option 3: Vercel (Serverless)

Deploy to Vercel with one click — the api/index.py and vercel.json are pre-configured.

See Self-Hosting Guide for detailed instructions.

Code Examples

Available on the landing page for: cURL, JavaScript, Python, Go, PHP, Ruby, and Dart (Flutter).

🇮🇩 Bahasa Indonesia

API REST gratis untuk prakiraan cuaca, data gempa bumi, peringatan cuaca, dan pencarian wilayah Indonesia dari BMKG.

🌐 Demo: https://bmkg-restapi.vercel.app

⚠️ Pemberitahuan Penting

Ini adalah instance demo/publik dengan batasan rate limit (30 request/menit).

Untuk penggunaan produksi dengan request tanpa batas, silakan self-host.

Fitur

🌍 Data Gempa — Gempa terbaru, terkini (M 5.0+), dirasakan, pencarian radius
🌤️ Prakiraan Cuaca — 3 hari & cuaca saat ini untuk lokasi mana pun di Indonesia
⚠️ Peringatan Cuaca (Nowcast) — Peringatan dini real-time dengan poligon area terdampak
📍 Pencarian Wilayah — Provinsi, kabupaten, kecamatan, desa, plus pencarian
📊 Dokumentasi Auto — Dokumentasi API interaktif di /docs
⚡ Caching — Response cepat dengan cache lokal (TTL bisa dikonfigurasi)
🌐 CORS Enabled — Bisa dipakai dari frontend mana saja
🔓 Tanpa API Key — Akses sederhana dan anonim
📈 Rate Limit Headers — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset di setiap response
🐳 Docker & GHCR — Image Docker multi-arsitektur otomatis di GitHub Container Registry
🤖 MCP Server — Model Context Protocol untuk AI assistants (Claude, Cursor, dll)

Cepat Mulai

# Gempa terbaru
curl https://bmkg-restapi.vercel.app/v1/earthquake/latest

# Prakiraan cuaca Pejaten Barat, Pasar Minggu, Jakarta Selatan
curl https://bmkg-restapi.vercel.app/v1/weather/31.74.04.1006

# Cuaca saat ini
curl https://bmkg-restapi.vercel.app/v1/weather/31.74.04.1006/current

# Peringatan cuaca aktif
curl https://bmkg-restapi.vercel.app/v1/nowcast

# Cari wilayah
curl https://bmkg-restapi.vercel.app/v1/wilayah/search?q=wiradesa

Endpoint API

🌍 Gempa Bumi

Endpoint	Deskripsi
`GET /v1/earthquake/latest`	Gempa terbaru
`GET /v1/earthquake/recent`	Gempa terkini (M 5.0+)
`GET /v1/earthquake/felt`	Gempa dirasakan
`GET /v1/earthquake/nearby?lat=&lon=&radius_km=`	Gempa terdekat

🌤️ Cuaca

Endpoint	Deskripsi
`GET /v1/weather/{adm4_code}`	Prakiraan 3 hari
`GET /v1/weather/{adm4_code}/current`	Cuaca saat ini

⚠️ Nowcast (Peringatan Cuaca)

Endpoint	Deskripsi
`GET /v1/nowcast`	Peringatan cuaca aktif per provinsi
`GET /v1/nowcast/{alert_code}`	Detail peringatan dengan poligon area
`GET /v1/nowcast/check?location=`	Cek peringatan untuk lokasi tertentu

📍 Wilayah

Endpoint	Deskripsi
`GET /v1/wilayah/provinces`	Daftar provinsi
`GET /v1/wilayah/districts?province_code=`	Daftar kabupaten/kota
`GET /v1/wilayah/subdistricts?district_code=`	Daftar kecamatan
`GET /v1/wilayah/villages?subdistrict_code=`	Daftar desa/kelurahan
`GET /v1/wilayah/search?q={query}`	Cari wilayah

Dokumentasi lengkap: https://bmkg-restapi.vercel.app/docs

🤖 MCP Server (untuk AI Assistants)

Gunakan data BMKG langsung di Claude Desktop, Cursor, VS Code, Windsurf, Zed, dan AI assistants lain yang kompatibel dengan MCP.

Instalasi

# Via pipx (direkomendasikan)
pipx install bmkg-api-mcp

# Via pip
pip install bmkg-api-mcp

Setup Cepat

Claude Desktop:

# Edit file config
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Tambahkan ke config:

{
  "mcpServers": {
    "bmkg-api": {
      "command": "bmkg-api-mcp"
    }
  }
}

Cursor:

Buka Settings → Features → MCP Servers
Klik "Add New MCP Server"
Name: bmkg-api, Type: command, Command: bmkg-api-mcp

VS Code (Cline/Roo Code):

{
  "mcpServers": {
    "bmkg-api": {
      "command": "bmkg-api-mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Tools Tersedia (15)

Kategori	Tools
🌍 Gempa	`get_latest_earthquake`, `get_recent_earthquakes`, `get_felt_earthquakes`, `get_nearby_earthquakes`
🌤️ Cuaca	`get_weather_forecast`, `get_current_weather`
⚠️ Nowcast	`get_weather_warnings`, `check_location_warnings`
📍 Wilayah	`search_regions`, `get_provinces`, `get_districts`, `get_subdistricts`, `get_villages`
🔧 Utility	`get_cache_stats`, `debug_ping`

Contoh Prompt

Coba query bahasa alami ini di AI assistant Anda:

"Gempa terbaru di Indonesia berapa magnitudenya?"
"Cuaca 3 hari ke depan di Jakarta Selatan?"
"Cari kode wilayah untuk Kelapa Gading"
"Ada peringatan cuaca ekstrem di Yogyakarta?"
"Gempa dengan magnitud di atas 5 derajat minggu ini?"
"Bandung ada gempa dekat-dekat sini?"

Fitur

⚡ Caching — Caching cerdas dengan TTL untuk performa optimal
🐛 Debug Mode — Jalankan bmkg-api-mcp --debug untuk logging detail
🔌 7 Prompt Spesialis — Asisten gempa, cuaca, wilayah, darurat, travel, riset, dan briefing harian

📖 Panduan Lengkap: Lihat MCP_SETUP.md untuk konfigurasi detail semua IDE yang didukung.

Self-Hosting

Opsi 1: Docker (Direkomendasikan)

# Pull dari GitHub Container Registry
docker pull ghcr.io/dhanyyudi/bmkg-api:latest

# Atau build dan jalankan dengan Docker Compose
git clone https://github.com/dhanyyudi/bmkg-api.git
cd bmkg-api
docker-compose up -d

Opsi 2: Lokal

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

Opsi 3: Vercel (Serverless)

Deploy ke Vercel — api/index.py dan vercel.json sudah dikonfigurasi.

Lihat Panduan Self-Hosting untuk detail.

Contoh Kode

Tersedia di halaman utama untuk: cURL, JavaScript, Python, Go, PHP, Ruby, dan Dart (Flutter).

Data Source

All data is sourced from BMKG (Badan Meteorologi, Klimatologi, dan Geofisika).

Attribution

This API is not affiliated with BMKG. All data belongs to BMKG.

License

MIT License — see LICENSE

Built with ❤️ by dhanypedia

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.github		.github
api		api
app		app
landing		landing
mcp_server		mcp_server
tests		tests
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
INSTALL.md		INSTALL.md
LICENSE		LICENSE
MCP_SETUP.md		MCP_SETUP.md
Makefile		Makefile
README.md		README.md
docker-compose.test.yml		docker-compose.test.yml
docker-compose.yml		docker-compose.yml
mcp_server.json		mcp_server.json
package.json		package.json
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
smithery.yaml		smithery.yaml
tailwind.config.js		tailwind.config.js
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

BMKG API

🇬🇧 English

⚠️ Important Notice

Features

Quick Start

API Endpoints

🌍 Earthquake

🌤️ Weather

⚠️ Nowcast (Weather Warnings)

📍 Wilayah (Region)

🤖 MCP Server (for AI Assistants)

Deployment Options

Option A: HTTP Transport (Recommended for Web)

Option B: Stdio Transport (Local Installation)

Available Tools (15)

Example Prompts

Features

Self-Hosting

Option 1: Docker (Recommended)

Option 2: Local Development

Option 3: Vercel (Serverless)

Code Examples

🇮🇩 Bahasa Indonesia

⚠️ Pemberitahuan Penting

Fitur

Cepat Mulai

Endpoint API

🌍 Gempa Bumi

🌤️ Cuaca

⚠️ Nowcast (Peringatan Cuaca)

📍 Wilayah

🤖 MCP Server (untuk AI Assistants)

Instalasi

Setup Cepat

Tools Tersedia (15)

Contoh Prompt

Fitur

Self-Hosting

Opsi 1: Docker (Direkomendasikan)

Opsi 2: Lokal

Opsi 3: Vercel (Serverless)

Contoh Kode

Data Source

Attribution

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages