Trang chủ Dashboard Demo API Ranh Giới Hành Chính Status

Đến với chúng tôi

Phản hồi, hợp tác hoặc hỗ trợ kỹ thuật

Giới thiệu GeoVina API

GeoVina API là nền tảng giải mã, chuẩn hóa và chuyển đổi hai chiều đơn vị hành chính tốt nhất Việt Nam. Hệ thống sở hữu khả năng tự động nhận diện thông minh dữ liệu đầu vào là địa chỉ hệ cũ (trước sáp nhập) hay hệ mới (sau sáp nhập) mà không cần chỉ định trước, qua đó tự động xử lý và trả về song song cả 2 định dạng chuẩn xác.

Giải pháp thiết yếu không chỉ cho các hệ thống quản trị CRM, ERP, E-commerce, Logistic truyền thống mà còn đặc biệt tối ưu cho nền tảng bất động sản (Proptech), dịch vụ cho thuê trọ, tổ chức sự kiện và chia sẻ thông tin doanh nghiệp.

Ngoài chuyển đổi địa chỉ, GeoVina còn cung cấp API Ranh Giới Hành Chính — trả về dữ liệu GeoJSON polygon của từng quận/huyện và phường/xã, giúp các ứng dụng bản đồ (Goong Maps, Mapbox, Leaflet…) dễ dàng vẽ ranh giới địa lý trực quan. Xem trang demo bản đồ để trải nghiệm trực tiếp.

Cực Nhanh

Phản hồi dưới 10ms qua Edge Network. Tự động cache, không cần thiết lập.

Dữ liệu Chuẩn

Data hoàn chỉnh và mới nhất, luôn sync với Tổng cục Thống kê (GSO).

Bảo Mật

Chống lạm dụng và phân quyền chặt chẽ bằng API Key.

Đa Dạng

Xử lý địa chỉ tự do, tọa độ GPS, chuẩn hóa văn bản dán tự động.

Lợi thế Caching tự động

GeoVina tích hợp sẵn cơ chế cache thông minh tại lớp Edge Network. Khi một địa chỉ hoặc tọa độ được tra cứu, kết quả sẽ được lưu trữ và phục vụ miễn phí cho lần truy vấn tiếp theo (bởi chính bạn hoặc bất kỳ người dùng nào khác trong hệ thống).

Bạn không cần thiết lập gì thêm: Tính năng cache tự động đã được kích hoạt mặc định cho mọi tài khoản. Hệ thống sẽ tự động nhận diện kết quả đã tồn tại và trả về ngay lập tức với chi phí 0 xu.

Xác thực & Bảo mật

Để truy cập API, bạn cần gửi kèm header X-Api-Key trong tất cả các request.

Lưu ý quan trọng: Luôn gọi API từ môi trường Server-side (ví dụ: Next.js Server Actions, Node.js, PHP, Python) để bảo mật API Key. Không gọi trực tiếp từ trình duyệt của người dùng cuối (Client-side) trừ khi dùng proxy.

Ví dụ xác thực (cURL)

curl -X POST https://geovina.io.vn/api/parse \\
  -H "Content-Type: application/json" \\
  -H "X-Api-Key: your_super_secret_key" \\
  -d '{"address": "123 Lê Lợi, Bến Nghé, Quận 1, TP.HCM"}'

API Reference

POST GET /parse
Phân tích một địa chỉ duy nhất

Parameters (Body / Query)

address *
string (3 - 300 chars)
Địa chỉ văn bản tự do cần phân tích.

Ví dụ Request

{
  "address": "50 Cao Thắng, Phường 5, Quận 3, Thành phố Hồ Chí Minh"
}

Response Thành Công (200 OK) 

{
  "success": true,
  "data": {
    "input": "50 Cao Thắng, Phường 5, Quận 3, Thành phố Hồ Chí Minh",
    "mode": "old_to_new",
    "parsed_province_raw": "Thành Phố Hồ Chí Minh",
    "parsed_district_raw": "Quận 3",
    "parsed_ward_raw": "Phường 5",
    "address_prefix": "50 Cao Thắng",
    "old_province": {
      "id": "79",
      "name": "TP. Hồ Chí Minh",
      "level": "Thành phố"
    },
    "old_district": {
      "id": "770",
      "name": "3",
      "level": "Quận",
      "province_id": "79"
    },
    "old_ward": {
      "id": "27151",
      "name": "05",
      "level": "Phường",
      "district_id": "770",
      "province_id": "79"
    },
    "new_province": {
      "id": "79",
      "name": "TP. Hồ Chí Minh",
      "level": "Thành phố",
      "merged_from_province_ids": [ "74", "77", "79" ],
      "merged_from_province_names": [ "Bình Dương", "Bà Rịa - Vũng Tàu", "Hồ Chí Minh" ]
    },
    "matched_ward": {
      "id": "27154",
      "name": "Bàn Cờ",
      "level": "Phường",
      "province_id": "79",
      "province_name": "TP. Hồ Chí Minh",
      "merged_from_district_ids": [ "770" ],
      "merged_from_district_names": [ "3" ],
      "merged_from_ward_ids": [ "27148", "27151", "27154", "27157", "27160" ],
      "merged_from_ward_names": [ "4", "5", "3", "2", "1" ]
    },
    "matched_wards": [ /* Giống matched_ward */ ],
    "matched_new_ward": { /* Giống matched_ward */ },
    "new_wards": [ /* Mảng các phường liên quan nếu address mơ hồ */ ],
    "ward_level_old_address": "Phường 5, Quận 3, TP. Hồ Chí Minh",
    "ward_level_new_address": "Phường Bàn Cờ, TP. Hồ Chí Minh",
    "full_old_address": "50 Cao Thắng, Phường 5, Quận 3, TP. Hồ Chí Minh",
    "full_new_address": "50 Cao Thắng, Phường Bàn Cờ, TP. Hồ Chí Minh",
    "warnings": []
  }
}
POST GET /reverse
Dịch ngược tọa độ (Reverse Geocoding)

Parameters (Body / Query)

lat *
number / string
Vĩ độ (Latitude) nằm trong lãnh thổ Việt Nam.
lng *
number / string
Kinh độ (Longitude) nằm trong lãnh thổ Việt Nam.

Ví dụ Request

{
  "lat": 10.776715,
  "lng": 106.70322
}

Response Thành Công (200 OK) 

{
  "success": true,
  "data": {
    "input": {
      "lat": 10.776715,
      "lng": 106.70322
    },
    "resolution_mode": "latlng",
    "address_prefix": "Nhà hát Thành phố Hồ Chí Minh, 7 Công Trường Lam Sơn",
    "full_old_address": "Nhà hát Thành phố Hồ Chí Minh, 7 Công Trường Lam Sơn, Phường Bến Nghé, Quận 1, Thành phố Hồ Chí Minh",
    "full_new_address": "Nhà hát Thành phố Hồ Chí Minh, 7 Công Trường Lam Sơn, Phường Sài Gòn, Thành phố Hồ Chí Minh",
    "old_ward": {
      "id": "26740",
      "name": "Phường Bến Nghé",
      "district_id": "760",
      "province_id": "79",
      "source": "postgis"
    },
    "old_district": {
      "id": "760",
      "name": "1",
      "level": "Quận",
      "province_id": "79"
    },
    "old_province": {
      "id": "79",
      "name": "Hồ Chí Minh",
      "level": "Thành phố"
    },
    "new_province": {
      "id": "79",
      "name": "Hồ Chí Minh",
      "level": "Thành phố",
      "merged_from_province_ids": [ "74", "77", "79" ],
      "merged_from_province_names": [ "Bình Dương", "Bà Rịa - Vũng Tàu", "Hồ Chí Minh" ]
    },
    "matched_new_ward": {
      "id": "26740",
      "name": "Sài Gòn",
      "level": "Phường",
      "province_id": "79",
      "province_name": "Hồ Chí Minh",
      "merged_from_district_ids": [ "760" ],
      "merged_from_district_names": [ "1" ],
      "merged_from_ward_ids": [ "26737", "26740", "26746" ],
      "merged_from_ward_names": [ "Đa Kao", "Bến Nghé", "Nguyễn Thái Bình" ]
    },
    "new_wards": [ /* Danh sách các phường đối chiếu liên quan */ ],
    "ward_level_old_address": "Phường Bến Nghé, Quận 1, Thành phố Hồ Chí Minh",
    "ward_level_new_address": "Phường Sài Gòn, Thành phố Hồ Chí Minh",
    "warnings": []
  }
}
POST /batch-reverse
Giải mã nhiều tọa độ cùng lúc
Tối đa 50 điểm tọa độ mỗi request. (Format linh hoạt: chuỗi text, hoặc {lat, lng})

Parameters (JSON Body)

coords *
Array<any>
Mảng điểm nhận. Hỗ trợ 2 định dạng:
  • String (VD: "10.7769, 106.7009", "lat=10.7 lng=106.7", ...)
  • Object (VD: {"lat": 10.7769, "lng": 106.7009})

Ví dụ Request

{
  "coords": [
    "10.776715, 106.703220",
    "10.769545, 106.682818"
  ]
}

Response Thành Công (200 OK) 

{
  "success": true,
  "count": 2,
  "data": [
    {
      "input": { "lat": 10.776715, "lng": 106.70322 },
      "resolution_mode": "latlng",
      "address_prefix": "Nhà hát Thành phố Hồ Chí Minh, 7 Công Trường Lam Sơn",
      "full_old_address": "Nhà hát Thành phố Hồ Chí Minh, 7 Công Trường Lam Sơn, Phường Bến Nghé, Quận 1, TPHCM",
      "full_new_address": "Nhà hát Thành phố Hồ Chí Minh, 7 Công Trường Lam Sơn, Phường Sài Gòn, TPHCM",
      "old_ward": {
        "id": "26740",
        "name": "Phường Bến Nghé",
        "district_id": "760",
        "province_id": "79",
        "source": "postgis"
      },
      "old_district": {
        "id": "760",
        "name": "1",
        "level": "Quận",
        "province_id": "79"
      },
      "old_province": {
        "id": "79",
        "name": "Hồ Chí Minh",
        "level": "Thành phố"
      },
      "new_province": {
        "id": "79",
        "name": "Hồ Chí Minh",
        "level": "Thành phố",
        "merged_from_province_ids": [ "74", "77", "79" ],
        "merged_from_province_names": [ "Bình Dương", "Bà Rịa - Vũng Tàu", "Hồ Chí Minh" ]
      },
      "matched_new_ward": {
        "id": "26740",
        "name": "Sài Gòn",
        "level": "Phường",
        "province_id": "79",
        "province_name": "Hồ Chí Minh",
        "merged_from_district_ids": [ "760" ],
        "merged_from_district_names": [ "1" ],
        "merged_from_ward_ids": [ "26737", "26740", "26746" ],
        "merged_from_ward_names": [ "Đa Kao", "Bến Nghé", "Nguyễn Thái Bình" ]
      },
      "new_wards": [ /* ... Danh sách ... */ ]
    },
    {
      "input": { "lat": 10.769545, "lng": 106.682818 },
      "resolution_mode": "latlng",
      "address_prefix": "50 Cao Thắng",
      "full_old_address": "50 Cao Thắng, Phường 5, Quận 3, Thành phố Hồ Chí Minh",
      "full_new_address": "50 Cao Thắng, Phường Bàn Cờ, Thành phố Hồ Chí Minh",
      /* ... Các block chi tiết về phường cũ (Phường 5) -> phường mới (Bàn Cờ) ... */
    }
  ]
}

API Ranh Giới Hành Chính

Endpoint trả về dữ liệu ranh giới địa lý dạng GeoJSON — dùng để vẽ polygon trên bản đồ (Goong Maps, Mapbox, Leaflet, Google Maps, v.v.).

GET /boundaries
Ranh giới quận/huyện & phường/xã (GeoJSON)
Trả về GeoJSON FeatureCollection với dữ liệu polygon. Kết quả được cache tự động trong memory.

Query Parameters

type *
"district" | "ward"
district — ranh giới hợp nhất của từng quận/huyện được chọn.
ward — ranh giới từng phường/xã mới bên trong các quận/huyện đó.
district_ids *
string (CSV)
Danh sách mã quận/huyện cũ (3 chữ số), phân cách bằng dấu phẩy. Tối đa 3 quận/huyện. VD: "001,002,003"

Ví dụ Request (cURL)

# type=district: vùng hợp nhất của quận Ba Đình (001)
curl "https://geovina.io.vn/boundaries?type=district&district_ids=001" \
  -H "X-Api-Key: your_key"

# type=ward: phường/xã mới trong Ba Đình + Hoàn Kiếm
curl "https://geovina.io.vn/boundaries?type=ward&district_ids=001,002" \
  -H "X-Api-Key: your_key"

Response Thành Công (200 OK) 

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [ /* mảng tọa độ polygon */ ]
      },
      "properties": {
        "old_district_id": "001",
        "new_ward_name": "Ba Đình",
        "ward_code": "00004"
      }
    }
  ],
  "meta": {
    "query_type": "ward",
    "district_ids": [ "001", "002" ],
    "feature_count": 42,
    "cached": false,
    "generated_at": "2026-04-26T13:00:00.000Z"
  }
}

Ví dụ tích hợp (JavaScript / Goong Maps)

// Fetch ranh giới và vẽ polygon lên Goong Map
const res = await fetch(
  'https://geovina.io.vn/boundaries?type=ward&district_ids=001,002',
  { headers: { 'X-Api-Key': 'YOUR_KEY' } }
);
const geojson = await res.json();

map.addSource('boundary', { type: 'geojson', data: geojson });
map.addLayer({ id: 'boundary-fill', type: 'fill', source: 'boundary',
  paint: { 'fill-color': '#8b5cf6', 'fill-opacity': 0.2 } });
map.addLayer({ id: 'boundary-line', type: 'line', source: 'boundary',
  paint: { 'line-color': '#8b5cf6', 'line-width': 2.5 } });
GET /new-boundaries Mới
Ranh giới tỉnh/TP & phường/xã sau sáp nhập (GeoJSON)
Hệ hành chính sau sáp nhập không có cấp quận/huyện. Chỉ có 2 cấp: Tỉnh/TP mới (34 đơn vị) và Phường/Xã mới. Ranh giới được cache tự động trong memory.

Query Parameters

type *
"new-province" | "new-ward"
new-province — ranh giới polygon tỉnh/TP mới (sau sáp nhập).
new-ward — ranh giới từng phường/xã mới bên trong các tỉnh/TP đã chọn.
province_ids *
string (CSV)
Danh sách mã tỉnh/TP mới (2 chữ số), phân cách bằng dấu phẩy. Tối đa 3 tỉnh/TP. VD: "79,01,48"

Ví dụ Request (cURL)

# type=new-province: ranh giới tỉnh TP.HCM mới (mã 79)
curl "https://geovina.io.vn/new-boundaries?type=new-province&province_ids=79" \
  -H "X-Api-Key: your_key"

# type=new-ward: phường/xã mới trong Hà Nội + Đà Nẵng
curl "https://geovina.io.vn/new-boundaries?type=new-ward&province_ids=01,48" \
  -H "X-Api-Key: your_key"

Response Thành Công (200 OK) 

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [ /* tọa độ polygon */ ]
      },
      "properties": {
        /* type=new-province: */
        "province_id": "79",
        "province_name": "TP. Hồ Chí Minh",
        "province_level": "Thành phố Trung ương"

        /* type=new-ward: */
        "ward_id": "26740",
        "ward_name": "Sài Gòn",
        "province_id": "79"
      }
    }
  ],
  "meta": {
    "query_type": "new-ward",
    "province_ids": [ "01", "48" ],
    "feature_count": 312,
    "cached": false
  }
}

Ví dụ tích hợp (JavaScript / Goong Maps)

// Fetch ranh giới tỉnh TP.HCM mới và vẽ polygon
const res = await fetch(
  'https://geovina.io.vn/new-boundaries?type=new-province&province_ids=79',
  { headers: { 'X-Api-Key': 'YOUR_KEY' } }
);
const geojson = await res.json();

map.addSource('boundary', { type: 'geojson', data: geojson });
map.addLayer({ id: 'boundary-fill', type: 'fill', source: 'boundary',
  paint: { 'fill-color': '#14b8a6', 'fill-opacity': 0.2 } });
map.addLayer({ id: 'boundary-line', type: 'line', source: 'boundary',
  paint: { 'line-color': '#14b8a6', 'line-width': 2 } });

API Danh mục Hành chính

Các endpoint tra cứu dữ liệu hành chính tĩnh. Kết quả được cache toàn phần — phản hồi dưới 10ms cho các warm instance.

GET /old-provinces
Danh sách tất cả tỉnh/thành cũ (trước sáp nhập)

Không có tham số. Trả về toàn bộ 63 tỉnh/thành trước khi sáp nhập.

Ví dụ Request (cURL)

curl https://geovina.io.vn/old-provinces \\
  -H "X-Api-Key: your_key"

Response (200 OK)

{
  "success": true,
  "total": 63,
  "data": [
    {
      "id": "01",
      "name": "Hà Nội",
      "level": "Thành phố Trung ương"
    },
    /* ... 62 phần tử còn lại ... */
  ]
}
GET /old-districts
Danh sách quận/huyện cũ theo tỉnh/thành

Query Parameters

province_id *
string (số)
ID tỉnh/thành cũ. VD: "01" (Hà Nội), "79" (Hồ Chí Minh). Phải tồn tại trong danh sách tỉnh/thành cũ.

Ví dụ Request

curl "https://geovina.io.vn/old-districts?province_id=01" \\
  -H "X-Api-Key: your_key"

Response (200 OK)

{
  "success": true,
  "province_id": "01",
  "total": 30,
  "data": [
    {
      "id": "001",
      "name": "Ba Đình",
      "level": "Quận",
      "province_id": "01",
      "province_name": "Hà Nội"
    },
    /* ... */
  ]
}
GET /old-wards
Danh sách phường/xã cũ theo quận/huyện

Query Parameters

district_id *
string (số)
ID quận/huyện cũ. VD: "001" (Ba Đình, Hà Nội), "760" (Quận 1, TPHCM). Phải tồn tại trong danh sách quận/huyện cũ.

Ví dụ Request

curl "https://geovina.io.vn/old-wards?district_id=001" \\
  -H "X-Api-Key: your_key"

Response (200 OK)

{
  "success": true,
  "district_id": "001",
  "total": 14,
  "data": [
    {
      "id": "00001",
      "name": "Phường Phúc Xá",
      "district_id": "001",
      "district_name": "Quận Ba Đình",
      "province_id": "01",
      "province_name": "Thành phố Hà Nội"
    },
    /* ... */
  ]
}
GET /new-provinces
Danh sách tất cả tỉnh/thành mới (sau sáp nhập)

Không có tham số. Trả về toàn bộ tỉnh/thành sau sáp nhập, bao gồm thông tin các tỉnh/thành cũ đã được hợp nhất.

Ví dụ Request

curl https://geovina.io.vn/new-provinces \\
  -H "X-Api-Key: your_key"

Response (200 OK)

{
  "success": true,
  "total": 34,
  "data": [
    {
      "id": "01",
      "name": "Hà Nội",
      "level": "Thành phố Trung ương",
      "merged_from_province_ids": [ "01" ],
      "merged_from_province_names": [ "Hà Nội" ]
    },
    /* ... */
  ]
}
GET /new-wards
Danh sách phường/xã mới theo tỉnh/thành mới

Query Parameters

province_id *
string (số)
ID tỉnh/thành mới. VD: "01" (Hà Nội), "79" (Hồ Chí Minh). Phải tồn tại trong danh sách tỉnh/thành mới.

Ví dụ Request

curl "https://geovina.io.vn/new-wards?province_id=01" \\
  -H "X-Api-Key: your_key"

Response (200 OK)

{
  "success": true,
  "province_id": "01",
  "total": 126,
  "data": [
    {
      "id": "00004",
      "name": "Ba Đình",
      "level": "Phường",
      "province_id": "01",
      "province_name": "Hà Nội",
      "merged_from_district_ids": [ "001", "002", "003" ],
      "merged_from_district_names": [ "Ba Đình", "Hoàn Kiếm", "Tây Hồ" ],
      "merged_from_ward_ids": [ "00004", /* ... */ ],
      "merged_from_ward_names": [ "Trúc Bạch", /* ... */ ]
    },
    /* ... */
  ]
}

Mã lỗi HTTP

Status Code Ý nghĩa Mô tả
400 Bad Request Thiếu tham số bắt buộc, sai định dạng JSON, tọa độ không hợp lệ.
401 Unauthorized Không cung cấp hoặc cung cấp sai X-Api-Key.
413 Payload Too Large Nội dung request (Body) vượt quá giới hạn.
429 Too Many Requests Gọi API quá nhanh. Vui lòng chờ trước khi thử lại (Rate Limit).
500 Internal Error Lỗi hệ thống hoặc ngoại lệ trong tính toán GIS.