API Documentation

Returns the list of all 63 former provinces/cities, with district and ward counts for each.

Example request

curl https://sapnhap.d4t0.com/api/v1/provinces

Example response

[
  { "name": "Thành phố Hà Nội", "slug": "ha-noi", "districtCount": 30, "wardCount": 794 },
  { "name": "Tỉnh Hà Giang", "slug": "ha-giang", "districtCount": 11, "wardCount": 196 },
  ...
]

Returns the old districts/wards of a province, with the matching new province/ward after the merger. Get slug from the /api/v1/provinces endpoint above.

Example request

curl https://sapnhap.d4t0.com/api/v1/provinces/da-nang

Example response

[
  {
    "district": "Quận Hải Châu",
    "wards": [
      { "ward": "Phường Thanh Bình", "newProvince": "Thành phố Đà Nẵng", "newWard": "Phường Hải Châu" },
      ...
    ]
  },
  ...
]

Look up a single old address (Province, District, Ward) and get back the matching new address.

Param	Required	Description
province	Yes	Old province name (e.g. "Thành phố Đà Nẵng") or slug (e.g. "da-nang")
district	Yes	Old district name, e.g. "Quận Hải Châu"
ward	Yes	Old ward name, e.g. "Phường Thanh Bình"

Example request

curl "https://sapnhap.d4t0.com/api/v1/lookup?province=da-nang&district=Qu%E1%BA%ADn%20H%E1%BA%A3i%20Ch%C3%A2u&ward=Ph%C6%B0%E1%BB%9Dng%20Thanh%20B%C3%ACnh"

Example response

{
  "old": {
    "province": "Thành phố Đà Nẵng",
    "district": "Quận Hải Châu",
    "ward": "Phường Thanh Bình"
  },
  "new": {
    "province": "Thành phố Đà Nẵng",
    "ward": "Phường Hải Châu"
  }
}

On no match (404)

{ "error": "Ward not found: ..." }

Some old wards were split across multiple new units during the merger. In that case new.ward is the recommended new unit (main area/population), and the response includes new.alternativeWards listing the other new units that part of the old ward also belongs to.

Example response for a split ward

{
  "old": {
    "province": "Thành phố Hà Nội",
    "district": "Huyện Thanh Trì",
    "ward": "Thị trấn Văn Điển"
  },
  "new": {
    "province": "Thành phố Hà Nội",
    "ward": "Xã Thanh Trì",
    "alternativeWards": ["Phường Hoàng Liệt", "Xã Đại Thanh"]
  }
}

{ "error": "Too many requests, slow down." }