Bab 2 · Endpoint

GET /v1/locations/search

Autocomplete kecamatan & kode pos: query param, contoh response, dan cara mengumpankan subdistrict_id / postal_code ke /v1/rates.

  • 2 menit baca
  • 6 bagian
  • Diperbarui 2 Jul 2026
Di halaman ini 6 bagian
  1. Ringkasan
  2. Query Parameter
  3. Contoh Request
  4. Contoh Response
  5. Field Response
  6. Mengumpankan Hasil ke /v1/rates

Referensi Endpoint

Ringkasan

GET /v1/locations/search adalah endpoint autocomplete untuk mencari kecamatan (subdistrict) dan kode pos di seluruh Indonesia. Pakai endpoint ini untuk membangun kolom pencarian alamat, lalu umpankan subdistrict_id atau postal_code yang dipilih pengguna ke POST /v1/rates.

Base URL: https://api.agenwebsite.com/v1 · Autentikasi lewat header x-api-key.

Query Parameter

Parameter Tipe Wajib Keterangan
q string Ya Kata kunci pencarian: nama kecamatan, kota, atau kode pos. Minimal 3 karakter.
limit integer Opsional Jumlah maksimum hasil. Default 10, maksimum 50.
Gunakan debounce (mis. 300 ms) pada input pencarian agar tidak mengirim satu request per ketikan. Setiap panggilan endpoint ini tetap menghitung 1 pemakaian kuota.

Contoh Request

Request · cURL

curl -G https://api.agenwebsite.com/v1/locations/search \
  -H "x-api-key: awk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "q=dago" \
  --data-urlencode "limit=5"

Contoh Response

Response · 200 OK

{
  "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"
      },
      {
        "subdistrict_id": "3273091002",
        "subdistrict_name": "Dago Pojok",
        "district_name": "Coblong",
        "city_name": "Bandung",
        "province_name": "Jawa Barat",
        "postal_code": "40135",
        "label": "Dago Pojok, Coblong, Bandung, Jawa Barat 40135"
      }
    ]
  },
  "meta": { "query": "dago", "count": 2 }
}

Field Response

Field Tipe Keterangan
subdistrict_id string ID unik kecamatan. Umpankan ke shipper.subdistrict_id / destination.subdistrict_id.
subdistrict_name string Nama kecamatan, mis. "Dago".
district_name string Nama kecamatan induk / distrik.
city_name string Nama kota / kabupaten.
province_name string Nama provinsi.
postal_code string Kode pos. Bisa diumpankan sebagai postal_code ke /v1/rates.
label string Alamat lengkap siap tampil di dropdown.
meta.query / meta.count string / integer Echo kata kunci & jumlah hasil.

Mengumpankan Hasil ke /v1/rates

Setelah pengguna memilih satu lokasi, ambil subdistrict_id (paling akurat) atau postal_code, lalu susun body request tarif. Untuk tiap pihak kirim salah satu saja:

Body /v1/rates — dari hasil pencarian

{
  "shipper":     { "subdistrict_id": "3273091001", "subdistrict_name": "Dago" },
  "destination": { "postal_code": "10110" },
  "weight": 1000
}
Mana yang lebih akurat? subdistrict_id menunjuk ke satu kecamatan spesifik sehingga paling presisi. postal_code praktis bila alamat pengguna hanya berupa kode pos. Menyertakan subdistrict_name membantu server memilih zona yang tepat bila satu kode pos mencakup beberapa kecamatan.

Apakah halaman ini menjawab pertanyaan Anda? Jawaban Anda membantu kami memperbaiki panduan ini.

Lainnya di bab "Endpoint"

  1. 04 POST /v1/rates — Cek Ongkir Endpoint utama cek ongkir: request body lengkap, contoh curl, response ter-branding penuh dengan penjelasan tiap field, helper termurah/tercepat.
  2. 05 GET /v1/couriers Daftar kurir yang didukung: contoh response dan tabel pemetaan courier_code ke nama kurir (J&T, Lion, SAP, SPX, J&T Cargo).
  3. 07 GET /v1/usage Pantau kuota harian: window saat ini, contoh response, dan cara memantau sisa kuota via header X-RateLimit tanpa panggilan ekstra.
Masih butuh bantuan?

Belum ketemu jawabannya?

Tanyakan ke asisten AI kami soal pengaturan plugin, error, lisensi, atau saldo: dijawab langsung. Kalau masih buntu, tim support siap membantu lewat WhatsApp.

Chat tim support

Atau lewat halaman kontak.