Indonesia Regions API: Complete Province, Regency, District and Village Data

Almost every app that has an address form, from e-commerce and HRIS to government apps, needs cascading region dropdowns: pick a province, then the regency/city appears automatically, then the district, then the kelurahan/desa (village). The problem is that the official Indonesian administrative region data (based on Kepmendagri, the Ministry of Home Affairs decree) is large and changes often because of regional splits (pemekaran). Hardcoding this data in your own app means you have to keep up the maintenance every time something changes.

The Regions API (API Wilayah) from API Indonesia provides the entire administrative region hierarchy, province, regency/city, district, and kelurahan/desa (village), in one REST API you can just call, without storing a static dataset on your own server.

Data Coverage

• Provinces: 38 provinces across Indonesia
• Regency/City (kabupaten/kota): every regency and city under each province
• District (kecamatan): every district under each regency/city
• Kelurahan/Desa (village): every kelurahan and desa under each district
• Cross-level search: search for a region name without knowing its level first

Endpoint List

Base URL: https://use.apiindonesia.id/api/v1/wilayah

Method	Endpoint	Description
GET	/provinsi	List all provinces (paginated)
GET	/provinsi/:id	Details of one province
GET	/kabupaten?provinsi_id=	List regencies/cities in one province
GET	/kabupaten/:id	Details of one regency/city
GET	/kecamatan?kabupaten_id=	List districts in one regency/city
GET	/kecamatan/:id	Details of one district
GET	/kelurahan?kecamatan_id=	List kelurahan/desa in one district
GET	/kelurahan/:id	Details of one kelurahan/desa
GET	/search?q=	Search regions across all levels at once

All list endpoints support the page and per_page parameters (maximum 100 per page) and return a meta object containing total, page, per_page, and total_pages.

Request Example

Get the list of regencies/cities in West Java:

curl "https://use.apiindonesia.id/api/v1/wilayah/kabupaten?provinsi_id=32" \
  -H "x-api-key: aip_live_xxx"

const res = await fetch(
  'https://use.apiindonesia.id/api/v1/wilayah/kabupaten?provinsi_id=32',
  { headers: { 'x-api-key': process.env.API_INDONESIA_KEY } }
);
const { data, meta } = await res.json();
console.log(data); // [{ id, name, province_id, ... }, ...]

import requests

res = requests.get(
    "https://use.apiindonesia.id/api/v1/wilayah/kabupaten",
    params={"provinsi_id": "32"},
    headers={"x-api-key": "aip_live_xxx"},
)
data = res.json()["data"]

Response Example

{
  "data": [
    { "id": "3273", "name": "KOTA BANDUNG", "province_id": "32" },
    { "id": "3204", "name": "KABUPATEN BANDUNG", "province_id": "32" }
  ],
  "meta": { "total": 27, "page": 1, "per_page": 20, "total_pages": 2 }
}

Building a Cascading Address Dropdown

The most common pattern: keep the provinsi_id the user selected in state, then call /kabupaten?provinsi_id= every time the user changes province. Repeat the same pattern for districts and villages. Because each level has a consistent id that works as a foreign key, you can store province_id, regency_id, district_id, and village_id directly in your own database without copying region names.

If you need free-form address search (for example an autocomplete to find a village), use the /search?q= endpoint, which searches all four levels at once and returns a level field to mark the type of region.

Tips for the /search endpoint:

• Send at least 3 characters before actually calling the API, so autocomplete results do not burn through your quota.
• Debounce user input for around 300ms before fetching.
• Use the level field in the response to decide the icon or label in the dropdown (for example a "Kota" vs "Kabupaten" badge).

Why Not Hardcode the Data Yourself?

Many teams choose to copy an open-source region dataset into their database. That can work, but there is a risk of the data going stale after a regional split or a change to region codes, and you still have to build your own search and pagination endpoints. With the Regions API, the data always matches the latest region codes and you only need one API key to access every endpoint.

Combining with Other APIs

Region data is only really complete when you pair it with other APIs in the same ecosystem:

• Postal Code API: after the user picks a kelurahan, fetch the matching postal codes via /api/v1/kodepos/search?q= so the postal code field fills in automatically. Good for e-commerce checkout and onboarding forms.
• KBBI API: if your app shows region names in its content (for example a regional news portal), validate the spelling of place names via /api/v1/kbbi/word/:word.
• BI Exchange Rate API: for logistics or e-commerce apps that show multi-currency prices per region, pair it with the official Bank Indonesia rates from /api/v1/kurs-bi/latest.

All of these APIs use the same API key, so integration just means adding a base path, not creating a new account.

FAQ

Does this data follow the latest regional changes? Yes, the data follows the latest Kepmendagri region codes and is updated on the API side, so you do not need to patch your own dataset every time a region splits.

How many kelurahan/desa are available in total? Every kelurahan and desa in Indonesia (more than 80 thousand) is available through the /kelurahan endpoint with pagination.

Can I use it for autocomplete? Yes. The /search?q= endpoint searches all levels at once and works well for autocomplete with client-side debounce.

Is it free? There is no monthly free allowance. New accounts get a one-time 3,000 credit bonus (Rp3,000) after email verification, and a successful request costs 2 credits, which is enough to build an MVP and test it.

Start Now

Get a free API key at dashboard.apiindonesia.id/register and see the full parameter list at docs.apiindonesia.id.