# Wilayah Indonesia — Zapi reference

> Indonesian administrative regions — province, regency, district and village — from official government registries, with BPS and Kemendagri codes.

**Base URL:** `https://api.zpi.web.id`
**Auth:** Send `x-api-key: YOUR_KEY` header on every request. Get a free key at https://zpi.web.id/dashboard/keys.
**Response envelope:** `{ content, message, errors }`
**Rate limit:** 60 req/min on free tier.

**Related:**
- Detail page: https://zpi.web.id/api/indonesia/wilayah
- Endpoint catalog: https://zpi.web.id/category/indonesia
- Concise index: https://zpi.web.id/llms.txt
- Full reference: https://zpi.web.id/llms-full.txt

---

## Wilayah Indonesia

**Category:** indonesia · **Slug:** `wilayah`
**Detail page:** https://zpi.web.id/api/indonesia/wilayah

Indonesian administrative regions — province, regency, district and village — from official government registries, with BPS and Kemendagri codes.

**Tags:** indonesia, wilayah, region, bps, kemendagri, address

### Provinces

All 38 Indonesian provinces with their official BPS codes.

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/indonesia:wilayah/provinces`
- **Cache TTL:** 86400s

**Parameters:**

_No parameters._

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/indonesia:wilayah/provinces" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/indonesia:wilayah/provinces", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/indonesia:wilayah/provinces",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "count": 38,
  "items": [
    {
      "code": "11",
      "name": "ACEH"
    },
    {
      "code": "12",
      "name": "SUMATERA UTARA"
    },
    {
      "code": "13",
      "name": "SUMATERA BARAT"
    },
    {
      "code": "14",
      "name": "RIAU"
    },
    {
      "code": "15",
      "name": "JAMBI"
    },
    {
      "code": "16",
      "name": "SUMATERA SELATAN"
    },
    {
      "code": "17",
      "name": "BENGKULU"
    },
    {
      "code": "18",
      "name": "LAMPUNG"
    }
  ],
  "provider": "sipedas"
}
```

---

### Regencies & Cities

Regencies and cities of one province, typed KABUPATEN or KOTA.

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/indonesia:wilayah/regencies`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `provinceCode` | string | query | yes | BPS province code, 2 digits, from the provinces endpoint. BPS and Kemendagri codes differ for the six Papua provinces. |
| `year` | number | query | no | Registry year. Data exists for 2014-2026; a region is absent from years before it was formed. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/indonesia:wilayah/regencies?provinceCode=32&year=2026" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/indonesia:wilayah/regencies?provinceCode=32&year=2026", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/indonesia:wilayah/regencies?provinceCode=32&year=2026",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "year": 2026,
  "count": 27,
  "items": [
    {
      "code": "3201",
      "name": "BOGOR",
      "type": "KABUPATEN"
    },
    {
      "code": "3202",
      "name": "SUKABUMI",
      "type": "KABUPATEN"
    },
    {
      "code": "3203",
      "name": "CIANJUR",
      "type": "KABUPATEN"
    },
    {
      "code": "3204",
      "name": "BANDUNG",
      "type": "KABUPATEN"
    },
    {
      "code": "3205",
      "name": "GARUT",
      "type": "KABUPATEN"
    },
    {
      "code": "3206",
      "name": "TASIKMALAYA",
      "type": "KABUPATEN"
    },
    {
      "code": "3207",
      "name": "CIAMIS",
      "type": "KABUPATEN"
    },
    {
      "code": "3208",
      "name": "KUNINGAN",
      "type": "KABUPATEN"
    }
  ],
  "provider": "sipedas",
  "provinceCode": "32"
}
```

---

### Districts

Districts (kecamatan) of one regency or city.

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/indonesia:wilayah/districts`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `regencyCode` | string | query | yes | BPS regency/city code, 4 digits, from the regencies endpoint |
| `year` | number | query | no | Registry year. Data exists for 2014-2026; a region is absent from years before it was formed. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/indonesia:wilayah/districts?regencyCode=3204&year=2026" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/indonesia:wilayah/districts?regencyCode=3204&year=2026", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/indonesia:wilayah/districts?regencyCode=3204&year=2026",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "year": 2026,
  "count": 31,
  "items": [
    {
      "code": "3204010",
      "name": "CIWIDEY"
    },
    {
      "code": "3204011",
      "name": "RANCABALI"
    },
    {
      "code": "3204020",
      "name": "PASIRJAMBU"
    },
    {
      "code": "3204030",
      "name": "CIMAUNG"
    },
    {
      "code": "3204040",
      "name": "PANGALENGAN"
    },
    {
      "code": "3204050",
      "name": "KERTASARI"
    },
    {
      "code": "3204060",
      "name": "PACET"
    },
    {
      "code": "3204070",
      "name": "IBUN"
    }
  ],
  "provider": "sipedas",
  "regencyCode": "3204"
}
```

---

### Villages

Villages (desa/kelurahan) of one district.

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/indonesia:wilayah/villages`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `districtCode` | string | query | yes | BPS district code, 7 digits, from the districts endpoint |
| `year` | number | query | no | Registry year. Data exists for 2014-2026; a region is absent from years before it was formed. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/indonesia:wilayah/villages?districtCode=3204280&year=2026" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/indonesia:wilayah/villages?districtCode=3204280&year=2026", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/indonesia:wilayah/villages?districtCode=3204280&year=2026",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "year": 2026,
  "count": 6,
  "items": [
    {
      "code": "3204280001",
      "name": "BOJONGSARI"
    },
    {
      "code": "3204280002",
      "name": "BOJONGSOANG"
    },
    {
      "code": "3204280003",
      "name": "LENGKONG"
    },
    {
      "code": "3204280004",
      "name": "CIPAGALO"
    },
    {
      "code": "3204280005",
      "name": "BUAHBATU"
    },
    {
      "code": "3204280006",
      "name": "TEGALLUAR"
    }
  ],
  "provider": "sipedas",
  "districtCode": "3204280"
}
```

---

### Search

Search regions by name across all four levels; returns BPS and Kemendagri codes.

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/indonesia:wilayah/search`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `q` | string | query | yes | Region name, at least 2 characters. Matches names only, never codes. SQL wildcards work: % for any run of characters, _ for exactly one. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/indonesia:wilayah/search?q=bojong%25soang" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/indonesia:wilayah/search?q=bojong%25soang", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/indonesia:wilayah/search?q=bojong%25soang",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "count": 2,
  "items": [
    {
      "code": "3204280",
      "name": "BOJONGSOANG",
      "level": "district",
      "kodeDagri": "32.04.08",
      "namaDagri": "BOJONGSOANG"
    },
    {
      "code": "3204280002",
      "name": "BOJONGSOANG",
      "level": "village",
      "kodeDagri": "32.04.08.2002",
      "namaDagri": "BOJONGSOANG"
    }
  ],
  "query": "bojong%soang",
  "provider": "sig-bps",
  "truncated": false
}
```

---

### Code Bridging

BPS code, Kemendagri code and postal code for every region under one parent.

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/indonesia:wilayah/bridging`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `level` | enum(province|regency|district|village) | query | yes | Level to list. Items carry both the BPS code and the Kemendagri code, which differ for the six Papua provinces. |
| `parentCode` | string | query | no | BPS code of the parent — 2 digits for regencies, 4 for districts, 7 for villages. Omit for level=province. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/indonesia:wilayah/bridging?level=village&parentCode=3204280" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/indonesia:wilayah/bridging?level=village&parentCode=3204280", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/indonesia:wilayah/bridging?level=village&parentCode=3204280",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "count": 6,
  "items": [
    {
      "code": "3204280001",
      "name": "BOJONGSARI",
      "type": "DESA",
      "kodePos": "40354",
      "kodeDagri": "32.04.08.2005",
      "namaDagri": "BOJONGSARI"
    },
    {
      "code": "3204280002",
      "name": "BOJONGSOANG",
      "type": "DESA",
      "kodePos": "40354",
      "kodeDagri": "32.04.08.2002",
      "namaDagri": "BOJONGSOANG"
    },
    {
      "code": "3204280003",
      "name": "LENGKONG",
      "type": "DESA",
      "kodePos": "40354",
      "kodeDagri": "32.04.08.2001",
      "namaDagri": "LENGKONG"
    },
    {
      "code": "3204280004",
      "name": "CIPAGALO",
      "type": "DESA",
      "kodePos": "40354",
      "kodeDagri": "32.04.08.2004",
      "namaDagri": "CIPAGALO"
    },
    {
      "code": "3204280005",
      "name": "BUAHBATU",
      "type": "DESA",
      "kodePos": "40354",
      "kodeDagri": "32.04.08.2003",
      "namaDagri": "BUAHBATU"
    },
    {
      "code": "3204280006",
      "name": "TEGALLUAR",
      "type": "DESA",
      "kodePos": "40354",
      "kodeDagri": "32.04.08.2006",
      "namaDagri": "TEGALLUAR"
    }
  ],
  "level": "village",
  "provider": "sig-bps",
  "parentCode": "3204280"
}
```

---


_Generated: 2026-09-02T14:24:36.866Z_