Lokasi

Wilayah asal dan tujuan.

Cari wilayah

GET https://api.ongkirhub.com/v1/locations

Cari kelurahan, kecamatan, kota, atau kode pos. Pakai hasilnya sebagai location pengirim dan penerima agar cocok dengan data kurir.

Akses (scope): locations:read.

Butuh kunci API (bearerAuth)

Parameter query

Parameter query
Field	Keterangan
`q` string, wajib	Kata kunci, minimal 3 karakter: nama wilayah atau kode pos.
`province` string	Batasi ke satu provinsi (nama persis, contoh Jawa Barat).
`limit` integer	Jumlah hasil.

Contoh permintaan

curl -X GET "https://api.ongkirhub.com/v1/locations?q=coblong" \
  -H "Authorization: Bearer ohk_test_xxx"

Respons

200 Wilayah yang cocok.

X-Request-Id: ID permintaan untuk dukungan.
RateLimit-Limit: Batas permintaan per jendela waktu.
RateLimit-Remaining: Sisa permintaan di jendela waktu ini.
RateLimit-Reset: Detik sampai jendela waktu berikutnya.

Field respons 200
Field	Keterangan
`data` array<Location>, wajib	-
`hasMore` boolean, wajib	Masih ada data setelah halaman ini.
`nextCursor` string \| null, wajib	Kirim sebagai parameter `cursor` untuk halaman berikutnya. Null di halaman terakhir.

{
  "data": [
    {
      "province": "Jawa Barat",
      "city": "Bandung",
      "district": "Coblong",
      "subdistrict": "Cipaganti",
      "zipcode": "40131"
    },
    {
      "province": "Jawa Barat",
      "city": "Bandung",
      "district": "Coblong",
      "subdistrict": "Dago",
      "zipcode": "40135"
    },
    {
      "province": "Jawa Barat",
      "city": "Bandung",
      "district": "Coblong",
      "subdistrict": "Lebak Gede",
      "zipcode": "40132"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

401 Kunci API tidak dikirim, tidak valid, atau sudah dicabut.

X-Request-Id: ID permintaan untuk dukungan.

{
  "error": {
    "code": "unauthenticated",
    "message": "Kunci API tidak valid, sudah dicabut, atau tidak dikirim. Kirim header Authorization: Bearer <kunci API>.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}

403 Kunci API tidak punya akses (scope) untuk endpoint ini.

X-Request-Id: ID permintaan untuk dukungan.
RateLimit-Limit: Batas permintaan per jendela waktu.
RateLimit-Remaining: Sisa permintaan di jendela waktu ini.
RateLimit-Reset: Detik sampai jendela waktu berikutnya.

{
  "error": {
    "code": "forbidden",
    "message": "Kunci API ini tidak punya akses ke endpoint ini. Tambahkan akses yang dibutuhkan di menu Developer.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
    "details": {
      "requiredScope": "shipments:write"
    }
  }
}

422 Isi permintaan belum valid.

X-Request-Id: ID permintaan untuk dukungan.
RateLimit-Limit: Batas permintaan per jendela waktu.
RateLimit-Remaining: Sisa permintaan di jendela waktu ini.
RateLimit-Reset: Detik sampai jendela waktu berikutnya.

{
  "error": {
    "code": "validation_error",
    "message": "Ada data yang belum lengkap atau belum sesuai. Periksa lagi isianmu.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
    "details": {
      "fields": [
        {
          "path": "receiver.location.zipcode",
          "message": "Kode pos harus 5 digit"
        }
      ]
    }
  }
}

429 Batas permintaan terlampaui.
X-Request-Id

ID permintaan untuk dukungan.

RateLimit-Limit

Batas permintaan per jendela waktu.

RateLimit-Remaining

Sisa permintaan di jendela waktu ini.

RateLimit-Reset

Detik sampai jendela waktu berikutnya.

Retry-After

Detik sampai boleh mencoba lagi.
```
{
  "error": {
    "code": "rate_limited",
    "message": "Terlalu banyak permintaan. Tunggu sebentar, lalu coba lagi.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
    "details": {
      "retryAfterSec": 21
    }
  }
}
```
500 Kesalahan di sistem OngkirHub. Aman dicoba ulang dengan Idempotency-Key yang sama.
X-Request-Id

ID permintaan untuk dukungan.

RateLimit-Limit

Batas permintaan per jendela waktu.

RateLimit-Remaining

Sisa permintaan di jendela waktu ini.

RateLimit-Reset

Detik sampai jendela waktu berikutnya.
```
{
  "error": {
    "code": "internal_error",
    "message": "Terjadi kesalahan di sistem kami. Coba lagi sebentar lagi.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}
```

503 Layanan pengiriman sedang gangguan atau pembuatan resi sedang dijeda. Coba lagi nanti.

X-Request-Id: ID permintaan untuk dukungan.
RateLimit-Limit: Batas permintaan per jendela waktu.
RateLimit-Remaining: Sisa permintaan di jendela waktu ini.
RateLimit-Reset: Detik sampai jendela waktu berikutnya.

Layanan pengiriman gangguan

{
  "error": {
    "code": "service_unavailable",
    "message": "Layanan pengiriman sedang gangguan. Coba lagi beberapa saat lagi.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}

Pembuatan resi dijeda

{
  "error": {
    "code": "booking_disabled",
    "message": "Pembuatan resi sedang dijeda sementara. Cek ongkir dan cek resi tetap bisa dipakai.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}

504 Layanan pengiriman lambat merespons. Coba lagi.
X-Request-Id

ID permintaan untuk dukungan.

RateLimit-Limit

Batas permintaan per jendela waktu.

RateLimit-Remaining

Sisa permintaan di jendela waktu ini.

RateLimit-Reset

Detik sampai jendela waktu berikutnya.
```
{
  "error": {
    "code": "service_timeout",
    "message": "Layanan pengiriman sedang lambat. Coba lagi sebentar lagi.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}
```

Skema objek

Objek yang dipakai di halaman ini, dijelaskan sekali di sini.

Location

Wilayah tujuan atau asal. Ambil dari GET /v1/locations agar cocok dengan data kurir.

Field objek Location
Field	Keterangan
`province` string, wajib	Provinsi, ditulis persis seperti hasil GET /v1/locations.
`city` string, wajib	Kota atau kabupaten.
`district` string, wajib	Kecamatan.
`subdistrict` string, wajib	Kelurahan atau desa.
`zipcode` string, wajib	Kode pos 5 digit. pola ^\d{5}$