REST API

REST API menyediakan akses ke data kode pos Indonesia melalui endpoint RESTful. Autentikasi menggunakan header Authorization: Bearer.

Base URL: https://api.kodepos.dev/kodepos/api

Data Model

Data kode pos Indonesia mengikuti hierarki wilayah: Provinsi → Kota/Kabupaten → Kecamatan → Kelurahan/Desa. Setiap kelurahan/desa memiliki kode pos.

Entitas	Field	Tipe	Deskripsi
Province	code	string	Kode provinsi (2 digit)
Province	name	string	Nama provinsi
City	code	string	Kode kota/kabupaten (5 digit)
City	name	string	Nama kota/kabupaten
District	code	string	Kode kecamatan (8 digit)
District	name	string	Nama kecamatan
Subdistrict	code	string	Kode kelurahan/desa (13 digit)
	name	string	Nama kelurahan/desa
	postalCode	string	Kode pos (5 digit)

Response Envelope

Semua response API menggunakan format envelope yang konsisten. Response yang berhasil memiliki field success: true dan data, sedangkan response error memiliki success: false dan error.

Response Berhasil

{
  "success": true,
  "data": [ ... ]
}

Response Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Deskripsi error dalam bahasa Inggris"
  }
}

Pagination

Semua endpoint list mendukung pagination berbasis kursor (cursor-based pagination). Gunakan parameter first dan after untuk menavigasi hasil.

Parameter	Tipe	Default	Deskripsi
first	integer	20	Jumlah item per halaman (maks 100)
after	string	null	Kursor untuk halaman berikutnya

Contoh Response dengan Pagination

{
  "success": true,
  "data": [
    { "code": "11", "name": "Aceh" },
    { "code": "12", "name": "Sumatera Utara" }
  ],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJjb2RlIjoiMTIifQ=="
  }
}

Menggunakan Kursor

Gunakan nilai endCursor dari response sebelumnya sebagai parameter after untuk mendapatkan halaman berikutnya:

curl -H "Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx" \
  "https://api.kodepos.dev/kodepos/api/provinces?first=10&after=eyJjb2RlIjoiMTIifQ=="

Provinces

GET

/kodepos/api/provinces

Mendapatkan daftar provinsi di Indonesia.

Parameter

Parameter	Tipe	Deskripsi
q	string	Kata kunci pencarian (opsional)
first	integer	Jumlah item per halaman (default 20)
after	string	Kursor pagination

Contoh Request

curl -H "Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx" \
  "https://api.kodepos.dev/kodepos/api/provinces?first=5"

Contoh Response

{
  "success": true,
  "data": [
    { "code": "11", "name": "Aceh" },
    { "code": "12", "name": "Sumatera Utara" },
    { "code": "13", "name": "Sumatera Barat" },
    { "code": "14", "name": "Riau" },
    { "code": "15", "name": "Jambi" }
  ],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJjb2RlIjoiMTUifQ=="
  }
}

GET

/kodepos/api/provinces/:code

Mendapatkan detail provinsi berdasarkan kode.

Contoh Request

curl -H "Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx" \
  "https://api.kodepos.dev/kodepos/api/provinces/11"

Contoh Response

{
  "success": true,
  "data": {
    "code": "11",
    "name": "Aceh"
  }
}

Cities

GET

/kodepos/api/cities

Mendapatkan daftar kota/kabupaten berdasarkan kode provinsi.

Parameter

Parameter	Tipe	Deskripsi
provinceCode wajib	string	Filter berdasarkan kode provinsi (wajib)
q	string	Kata kunci pencarian (opsional)
first	integer	Jumlah item per halaman (default 20)
after	string	Kursor pagination

Contoh Request

curl -H "Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx" \
  "https://api.kodepos.dev/kodepos/api/cities?provinceCode=11&first=5"

Contoh Response

{
  "success": true,
  "data": [
    { "code": "11.01", "name": "Kab. Aceh Selatan" },
    { "code": "11.02", "name": "Kab. Aceh Tenggara" },
    { "code": "11.03", "name": "Kab. Aceh Timur" },
    { "code": "11.04", "name": "Kab. Aceh Tengah" },
    { "code": "11.05", "name": "Kab. Aceh Barat" }
  ],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJjb2RlIjoiMTEuMDUifQ=="
  }
}

GET

/kodepos/api/cities/:code

Mendapatkan detail kota/kabupaten berdasarkan kode, termasuk data provinsi induk.

Contoh Response

{
  "success": true,
  "data": {
    "code": "11.01",
    "name": "Kab. Aceh Selatan",
    "province": {
      "code": "11",
      "name": "Aceh"
    }
  }
}

Districts

GET

/kodepos/api/districts

Mendapatkan daftar kecamatan berdasarkan kode kota/kabupaten.

Parameter

Parameter	Tipe	Deskripsi
cityCode wajib	string	Filter berdasarkan kode kota/kabupaten (wajib)
q	string	Kata kunci pencarian (opsional)
first	integer	Jumlah item per halaman (default 20)
after	string	Kursor pagination

Contoh Request

curl -H "Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx" \
  "https://api.kodepos.dev/kodepos/api/districts?cityCode=11.01&first=5"

Contoh Response

{
  "success": true,
  "data": [
    { "code": "11.01.01", "name": "Bakongan" },
    { "code": "11.01.02", "name": "Kluet Utara" },
    { "code": "11.01.03", "name": "Kluet Selatan" },
    { "code": "11.01.04", "name": "Kluet Timur" },
    { "code": "11.01.05", "name": "Kluet Tengah" }
  ],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJjb2RlIjoiMTEuMDEuMDUifQ=="
  }
}

GET

/kodepos/api/districts/:code

Mendapatkan detail kecamatan berdasarkan kode, termasuk data kota dan provinsi induk.

Contoh Response

{
  "success": true,
  "data": {
    "code": "11.01.01",
    "name": "Bakongan",
    "city": {
      "code": "11.01",
      "name": "Kab. Aceh Selatan"
    },
    "province": {
      "code": "11",
      "name": "Aceh"
    }
  }
}

Subdistricts

GET

/kodepos/api/subdistricts

Mendapatkan daftar kelurahan/desa beserta kode pos dan hierarki wilayah berdasarkan kode kecamatan.

Parameter

Parameter	Tipe	Deskripsi
districtCode wajib	string	Filter berdasarkan kode kecamatan (wajib)
q	string	Kata kunci pencarian (opsional)
first	integer	Jumlah item per halaman (default 20)
after	string	Kursor pagination

Contoh Request

curl -H "Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx" \
  "https://api.kodepos.dev/kodepos/api/subdistricts?districtCode=11.01.01&first=5"

Contoh Response

{
  "success": true,
  "data": [
    {
      "code": "11.01.01.2001",
      "name": "Kampung Baru",
      "postalCode": "23761",
      "district": { "code": "11.01.01", "name": "Bakongan" },
      "city": { "code": "11.01", "name": "Kab. Aceh Selatan" },
      "province": { "code": "11", "name": "Aceh" }
    }
  ],
  "pagination": {
    "hasNextPage": false,
    "endCursor": null
  }
}

GET

/kodepos/api/subdistricts/:code

Mendapatkan detail kelurahan/desa berdasarkan kode, termasuk kode pos dan hierarki wilayah lengkap.

Contoh Response

{
  "success": true,
  "data": {
    "code": "11.01.01.2001",
    "name": "Kampung Baru",
    "postalCode": "23761",
    "district": { "code": "11.01.01", "name": "Bakongan" },
    "city": { "code": "11.01", "name": "Kab. Aceh Selatan" },
    "province": { "code": "11", "name": "Aceh" }
  }
}

Pencarian

GET

/kodepos/api/search

Pencarian lintas semua kelurahan/desa berdasarkan kata kunci. Pencarian dilakukan pada nama kelurahan, kode pos, nama kecamatan, nama kota/kabupaten, dan nama provinsi.

Parameter

Parameter	Tipe	Deskripsi
q wajib	string	Kata kunci pencarian (wajib, min. 2 karakter)
first	integer	Jumlah item per halaman (default 20)
after	string	Kursor pagination

Contoh Request

curl -H "Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx" \
  "https://api.kodepos.dev/kodepos/api/search?q=menteng&first=5"

Contoh Response

{
  "success": true,
  "data": [
    {
      "code": "31.73.06.1003",
      "name": "Menteng",
      "postalCode": "10310",
      "district": { "code": "31.73.06", "name": "Menteng" },
      "city": { "code": "31.73", "name": "Kota Jakarta Pusat" },
      "province": { "code": "31", "name": "DKI Jakarta" }
    }
  ],
  "pagination": {
    "hasNextPage": false,
    "endCursor": null
  }
}