Resolve Location

Loading...

Cho một điểm toạ độ WGS84, API trả về đơn vị hành chính chứa điểm đó. Điểm nằm trên đường biên vẫn được tính là thuộc đơn vị hành chính đó.

Phiên bản dữ liệu

Endpoint này chỉ hoạt động trên dữ liệu sau sáp nhập 2025 — request phải mang một data_version thuộc nhóm này, truyền bằng query parameter data_version hoặc header X-Data-Version. Danh sách mã đang phục vụ: Data Versions.

Tham số

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
location	string	Có	—	Toạ độ dạng lat,lng, ví dụ 21.0278,105.8342
resolveToLevel	string	Không	ward	Mức phân giải: province hoặc ward
data_version	string	Không	—	Mã phiên bản dữ liệu sau sáp nhập — xem Data Versions; không truyền thì request rơi về bộ legacy và nhận 404

Hành vi theo resolveToLevel

Giá trị	Kết quả
ward (mặc định)	Tìm cả tỉnh/thành phố và phường/xã chứa toạ độ
province	Chỉ tìm tỉnh/thành phố; trường ward luôn trả null

Khi không tìm thấy tỉnh/thành phố nào chứa điểm, toàn bộ data trả về null — kể cả khi resolveToLevel=ward. Endpoint này không báo lỗi cho trường hợp không tìm thấy.

Yêu cầu mẫu

Phân giải tới cấp phường/xã (mặc định):

Loading API request...

Chỉ phân giải tới cấp tỉnh/thành phố:

Loading API request...

Phản hồi

Toạ độ nằm trong cả tỉnh/thành phố và phường/xã

{
  "status": "OK",
  "data": {
    "province": {
      "prov_code": "01",
      "prov_name": "Hà Nội",
      "prov_fname": "Thành phố Hà Nội",
      "prov_ne": "Ha Noi",
      "prov_fne": "Ha Noi City",
      "level": "Thành phố Trung ương"
    },
    "ward": {
      "ward_code": "00190",
      "ward_name": "Ô Chợ Dừa",
      "ward_fname": "Phường Ô Chợ Dừa",
      "ward_ne": "O Cho Dua",
      "ward_fne": "O Cho Dua Ward",
      "level": "Phường"
    }
  },
  "meta": { "data_version": "2025-07.r2" },
  "licence": "© GTEL Maps"
}

resolveToLevel=province — chỉ trả về tỉnh/thành phố

{
  "status": "OK",
  "data": {
    "province": {
      "prov_code": "01",
      "prov_name": "Hà Nội",
      "prov_fname": "Thành phố Hà Nội",
      "prov_ne": "Ha Noi",
      "prov_fne": "Ha Noi City",
      "level": "Thành phố Trung ương"
    },
    "ward": null
  },
  "meta": { "data_version": "2025-07.r2" },
  "licence": "© GTEL Maps"
}

Toạ độ không nằm trong đơn vị hành chính nào

{
  "status": "OK",
  "data": null,
  "meta": { "data_version": "2025-07.r2" },
  "licence": "© GTEL Maps"
}

Lỗi thường gặp

HTTP	Tình huống
400	Giá trị tham số không hợp lệ — location thiếu hoặc sai định dạng, resolveToLevel sai giá trị
404	Thiếu data_version hoặc X-Data-Version