Pos Indonesia API: Cek Kode Pos dan Data Alamat untuk Logistik dan E-Commerce

Developer logistik dan ecommerce di Indonesia sering mencari "Pos Indonesia API" untuk satu kebutuhan praktis: menerjemahkan alamat jadi kode pos, atau sebaliknya, memvalidasi alamat pelanggan saat checkout. Kenyataannya, kanal data kode pos yang beredar tidak selalu enak dipakai secara programatik.

Masalah yang biasa ditemui:

• Pencarian di situs web bukan API, jadi tidak bisa dipanggil dari backend checkout.
• Dataset yang beredar di internet tidak seragam, kadang cuma sampai tingkat kota tanpa hierarki desa.
• Tidak ada endpoint pencarian by nomor kode pos, padahal itu use case paling sering: user isi "40154", sistem harus tahu itu Isola, Sukasari, Kota Bandung.

API Kode Pos dari API Indonesia menutup kebutuhan itu: direktori 83.000+ kode pos se-Indonesia lengkap dengan hierarki wilayah dari provinsi sampai desa, dalam REST API biasa.

Endpoint

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

Method	Endpoint	Keterangan
GET	/	List kode pos, filter per provinsi/kabupaten/kecamatan, paginated
GET	/search?q=	Cari by nama desa atau nomor kode pos
GET	/:id	Detail satu entri

Contoh curl: cari by kode pos

curl "https://use.apiindonesia.id/api/v1/kodepos/search?q=40154" \
  -H "x-api-key: $API_INDONESIA_KEY"

Response:

{
  "data": [
    {
      "id": "kp_3273010001",
      "village_name": "ISOLA",
      "district_name": "SUKASARI",
      "regency_name": "KOTA BANDUNG",
      "province_name": "JAWA BARAT",
      "postal_code": "40154"
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 20, "total_pages": 1 }
}

Contoh curl: list per kabupaten

curl "https://use.apiindonesia.id/api/v1/kodepos?kabupaten_id=3273&per_page=100" \
  -H "x-api-key: $API_INDONESIA_KEY"

Contoh Integrasi: Validasi Alamat Checkout (Python)

Pola yang umum di checkout ecommerce: user pilih provinsi dan kabupaten pakai API Wilayah, lalu kode pos divalidasi silang dengan data kode pos sebelum order dibuat.

import requests, os

BASE = "https://use.apiindonesia.id/api/v1"
HEADERS = {"x-api-key": os.environ["API_INDONESIA_KEY"]}

def cari_kode_pos(keyword: str):
    res = requests.get(
        f"{BASE}/kodepos/search",
        params={"q": keyword},
        headers=HEADERS,
        timeout=10,
    )
    res.raise_for_status()
    return res.json()["data"]

def validasi_alamat(postal_code: str, regency_name: str) -> bool:
    hasil = cari_kode_pos(postal_code)
    if not hasil:
        return False
    # kode pos harus benar-benar ada di kabupaten/kota yang dipilih user
    return any(r["regency_name"].upper() == regency_name.upper() for r in hasil)

print(validasi_alamat("40154", "KOTA BANDUNG"))  # True
print(validasi_alamat("40154", "KOTA JAKARTA"))  # False

Use Case

• Checkout ecommerce: autokomplit kode pos dari nama desa, atau validasi silang kode pos vs kabupaten.
• Aplikasi 3PL / ekspedisi: hitung tarif lebih akurat karena kode pos tujuan terverifikasi.
• Form onboarding merchant: normalkan alamat merchant jadi hierarki standar provinsi, kabupaten, kecamatan, desa.
• Data cleansing CRM: perbaiki alamat pelanggan lama dengan memetakan ulang ke kode pos resmi.

Catatan Teknis

• Data statis bersumber dari dataset resmi, jadi konsisten antar panggilan dan aman di-cache di sisi aplikasi Anda.
• Semua list endpoint mendukung page dan per_page (maksimum 100).
• Kalau butuh kode wilayah (kode kemendagri) juga, pasangkan dengan API Wilayah Indonesia, satu API key untuk semua.

Mulai Sekarang

Dapatkan API key gratis di dashboard.apiindonesia.id/register. Detail parameter lengkap ada di halaman API Kode Pos Indonesia dan docs.apiindonesia.id.