Data Versions

Dữ liệu đơn vị hành chính thay đổi theo nghị quyết của Chính phủ. Để hệ thống tích hợp không bị lệch dữ liệu giữa các lần cập nhật, Administrative API cho phép chọn một phiên bản dữ liệu cụ thể bằng tham số data_version.

Tham số này không đổi cấu trúc của trường data, chỉ đổi bộ dữ liệu được đọc.

Các phiên bản đang phục vụ

data_version	Nội dung
2025-07.r2	Dữ liệu sau sáp nhập 2025, bản biên tập 2 — bản mặc định. 2 cấp, 34 tỉnh/thành phố
2025-07.r1	Dữ liệu sau sáp nhập 2025, bản phát hành đầu. 2 cấp
legacy	Dữ liệu trước sáp nhập 2025, còn cấp quận/huyện — mặc định khi không gửi data_version. 63 tỉnh/thành phố
latest	Luôn trỏ tới bản mặc định (hiện là 2025-07.r2)

Danh sách trên có thể thay đổi — dùng GET /data-versions để lấy bản mới nhất.

Cách truyền

Cách	Ví dụ
Query parameter	?data_version=2025-07.r2
Header	X-Data-Version: 2025-07.r2

API tra cứu danh mục phiên bản

Loading...

Trả về các phiên bản dữ liệu đơn vị hành chính.

Tham số

Không có tham số nào ngoài apikey.

Yêu cầu mẫu

Loading API request...

Phản hồi

{
  "data": [
    {
      "code": "2025-07.r2",
      "resolution": "2025-07",
      "revision": 2,
      "structure": "standard",
      "label": "Standard dataset, resolution 2025-07 revision 2",
      "status": "active",
      "is_default": true,
      "effective_date": null
    },
    {
      "code": "2025-07.r1",
      "resolution": "2025-07",
      "revision": 1,
      "structure": "standard",
      "label": "Standard dataset, resolution 2025-07 revision 1",
      "status": "deprecated",
      "is_default": false,
      "effective_date": null
    },
    {
      "code": "legacy",
      "resolution": null,
      "revision": null,
      "structure": "legacy",
      "label": "Legacy dataset (vn_provinces / vn_districts / vn_wards)",
      "status": "deprecated",
      "is_default": true,
      "effective_date": null
    }
  ],
  "meta": {
    "total": 3,
    "default": { "standard": "2025-07.r2", "legacy": "legacy" }
  },
  "licence": "© GTEL Maps"
}

Mô tả các trường phản hồi

Trường	Kiểu	Mô tả
data[].code	string	Mã điền vào data_version khi gọi API
data[].resolution	string | null	Tháng nghị quyết có hiệu lực, dạng YYYY-MM (legacy không có)
data[].revision	integer | null	Lần chỉnh sửa thứ mấy của bộ dữ liệu đó
data[].structure	string	Dữ liệu 2 cấp (standard) hay 3 cấp (legacy)
data[].label	string | null	Tên gọi dễ đọc của phiên bản
data[].status	string	active là bản nên dùng, deprecated vẫn dùng được
data[].is_default	boolean	Có phải bản mặc định trong nhóm của nó hay không
data[].effective_date	string | null	Ngày nghị quyết có hiệu lực, dạng YYYY-MM-DD
meta.total	integer	Số phiên bản đang phục vụ
meta.default.standard	string	Bản mặc định của dữ liệu 2 cấp, cũng là bản latest trỏ tới
meta.default.legacy	string	Bản mặc định của dữ liệu 3 cấp, dùng khi không gửi data_version