Chuyển tới nội dung chính

Admin Unit Tile Layer

Admin Unit Tile Layer cung cấp vector tiles (PBF/MVT) về ranh giới hành chính Việt Nam và label layers để hiển thị tên đơn vị hành chính trên bản đồ. Lớp này phù hợp để build trải nghiệm tương tác như hover, selection, drill-down, và lọc theo cấp hành chính trong các ứng dụng MapLibre.

Cấp hành chính được hỗ trợ​

  • Cấp tỉnh/thành phố: polygon biên giới và điểm nhãn.
  • Cấp phường/xã/thị trấn: polygon biên giới và điểm nhãn.

Bản đồ minh hoạ​

Ví dụ trực tiếp dưới đây dùng GTEL MAPS street style (gtelmaps-streets-v1), Admin Unit Tile Layer (toàn bộ tỉnh/thành và phường/xã)

Đang tải bản đồ...

Truy xuất tile đơn vị hành chính​

Loading...

Tham số đường dẫn​

Tham sốKiểuMô tả
zintegerZoom level (mức zoom).
{x}/{y}integerChỉ định cột {x} và hàng {y} của ô bản đồ.

Các tham số {z}/{x}/{y} tuân theo chuẩn Slippy Map Tilenames.

Sử dụng API key​

Admin Unit Tile Layer yêu cầu API key qua query param:

  • Query param: apikey={YOUR_API_KEY}

MapLibre: thêm nguồn tile​

Ví dụ tile source tối thiểu (MapLibre Style Spec):

const ADMIN_UNITS_SOURCE_ID = 'admin-units';

map.addSource(ADMIN_UNITS_SOURCE_ID, {
 type: 'vector',
 tiles: [
   `{{API_BASE_URL}}/api/tiles/v1/layers/admin-units/{z}/{x}/{y}.pbf?apikey=${encodeURIComponent(YOUR_API_KEY)}`
 ],
 minzoom: 0,
 maxzoom: 14,
});

Tham chiếu lớp (layer)​

Các source-layer dưới đây là các lớp vector tile mà client sẽ tham chiếu trong addLayer. Trong môi trường production, bạn nên xác minh danh sách layer bằng TileJSON vector_layers (nếu hệ thống cung cấp endpoint tiles.json cho dataset này).

Lớp (layer)Hình họcMô tảCách dùng thường gặp
vn_provinces_pgPolygon (đa giác)Ranh giới tỉnh/thành phốVẽ biên giới cấp tỉnh; highlight khi chọn tỉnh
vn_provinces_ptPoint (điểm)Nhãn tỉnh/thành phốHiển thị tên tỉnh; tìm kiếm/hover nhãn
vn_wards_pgPolygon (đa giác)Ranh giới phường/xã/thị trấnDrill-down theo tỉnh; tô vùng cấp phường
vn_wards_ptPoint (điểm)Nhãn phường/xã/thị trấnHiển thị tên phường; gắn nhãn theo zoom

Ví dụ MapLibre cho production​

Thêm lớp biên giới tỉnh/thành​

Lớp boundary vẽ đường viền ranh giới tỉnh/thành từ polygon vn_provinces_pg (kiểu line). Đây là lớp nền hành chính cấp tỉnh: dùng cho bản đồ tổng quan. Nên interpolate line-width theo zoom để viền rõ hơn khi phóng to mà không quá đậm ở zoom thấp.

map.addLayer({
  id: 'admin-provinces-boundary',
  type: 'line',
  source: 'admin-units',
  'source-layer': 'vn_provinces_pg',
  paint: {
    'line-color': '#2b2b2b',
    'line-width': [
      'interpolate',
      ['linear'],
      ['zoom'],
      4, 0.6,
      8, 1.2,
      12, 2.0,
    ],
    'line-opacity': 0.9,
  },
});

Thêm lớp biên giới phường/xã​

Lớp boundary vẽ đường viền phường/xã/thị trấn từ polygon vn_wards_pg (kiểu line). Lớp ward có nhiều feature hơn tỉnh, nên đặt minzoom (ví dụ 8) để tránh rối ở zoom thấp; có thể interpolate line-width và line-opacity theo zoom giống demo trên trang.

map.addLayer({
  id: 'admin-wards-boundary',
  type: 'line',
  source: 'admin-units',
  'source-layer': 'vn_wards_pg',
  minzoom: 8,
  paint: {
    'line-color': '#555',
    'line-width': 0.8,
    'line-opacity': 0.7,
  },
});

Thêm điểm neo nhãn tỉnh/thành​

Lớp anchor là điểm tròn tại vị trí nhãn tỉnh/thành (vn_provinces_pt), giúp người dùng nhận diện vị trí tên trước khi đọc label. Thêm layer này trước lớp nhãn chữ để nhãn nằm phía trên anchor.

map.addLayer({
  id: 'admin-provinces-label-anchor',
  type: 'circle',
  source: 'admin-units',
  'source-layer': 'vn_provinces_pt',
  paint: {
    'circle-radius': [
      'interpolate',
      ['linear'],
      ['zoom'],
      3, 2.8,
      8, 4.4,
    ],
    'circle-color': '#2b2b2b',
    'circle-stroke-color': '#ffffff',
    'circle-stroke-width': 0.8,
    'circle-opacity': 0.9,
  },
});

Thêm nhãn tỉnh/thành​

Lớp label hiển thị tên tỉnh/thành tại điểm vn_provinces_pt (kiểu symbol). Dùng text-field với coalesce để lấy tên từ các thuộc tính có thể có (name, ten, ten_tinh). Nên bật text halo để chữ đọc được trên nền bản đồ; đặt text-allow-overlap: false để tránh chồng nhãn. Thêm sau lớp anchor nếu bạn dùng điểm tròn làm mốc nhãn.

map.addLayer({
  id: 'admin-provinces-label',
  type: 'symbol',
  source: 'admin-units',
  'source-layer': 'vn_provinces_pt',
  layout: {
    'text-field': ['coalesce', ['get', 'name'], ['get', 'ten'], ['get', 'ten_tinh'], ''],
    'text-size': [
      'interpolate',
      ['linear'],
      ['zoom'],
      4, 10,
      8, 12,
      12, 14,
    ],
    'text-font': ['Inter Regular'],
    'text-allow-overlap': false,
    'text-ignore-placement': false,
  },
  paint: {
    'text-color': '#111',
    'text-halo-color': '#fff',
    'text-halo-width': 1.2,
  },
});

Thêm nhãn phường/xã​

Lớp label hiển thị tên phường/xã/thị trấn tại điểm vn_wards_pt (kiểu symbol). Giống tỉnh, dùng coalesce cho name, ten, ten_xa. Đặt minzoom cao hơn (ví dụ 10) vì mật độ nhãn lớn; có thể interpolate text-size theo zoom. Halo và text-allow-overlap: false giúp nhãn dễ đọc mà không che khuất toàn bản đồ.

map.addLayer({
  id: 'admin-wards-label',
  type: 'symbol',
  source: 'admin-units',
  'source-layer': 'vn_wards_pt',
  minzoom: 10,
  layout: {
    'text-field': ['coalesce', ['get', 'name'], ['get', 'ten'], ['get', 'ten_xa'], ''],
    'text-size': 11,
    'text-font': ['Inter Regular'],
    'text-allow-overlap': false,
  },
  paint: {
    'text-color': '#222',
    'text-halo-color': '#fff',
    'text-halo-width': 1.1,
  },
});