DocsWilayah

API Wilayah

Akses data lengkap 83.000+ wilayah administratif Indonesia mulai dari tingkat provinsi hingga kelurahan/desa.

Ringkasan

Base URL:/api/v1/regions

Total Data:83.000+ wilayah

Sumber Data:BPS / Kemendagri

Update:Tahunan (Permendagri)

Apa itu Data Wilayah?

Data wilayah adalah data pembagian administratif Republik Indonesia yang terdiri dari 4 tingkatan hierarki:

Level	Nama Indonesia	Jumlah	Contoh Kode
`province`	Provinsi	38	`31` (DKI Jakarta)
`city`	Kota/Kabupaten	514	`31.71` (Kota Jakarta Pusat)
`district`	Kecamatan	7.277	`31.71.01` (Tanah Abang)
`village`	Kelurahan/Desa	83.761	`31.71.01.1001` (Bendungan Hilir)

Format Kode Wilayah

Kode wilayah menggunakan format hierarkis dengan titik sebagai pemisah. Contoh: 31.71.01.1001 berarti Provinsi 31, Kota 71, Kecamatan 01, Kelurahan 1001.

Endpoints

GET/api/v1/regions

Mendapatkan daftar wilayah dengan pagination

Query Parameters

Parameter	Tipe	Default	Deskripsi
`page`	integer	1	Nomor halaman untuk pagination
`limit`	integer	50	Jumlah data per halaman (maks: 100)
`search`	string	-	Cari berdasarkan nama atau kode wilayah
`level`	string	-	Filter tingkat: `province`, `city`, `district`, `village`

Contoh Request

cURL

curl -X GET "https://api.portaldata.id/api/v1/regions?level=province" \
  -H "X-API-Key: YOUR_API_KEY"

Contoh Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "11",
      "name": "Aceh",
      "nameEn": "Aceh",
      "level": "province",
      "parentId": null,
      "latitude": 4.6951,
      "longitude": 96.7494
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "code": "12",
      "name": "Sumatera Utara",
      "nameEn": "North Sumatra",
      "level": "province",
      "parentId": null,
      "latitude": 2.1154,
      "longitude": 99.5451
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 38,
    "totalPages": 1
  },
  "meta": {
    "source": "BPS / Kemendagri",
    "apiVersion": "1.0.0",
    "regulationRef": "Permendagri 72/2019",
    "riskLevel": "low"
  },
  "disclaimer": "Reference data only. Not legal or tax advice."
}

GET/api/v1/regions/:code

Mendapatkan detail wilayah berdasarkan kode

Path Parameters

Parameter	Tipe	Deskripsi
`code`	string	Kode wilayah BPS (contoh: `31`, `31.71`)

Query Parameters

Parameter	Tipe	Deskripsi
`include`	string	Data tambahan (pisahkan dengan koma): `parent`, `children`, `postal_codes`

Contoh Request

curl -X GET "https://api.portaldata.id/api/v1/regions/31?include=children" \
  -H "X-API-Key: YOUR_API_KEY"

Contoh Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440031",
    "code": "31",
    "name": "DKI Jakarta",
    "nameEn": "Special Capital Region of Jakarta",
    "level": "province",
    "parentId": null,
    "latitude": -6.2088,
    "longitude": 106.8456,
    "metadata": {
      "capital": "Jakarta",
      "area_km2": 664.01
    },
    "children": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440032",
        "code": "31.01",
        "name": "Kepulauan Seribu",
        "level": "city"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440033",
        "code": "31.71",
        "name": "Kota Jakarta Pusat",
        "level": "city"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440034",
        "code": "31.72",
        "name": "Kota Jakarta Utara",
        "level": "city"
      }
    ]
  },
  "meta": {
    "source": "BPS / Kemendagri",
    "apiVersion": "1.0.0",
    "regulationRef": "Permendagri 72/2019",
    "riskLevel": "low"
  },
  "disclaimer": "Reference data only. Not legal or tax advice."
}

Penjelasan Field Response

Field	Tipe	Deskripsi
`id`	UUID	ID unik wilayah dalam format UUID
`code`	string	Kode wilayah BPS (hierarkis dengan titik)
`name`	string	Nama wilayah dalam Bahasa Indonesia
`nameEn`	string \| null	Nama wilayah dalam Bahasa Inggris (jika tersedia)
`level`	enum	Tingkat administratif: province, city, district, village
`parentId`	UUID \| null	ID wilayah induk (null untuk provinsi)
`latitude`	number \| null	Koordinat lintang (decimal degrees)
`longitude`	number \| null	Koordinat bujur (decimal degrees)
`metadata`	object \| null	Data tambahan (ibukota, luas wilayah, dll)
`parent`	object \| undefined	Data wilayah induk (jika include=parent)
`children`	array \| undefined	Daftar wilayah anak (jika include=children)
`postalCodes`	array \| undefined	Daftar kode pos (jika include=postal_codes)

Contoh Penggunaan

1. Dropdown Provinsi

Mengambil daftar semua provinsi untuk form dropdown

GET /api/v1/regions?level=province&limit=100

2. Cascading Dropdown Kota

Mengambil kota/kabupaten berdasarkan provinsi yang dipilih

GET /api/v1/regions/31?include=children

3. Pencarian Wilayah

Mencari wilayah berdasarkan nama

GET /api/v1/regions?search=surabaya&level=city

4. Validasi Alamat

Memvalidasi apakah kombinasi wilayah valid

GET /api/v1/regions/31.71.01?include=parent

Contoh Kode Lengkap

JavaScript - Cascading Dropdown

// Fungsi untuk mengambil daftar provinsi
async function getProvinces() {
  const response = await fetch(
    'https://api.portaldata.id/api/v1/regions?level=province&limit=100',
    { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
  );
  const { data } = await response.json();
  return data;
}

// Fungsi untuk mengambil kota/kabupaten berdasarkan kode provinsi
async function getCities(provinceCode) {
  const response = await fetch(
    `https://api.portaldata.id/api/v1/regions/${provinceCode}?include=children`,
    { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
  );
  const { data } = await response.json();
  return data.children;
}

// Contoh penggunaan
const provinces = await getProvinces();
console.log('Provinsi:', provinces);

const cities = await getCities('31'); // DKI Jakarta
console.log('Kota di DKI Jakarta:', cities);

Python - Mencari Wilayah

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.portaldata.id/api/v1'

def search_regions(query, level=None):
    """Mencari wilayah berdasarkan nama"""
    params = {'search': query}
    if level:
        params['level'] = level

    response = requests.get(
        f'{BASE_URL}/regions',
        params=params,
        headers={'X-API-Key': API_KEY}
    )
    return response.json()['data']

def get_region_hierarchy(code):
    """Mendapatkan hierarki lengkap wilayah"""
    response = requests.get(
        f'{BASE_URL}/regions/{code}',
        params={'include': 'parent,children'},
        headers={'X-API-Key': API_KEY}
    )
    return response.json()['data']

# Contoh penggunaan
results = search_regions('bandung', level='city')
for region in results:
    print(f"{region['code']} - {region['name']}")

# Output:
# 32.73 - Kota Bandung
# 32.04 - Kabupaten Bandung
# 32.17 - Kabupaten Bandung Barat

Best Practices

Cache Data Statis

Data provinsi dan kota jarang berubah. Cache hasil API selama 24 jam untuk mengurangi request dan meningkatkan performa aplikasi.

Gunakan Parameter Include dengan Bijak

Hanya minta data yang diperlukan. Misalnya, jangan minta include=children jika Anda hanya butuh info wilayah tanpa anak-anaknya.

Pagination untuk Data Besar

Untuk daftar kelurahan/desa yang besar, gunakan pagination dengan limit yang wajar (50-100) untuk menghindari response yang terlalu besar.

API Wilayah

Ringkasan

Apa itu Data Wilayah?

Endpoints

Query Parameters

Contoh Request

Contoh Response

Path Parameters

Query Parameters

Contoh Request

Contoh Response

Penjelasan Field Response

Contoh Penggunaan

1. Dropdown Provinsi

2. Cascading Dropdown Kota

3. Pencarian Wilayah

4. Validasi Alamat

Contoh Kode Lengkap

Best Practices

Cache Data Statis

Gunakan Parameter Include dengan Bijak

Pagination untuk Data Besar

Lihat Juga

Upah Minimum

Hari Libur