# BMKG Indonesia Weather Forecast – Village Level, 3-Day (`nusantara-data-tools/bmkg-indonesia-weather-forecast`) Actor

Official BMKG 3-day weather forecasts for 83,000+ Indonesian villages: temperature, rain, humidity, wind every 3 hours. Search by place name or adm4 code.

- **URL**: https://apify.com/nusantara-data-tools/bmkg-indonesia-weather-forecast.md
- **Developed by:** [Nusantara Data Tools](https://apify.com/nusantara-data-tools) (community)
- **Categories:** Travel, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 location forecasts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## BMKG Indonesia Weather Forecast API – Village Level (3-day, 3-hourly)

**Official BMKG weather forecasts for any of 83,000+ Indonesian villages (desa/kelurahan)** — temperature, rain, humidity, wind, cloud cover and visibility **every 3 hours for 3 days**, in English and Indonesian. Just type a place name like `Ubud, Gianyar`, `Kuta, Badung` or `Kemayoran, Jakarta Pusat` — no need to look up region codes.

Perfect for **logistics & delivery planning, agriculture, construction, tourism & villa operators, events, insurance, dashboards and AI agents** that need hyper-local Indonesian weather.

### Why this Actor

- **Name → code lookup built in** (Kepmendagri 2025 region codes for 83,762 villages). Enter a district name to get all its villages.
- **Two output formats**: one row per 3-hour slot (spreadsheets/BI) or one row per location with min/max temperature, rainy slots, first rain time and total precipitation + nested forecast (apps/LLMs).
- **Respects BMKG's 60 requests/minute limit** and retries automatically; failed locations are not charged.
- **Attribution included** in every row, as required by BMKG.

### Output example (slots mode)

```json
{
  "adm4": "51.04.05.1005", "village": "Ubud", "district": "Ubud", "regency": "Gianyar", "province": "Bali",
  "lat": -8.497, "lon": 115.264, "timezone": "Asia/Makassar",
  "localDatetime": "2026-10-20 17:00:00", "weatherEn": "Partly Cloudy", "weatherId": "Cerah Berawan",
  "temperatureC": 29, "humidityPct": 66, "precipitationMm": 0, "windSpeedKmh": 9.4, "windFrom": "SE",
  "cloudCoverPct": 58, "iconUrl": "https://api-apps.bmkg.go.id/storage/icon/cuaca/...svg",
  "source": "BMKG (Badan Meteorologi, Klimatologi, dan Geofisika)"
}
```

See `samples/` for real output.

### Input

| Field | Description |
|---|---|
| `locations` | Village or district names; add regency/province after commas to disambiguate |
| `adm4Codes` | Or give codes directly, e.g. `31.71.03.1001` |
| `maxVillagesPerLocation` | Expand a district name to up to N villages |
| `outputMode` | `slots` or `locations` |
| `hoursAhead` | Keep only the next N hours |

### Pricing (pay per event)

**$2 per 1,000 location forecasts** (event `location-forecast`; one location = ~20–24 three-hour slots). Schedule it twice a day (BMKG updates forecasts twice daily).

### Data source & terms

Data: BMKG open data API (`api.bmkg.go.id/publik/prakiraan-cuaca`, documented at data.bmkg.go.id). BMKG requires that you **credit BMKG as the data source** in your app — the `source` field is included for this. Region names: Kepmendagri No. 300.2.2-2138/2025 via cahyadsn/wilayah (MIT). Not affiliated with BMKG.

*Kata kunci: prakiraan cuaca BMKG, cuaca per desa, API cuaca Indonesia, weather Bali, weather Jakarta.*

# Actor input Schema

## `locations` (type: `array`):

Indonesian village (desa/kelurahan) or district (kecamatan) names. Add regency/province after commas to disambiguate, e.g. 'Ubud, Gianyar', 'Kuta, Badung', 'Kemayoran, Jakarta Pusat', 'Cibodas, Bandung Barat'.

## `adm4Codes` (type: `array`):

Kepmendagri village codes, format NN.NN.NN.NNNN, e.g. 31.71.03.1001 (Kemayoran).

## `maxVillagesPerLocation` (type: `integer`):

If a name matches several villages (or a whole district), take up to this many.

## `outputMode` (type: `string`):

'slots' = one row per location per 3-hour slot (best for spreadsheets/BI). 'locations' = one row per location with summary + nested forecast array (best for apps/AI agents).

## `hoursAhead` (type: `integer`):

Keep only forecast slots up to this many hours ahead (BMKG provides ~72h).

## `maxLocations` (type: `integer`):

Safety cap on the number of villages fetched (each is one billable 'location-forecast' event).

## Actor input object example

```json
{
  "locations": [
    "Ubud, Gianyar",
    "Kemayoran, Jakarta Pusat"
  ],
  "maxVillagesPerLocation": 1,
  "outputMode": "slots",
  "hoursAhead": 72,
  "maxLocations": 50
}
```

# Actor output Schema

## `overview` (type: `string`):

3-hourly BMKG forecasts per village (or one row per location in locations mode).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locations": [
        "Ubud, Gianyar",
        "Kemayoran, Jakarta Pusat"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nusantara-data-tools/bmkg-indonesia-weather-forecast").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "locations": [
        "Ubud, Gianyar",
        "Kemayoran, Jakarta Pusat",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("nusantara-data-tools/bmkg-indonesia-weather-forecast").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "locations": [
    "Ubud, Gianyar",
    "Kemayoran, Jakarta Pusat"
  ]
}' |
apify call nusantara-data-tools/bmkg-indonesia-weather-forecast --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nusantara-data-tools/bmkg-indonesia-weather-forecast"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Wim7k3znLERNQUfLo/builds/t7V3IVLTrCcaXjoBq/openapi.json