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.