API kode pos Indonesia yang paling praktis untuk form checkout adalah endpoint GET /v1/locations/search di AgenWebsite Rate API: pembeli mengetik minimal tiga huruf nama kecamatan, kota, atau kode pos, dan Anda mendapat daftar kecamatan lengkap dengan postal_code, subdistrict_id, dan satu label siap tampil. Endpoint ini tersedia di semua paket, termasuk Free, tapi setiap panggilannya menghitung satu kuota, jadi cara memanggilnya menentukan apakah 150 request per hari cukup atau habis sebelum jam makan siang.

Satu pola kesalahan yang berulang di order toko online: pembeli menulis “Cibeunying Kidul” sebagai “Cibenying”, kode posnya kosong, dan ongkir tidak bisa dihitung sampai admin menelepon pembeli. Di toko dengan 30 order sehari, dua atau tiga kasus seperti ini cukup untuk membuat satu orang sibuk sepanjang sore. Form yang menerima ketikan bebas untuk alamat pada dasarnya mendelegasikan validasi ke manusia. Autocomplete memindahkannya kembali ke mesin.

💡 Jawaban Singkat: Untuk autocomplete kecamatan dan kode pos di form checkout, panggil GET https://api.agenwebsite.com/v1/locations/search?q=<teks>&limit=8 dengan header x-api-key dari server Anda. Respons berisi data.locations[] dengan subdistrict_id, subdistrict_name, district_name, city_name, province_name, postal_code, dan label. Minimal 3 karakter, debounce 300 ms, dan cache hasilnya; setiap panggilan memakai 1 kuota dari 150 per hari di paket Free.

Kenapa form alamat checkout butuh data kecamatan dan kode pos?

Karena tarif ongkir dihitung dari titik asal ke titik tujuan yang pasti, dan “Bandung” bukan titik yang pasti. Kota Bandung punya puluhan kecamatan dengan tarif kurir yang bisa berbeda, dan kode pos yang salah satu digit bisa melempar paket ke kabupaten sebelah. API ongkir mana pun, termasuk POST /v1/rates milik kami, meminta penanda tujuan yang tegas: di Rate API itu postal_code atau subdistrict_id, tepat satu di antaranya.

Masalahnya, pembeli tidak hafal kode pos mereka. Yang mereka hafal adalah nama kecamatan atau kelurahan, sering dengan ejaan versi sendiri. Jadi tugas form checkout adalah menerjemahkan ketikan yang tidak rapi itu menjadi satu baris data yang rapi, dan itu persis fungsi endpoint pencarian lokasi.

Perlu jujur soal batasnya sejak awal. /v1/locations/search adalah alat bantu untuk API ongkir, bukan database wilayah Indonesia yang lengkap. Datanya berhenti di tingkat kecamatan plus kode pos; dokumentasi kami tidak menyebut cakupan desa atau kelurahan, jadi kalau Anda butuh daftar kelurahan untuk keperluan lain (misalnya KYC atau data sensus), ini bukan endpoint yang tepat. Untuk checkout dan hitung ongkir, tingkat kecamatan itu yang dibutuhkan kurir.

Memakai /v1/locations/search untuk autocomplete

Endpoint ini menerima dua parameter: q (wajib, minimal 3 karakter, mencocokkan nama kecamatan, kota, atau kode pos) dan limit (opsional, default 10, maksimal 50). Autentikasinya sama dengan endpoint lain di Rate API, header x-api-key, dan key itu harus dipanggil dari server Anda, bukan dari JavaScript di halaman checkout.

1. Lihat dulu bentuk responsnya

curl -G https://api.agenwebsite.com/v1/locations/search \
  -H "x-api-key: awk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "q=dago" \
  --data-urlencode "limit=5"
{
  "success": true,
  "data": {
    "locations": [
      {
        "subdistrict_id": "3273091001",
        "subdistrict_name": "Dago",
        "district_name": "Coblong",
        "city_name": "Bandung",
        "province_name": "Jawa Barat",
        "postal_code": "40135",
        "label": "Dago, Coblong, Bandung, Jawa Barat 40135"
      }
    ]
  },
  "meta": { "query": "dago", "count": 1 }
}

Perhatikan limit. Default 10 cukup untuk dropdown, tapi untuk nama yang umum seperti “Sukamaju” atau “Mekarsari”, hasil yang relevan bisa ada di urutan belasan; naikkan ke 15 atau 20 untuk kasus seperti itu, dan biarkan label yang memuat kota dan provinsi membantu pembeli membedakannya. Jangan langsung 50 hanya karena bisa; dropdown 50 baris lebih sulit dipakai daripada mengetik satu huruf tambahan.

Tiga field yang akan Anda pakai: label untuk ditampilkan di dropdown, subdistrict_id untuk disimpan sebagai tujuan, dan postal_code untuk mengisi kolom kode pos di form secara otomatis. Pembeli tidak perlu lagi mengetik kode pos sama sekali.

2. Proxy kecil di server

Contoh di bawah memakai Node.js dengan Express, tapi polanya sama untuk Laravel atau Route Handler Next.js: terima q dari browser, panggil Rate API dengan key dari process.env, kembalikan hanya field yang dibutuhkan.

// server/routes/lokasi.js
import express from "express";

const router = express.Router();
const BASE_URL = process.env.AGENWEBSITE_RATE_API_URL ?? "https://api.agenwebsite.com/v1";

router.get("/api/lokasi", async (req, res) => {
  const q = String(req.query.q ?? "").trim();
  if (q.length < 3) return res.json({ locations: [] }); // jangan buang kuota untuk 1-2 huruf

  const url = new URL(`${BASE_URL}/locations/search`);
  url.searchParams.set("q", q);
  url.searchParams.set("limit", "8");

  const upstream = await fetch(url, {
    headers: { "x-api-key": process.env.AGENWEBSITE_RATE_API_KEY },
  });
  const json = await upstream.json();

  if (!upstream.ok || !json.success) {
    return res.status(upstream.status === 429 ? 429 : 502).json({
      locations: [],
      error: json?.error?.code ?? "upstream_error",
    });
  }

  res.json({
    locations: json.data.locations.map((l) => ({
      id: l.subdistrict_id,
      postal_code: l.postal_code,
      label: l.label,
    })),
  });
});

export default router;

3. Input autocomplete di browser

<input id="kecamatan" type="text" autocomplete="off" placeholder="Ketik nama kecamatan atau kode pos">
<ul id="saran"></ul>
<input type="hidden" name="destination_subdistrict_id" id="dest-id">
<input type="text" name="postal_code" id="kode-pos" readonly>
// checkout.js (browser). Tidak ada API key di sini.
const input = document.getElementById("kecamatan");
const list = document.getElementById("saran");
let timer;

input.addEventListener("input", () => {
  clearTimeout(timer);
  const q = input.value.trim();
  if (q.length < 3) { list.innerHTML = ""; return; }

  timer = setTimeout(async () => {
    const res = await fetch(`/api/lokasi?q=${encodeURIComponent(q)}`);
    const { locations } = await res.json();
    list.innerHTML = locations
      .map((l) => `<li data-id="${l.id}" data-pos="${l.postal_code}">${l.label}</li>`)
      .join("");
  }, 300);
});

list.addEventListener("click", (e) => {
  const li = e.target.closest("li");
  if (!li) return;
  input.value = li.textContent;
  document.getElementById("dest-id").value = li.dataset.id;
  document.getElementById("kode-pos").value = li.dataset.pos;
  list.innerHTML = "";
});

Sediakan juga jalan keluar kalau pencarian tidak menemukan apa-apa. Ejaan lokal, nama kecamatan baru hasil pemekaran, atau pembeli yang mengetik nama kelurahan alih-alih kecamatan bisa menghasilkan meta.count nol. Untuk kasus itu, tampilkan pesan singkat “coba nama kota atau kode pos” dan biarkan field kode pos bisa diketik manual sebagai cadangan. Kode pos manual tetap bisa dikirim ke POST /v1/rates sebagai destination.postal_code; kalau ternyata salah, API membalas 404 destination_not_found dan Anda bisa meminta pembeli mengecek ulang sebelum order tersimpan dengan alamat yang tidak bisa dihitung.

Setelah pembeli memilih, destination_subdistrict_id yang terisi itulah yang Anda kirim ke POST /v1/rates sebagai destination.subdistrict_id. Jangan kirim postal_code sekaligus; Rate API menolak kalau keduanya ada. Kalau Anda butuh contoh pemanggilan rates-nya, artikel API cek ongkir untuk Next.js membahasnya sampai ke komponen checkout.

Untuk pembaca yang masih menimbang apakah tujuan sebaiknya disimpan sebagai kode pos atau ID kecamatan, kami pernah menulis perbandingannya di ongkir berdasarkan kode pos vs kecamatan. Versi singkatnya: ID kecamatan lebih presisi, karena satu kode pos bisa menaungi lebih dari satu kecamatan.

Debounce dan cache agar kuota awet

Dua angka yang menentukan hidup matinya paket Free di sini: 150 request per hari dan 20 request per menit. Tanpa pengaman, satu pembeli yang mengetik “kecamatan cibeunying kidul” huruf demi huruf memicu lebih dari 20 panggilan dalam beberapa detik, melewati batas per menit, dan pembeli berikutnya mendapat 429 rate_limit_exceeded. Tiga lapis pengaman di bawah menurunkan angka itu drastis.

Debounce 300 ms

Kode browser di atas sudah melakukannya: tunggu 300 ms setelah ketikan terakhir, baru kirim. Dengan kecepatan mengetik normal, satu kata utuh biasanya menjadi 1 sampai 3 request alih-alih 15. Angka 300 ms adalah yang disarankan dokumentasi kami; lebih pendek terasa lebih responsif tapi boros, lebih dari 500 ms mulai terasa lambat.

Minimal 3 karakter, dan buang spasi

Server Anda sebaiknya menolak q di bawah 3 karakter sebelum menyentuh Rate API, karena endpoint-nya memang mensyaratkan itu dan Anda tidak perlu membuang satu kuota untuk mendapat 400 validation_error. Trim spasi juga, supaya “dago ” dan “dago” tidak jadi dua pencarian berbeda di cache.

Jangan memanggil saat fokus, hanya saat mengetik

Kesalahan kecil yang sering lolos review: memanggil pencarian saat field mendapat fokus atau saat halaman dimuat, misalnya untuk “memanaskan” dropdown. Setiap pembeli yang mengeklik kolom alamat lalu berubah pikiran sudah menghabiskan satu kuota tanpa mengetik apa pun. Panggil hanya dari event input, dan hanya setelah debounce selesai.

Cache di server per kata kunci

Nama kecamatan dan kode pos hampir tidak berubah. Cache hasil pencarian di server Anda dengan kunci berupa q yang sudah dinormalisasi (huruf kecil, tanpa spasi berlebih), dan simpan 24 jam. Di toko dengan pembeli yang terkonsentrasi di beberapa kota besar, kata kunci yang sama akan muncul berulang; setelah hari pertama, sebagian besar pencarian dilayani dari cache tanpa menyentuh kuota.

// Tambahan di server/routes/lokasi.js: cache in-memory sederhana, 24 jam.
// Untuk produksi dengan beberapa instance, pindahkan ke Redis dengan TTL yang sama.
const cache = new Map();
const TTL_MS = 24 * 60 * 60 * 1000;

function cacheKey(q) {
  return q.toLowerCase().replace(/\s+/g, " ");
}

// sebelum fetch ke Rate API:
const key = cacheKey(q);
const hit = cache.get(key);
if (hit && Date.now() - hit.at < TTL_MS) return res.json(hit.data);

// setelah respons sukses:
cache.set(key, { at: Date.now(), data: payload });

Angka kasarnya untuk toko 30 order per hari: tanpa pengaman, pencarian lokasi saja bisa menghabiskan ratusan request. Dengan debounce dan batas 3 karakter, biasanya turun ke 60 sampai 90. Dengan cache 24 jam di atasnya, hari kedua dan seterusnya sering di bawah 30, menyisakan ruang untuk panggilan /v1/rates yang memang tidak bisa di-cache selama itu. Angka ini perkiraan dari pola pemakaian, bukan jaminan; pantau sendiri lewat header X-RateLimit-Remaining atau GET /v1/usage.

Kalau setelah semua itu kuota masih mepet, berarti toko Anda sudah cukup ramai untuk Pro (Rp129.000/bulan, 30.000 request/hari), dan itu kabar baik. Pembahasan lebih dalam soal kuota ada di rate limiting dan kuota API ongkir.

Pertanyaan yang Sering Diajukan

Apakah endpoint lokasi memakai kuota?

Ya. Setiap panggilan GET /v1/locations/search menghitung 1 pemakaian kuota harian, sama seperti POST /v1/rates, dan tunduk pada batas per menit yang sama (20 per menit di Free). Itu sebabnya debounce dan cache bukan opsional kalau Anda memakai paket Free.

Apakah datanya mencakup desa/kelurahan?

Dokumentasi endpoint ini mencantumkan field sampai tingkat kecamatan (subdistrict_name), kabupaten/kota, provinsi, dan kode pos; tidak ada field desa atau kelurahan. Untuk menghitung ongkir, tingkat kecamatan sudah cukup bagi kurir. Kalau Anda butuh daftar kelurahan untuk keperluan non-ongkir, pakai sumber data wilayah yang memang dirancang untuk itu.

Bisakah dipakai tanpa cek ongkir?

Secara teknis bisa, karena endpoint-nya berdiri sendiri dan hanya butuh x-api-key. Tapi ia dirancang sebagai pelengkap API ongkir, bukan database wilayah umum, dan setiap panggilan tetap memakai kuota paket Anda. Untuk autocomplete alamat di checkout yang berujung pada hitung ongkir, itu pas; untuk aplikasi yang hanya butuh data wilayah, pertimbangkan sumber lain.

Berapa kuota gratisnya?

Paket Free memberi 150 request per hari dan 20 request per menit, direset setiap pukul 00:00 WIB, dengan maksimal 2 API key aktif yang berbagi kuota yang sama. Kalau pencarian lokasi plus cek ongkir Anda melewati itu, Pro Rp129.000/bulan memberi 30.000 request/hari dan Max Rp229.000/bulan memberi 60.000 request/hari.

Langkah pertama yang masuk akal

Pasang proxy /api/lokasi dengan key sandbox dan coba ketik lima nama kecamatan yang paling sering muncul di order Anda, termasuk versi salah ejanya. Kalau hasilnya cocok, pasang debounce dan cache, lalu ganti field kode pos di checkout menjadi readonly yang terisi otomatis. Sejak hari itu, tugas menelepon pembeli untuk menanyakan kode pos seharusnya hilang dari daftar admin Anda.

👉 Key Free dibuat di halaman AgenWebsite Rate API, dan detail parameter endpoint lokasi ada di dokumentasi GET /v1/locations/search.