Skip to Content
FastracDocs

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.
  1. 1subdistrictId
    You are here

    YouShipping Engine

    Find the region

    Turn each address into the ID of its subdistrict.

    GET/b2b/region/find

  2. 2shippingRateCode

    YouShipping Engine

    Get rates

    Describe the parcel and route. Get a price from every courier.

    POST/b2b/shipping-rate

  3. 3airwayBill

    YouShipping Engine

    Create the order

    Book the rate your customer picked. The courier is booked for you.

    POST/b2b/orders

  4. 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.

LevelIndonesianExampleAPI name
1ProvinsiDKI Jakartaprovince
2Kota / KabupatenKota Jakarta Selatancity
3KecamatanTebetdistrict
4Kelurahan / DesaTebet Baratsubdistrict

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

MethodEndpointBest forWatch out for
SearchGET /b2b/region/findAutocomplete as the customer types. One call.Returns several matches; let the customer choose.
Postal codeGET /b2b/region/postCodeForms that already ask for a postal code.One postal code usually covers several subdistricts.
Drill-downprovince → city → district → subdistrictFour dropdown menus, or importing a full list.Four calls per address.

None of the region endpoints needs a token.

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"
InboundResponse
{
  "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"
InboundResponse (trimmed)
{
  "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

  1. Wait until the customer has typed at least 3 characters, and for a pause of about 300 ms, before you search.
  2. Call GET /b2b/region/find?keyword=…&limit=10 and show each name.
  3. When the customer picks one, store its id as subdistrictId and its postCode with the address.
  4. Ask for the street, house number and RT/RW in a separate free-text field: that becomes fullAddress.
  5. 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:

WhenWhereFormat
Instant couriers price by distanceorigin.coordinate and every destinations[].coordinate in the rate requestNumbers: { "latitude": -6.2297, "longitude": 106.8536 }
Pickup by a regular couriersender.coordinate in POST /b2b/ordersStrings: { "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 subdistrictId with 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?

On this page