Regions and addresses
How Indonesian addresses map to a subdistrict ID, three ways to find it, and when you also need coordinates.
- Product
- APIShipping Engine API
- Section
- Core concepts
- Reading time
- 5 min read
In short
- Every origin and destination needs a
subdistrictId: the ID of its kelurahan or desa. - Find it by searching, by postal code, or by drilling down from province to subdistrict.
- Look it up once per address and store it. Add coordinates for instant couriers and for pickups.
- 1subdistrictIdYou are here
YouShipping Engine
Find the region
Turn each address into the ID of its subdistrict.
GET/b2b/region/find
- 2shippingRateCode
YouShipping Engine
Get rates
Describe the parcel and route. Get a price from every courier.
POST/b2b/shipping-rate
- 3airwayBill
YouShipping Engine
Create the order
Book the rate your customer picked. The courier is booked for you.
POST/b2b/orders
- 4
Shipping EngineYou
Track
Shipping Engine calls your webhook each time the status changes.
EVENTshipment.* webhooks
→ status
How Indonesian addresses are organised
Indonesia has four administrative levels. Shipping Engine prices and routes on the lowest one.
| Level | Indonesian | Example | API name |
|---|---|---|---|
| 1 | Provinsi | DKI Jakarta | province |
| 2 | Kota / Kabupaten | Kota Jakarta Selatan | city |
| 3 | Kecamatan | Tebet | district |
| 4 | Kelurahan / Desa | Tebet Barat | subdistrict |
A rate request needs the subdistrict, as subdistrictId, plus the street address as free text in
fullAddress:
{
"origin": {
"fullAddress": "Jl. Tebet Raya No. 12, RT 03/RW 05",
"subdistrictId": "3174091001"
}
}The fullAddress is what the courier reads. The subdistrictId is what Shipping Engine and the courier
use to price and route the parcel. They must describe the same place.
Three ways to find a subdistrict
| Method | Endpoint | Best for | Watch out for |
|---|---|---|---|
| Search | GET /b2b/region/find | Autocomplete as the customer types. One call. | Returns several matches; let the customer choose. |
| Postal code | GET /b2b/region/postCode | Forms that already ask for a postal code. | One postal code usually covers several subdistricts. |
| Drill-down | province → city → district → subdistrict | Four dropdown menus, or importing a full list. | Four calls per address. |
None of the region endpoints needs a token.
Search
Send part of the name, in any order. Results include the full path in name.
curl -s "$FASTRAC_API/b2b/region/find?keyword=tebet%20barat&limit=5"{
"statusCode": 200,
"message": "Request successful.",
"data": {
"regions": [
{ "id": "3174091001", "name": "Tebet Barat, Tebet, Kota Jakarta Selatan, DKI Jakarta", "postCode": 12810 }
],
"nextCursor": null
}
}id is the subdistrictId. limit defaults to 20 (maximum 100); use nextCursor for more
results. Leaving out keyword returns 400 Field 'keyword' is required.
Postal code
curl -s "$FASTRAC_API/b2b/region/postCode?postCode=12810"{
"statusCode": 200,
"message": "Request successful.",
"data": [
{
"provinceId": 31, "provinceName": "DKI Jakarta",
"cityId": 3174, "cityName": "Kota Jakarta Selatan",
"districtId": 317409, "district": "Tebet",
"subdistrictId": 3174091001, "subdistrict": "Tebet Barat",
"postCode": 12810
}
]
}If more than one subdistrict comes back, ask the customer to pick one. Here subdistrictId is a
number; send it as a string ("3174091001") in rate requests.
Drill-down
Each call takes the ID chosen at the level above:
curl -s "$FASTRAC_API/b2b/region/province"
curl -s "$FASTRAC_API/b2b/region/city?provinceId=31"
curl -s "$FASTRAC_API/b2b/region/district?cityId=3174"
curl -s "$FASTRAC_API/b2b/region/subdistrict?districtId=317409"The last call returns [{ "id": "3174091001", "name": "Tebet Barat", "districtId": 317409, "postCode": 12810 }, …].
The IDs on this page are examples; use the ones the API returns.
A missing or non-numeric ID returns 400 Query parameter 'cityId' is required. or … must be a valid number.
Build an address autocomplete
- Wait until the customer has typed at least 3 characters, and for a pause of about 300 ms, before you search.
- Call
GET /b2b/region/find?keyword=…&limit=10and show eachname. - When the customer picks one, store its
idassubdistrictIdand itspostCodewith the address. - Ask for the street, house number and RT/RW in a separate free-text field: that becomes
fullAddress. - If nothing matches, let the customer try a shorter keyword or the postal code.
Search from your server
The region endpoints need no token, so you can call them from your server and pass results to your front end. Keep all other Shipping Engine calls on your server.
Coordinates
Coordinates (latitude and longitude) pin the exact address. You need them in two cases:
| When | Where | Format |
|---|---|---|
| Instant couriers price by distance | origin.coordinate and every destinations[].coordinate in the rate request | Numbers: { "latitude": -6.2297, "longitude": 106.8536 } |
| Pickup by a regular courier | sender.coordinate in POST /b2b/orders | Strings: { "latitude": "-6.2297", "longitude": "106.8536" } |
Without sender coordinates, a regular pickup is rejected with Pickup shipments require sender coordinates.
For regular couriers with drop-off, coordinates are optional.
Get coordinates from a map picker or a geocoding service in your app, and save them with the address.
Cache region data
- Store the
subdistrictIdwith each saved address (customer address book, warehouse, store). Then you never look it up again for that address. - Region names and IDs rarely change. Cache search and drill-down results for a day or more.
- If you import the full list, refresh it occasionally, for example monthly.
Common mistakes
Using a district or city ID
subdistrictId must be the level-4 ID (kelurahan/desa), such as 3174091001. A kecamatan ID such as
317409 is not a subdistrict.
Address and subdistrict don't match
If fullAddress is in Bandung but subdistrictId is in Jakarta, the price is wrong and the courier
may fail to deliver. Re-check the subdistrict whenever the customer edits the address.
Guessing from the postal code
A postal code often covers several subdistricts. Taking the first one silently can pick the wrong area. Let the customer choose.
Was this page helpful?