Malaysia Postcode API

Resolve a Malaysian postcode to its state and city/town.

Authentication

All /v1 endpoints require an X-API-Key header. Keys are rate-limited per minute.

Endpoints

MethodPathDescription
GET/healthzLiveness probe (public)
GET/v1/postcodes/{postcode}Lookup one postcode
GET/v1/postcodes?state=&city=Filtered list
GET/v1/statesDistinct state names

Example

curl -H "X-API-Key: YOUR_KEY" \
  http://localhost:8080/v1/postcodes/01000

{
  "postcode": "01000",
  "state": "PERLIS",
  "city": "Kangar"
}

Data seeded from lomotech/jajahan. "city" is the post-office locality, not the land-authority district.