API Documentation

Overview

This API provides access to Indonesian administrative divisions data, including provinces, cities/regencies, districts, and villages. All endpoints return JSON responses with a consistent structure.

Response Format

{
  "status": boolean,
  "message": string,
  "data": array | null
}

Endpoints

Get All Provinces

Retrieve a list of all provinces in Indonesia

Endpoint: /api/provinces

Method: GET

Query Parameters:

Name	Type	Description
sort	string	Set to 'name' to sort results alphabetically by name

Response Example:

{
  "status": true,
  "statusCode": 200,
  "message": "Provinces retrieved successfully",
  "data": [
    {
      "id": "11",
      "name": "Aceh"
    },
    {
      "id": "12",
      "name": "Sumatera Utara"
    },
    // ...
  ]
}

Get Cities by Province ID

Retrieve a list of cities/regencies in a specific province

Endpoint: /api/cities/{provinceId}

Method: GET

Parameters:

Name	Type	Description
provinceId	string	The ID of the province

Query Parameters:

Name	Type	Description
sort	string	Set to 'name' to sort results alphabetically by name

Response Example:

{
  "status": true,
  "statusCode": 200,
  "message": "Cities in province Aceh retrieved successfully",
  "data": [
    {
      "id": "1101",
      "provinceId": "11",
      "name": "Kabupaten Simeulue"
    },
    {
      "id": "1102",
      "provinceId": "11",
      "name": "Kabupaten Aceh Singkil"
    },
    // ...
  ]
}

Get Districts by City ID

Retrieve a list of districts in a specific city/regency

Endpoint: /api/districts/{cityId}

Method: GET

Parameters:

Name	Type	Description
cityId	string	The ID of the city/regency

Query Parameters:

Name	Type	Description
sort	string	Set to 'name' to sort results alphabetically by name

Response Example:

{
  "status": true,
  "statusCode": 200,
  "message": "Districts in city Kabupaten Simeulue retrieved successfully",
  "data": [
    {
      "id": "1101010",
      "cityId": "1101",
      "name": "Teupah Selatan"
    },
    {
      "id": "1101020",
      "cityId": "1101",
      "name": "Simeulue Timur"
    },
    // ...
  ]
}

Get Villages by District ID

Retrieve a list of villages in a specific district

Endpoint: /api/villages/{districtId}

Method: GET

Parameters:

Name	Type	Description
districtId	string	The ID of the district

Query Parameters:

Name	Type	Description
sort	string	Set to 'name' to sort results alphabetically by name

Response Example:

{
  "status": true,
  "statusCode": 200,
  "message": "Villages in district Teupah Selatan retrieved successfully",
  "data": [
    {
      "id": "1101010001",
      "districtId": "1101010",
      "name": "Latiung"
    },
    {
      "id": "1101010002",
      "districtId": "1101010",
      "name": "Labuhan Bajau"
    },
    // ...
  ]
}

Implementation Example

Cascading Dropdown for Region Selection

A practical example of using the API to create dependent dropdowns for selecting Indonesian regions

Below is a working example of cascading dropdowns that use the API to load provinces, cities, districts, and villages:

Provinsi

Kabupaten/Kota

Kecamatan

Desa/Kelurahan

Error Handling

The API returns appropriate HTTP status codes along with error messages in the response body.

Status Code	Description
200	Success
404	Resource not found
500	Internal server error

Error Response Example

{
  "status": false,
  "statusCode": 404,
  "message": "Province with ID 999 not found",
  "data": null
}