GeoVina API

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.

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 Bàn Cờ, Thành phố Hồ Chí Minh"
}

Response Thành Công (200 OK) 

{
  "success": true,
  "data": {
    "input": "50 Cao Thắng, Phường Bàn Cờ, Thành phố Hồ Chí Minh",
    "mode": "new_to_old",
    "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",
    "old_ward": {
      "id": "27202",
      "name": "Phường 5",
      "district_id": "770",
      "province_id": "79",
      "source": "regex"
    },
    "old_district": {
      "id": "770",
      "name": "3",
      "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": "27196",
      "name": "Bàn Cờ",
      "level": "Phường",
      "province_id": "79",
      "province_name": "Hồ Chí Minh",
      "merged_from_district_ids": [ "770" ],
      "merged_from_district_names": [ "3" ],
      "merged_from_ward_ids": [ "27202" ],
      "merged_from_ward_names": [ "Phường 5" ]
    },
    "new_wards": [ /* Mảng các phường liên quan nếu address mơ hồ */ ],
    "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
Tối ưu hóa xử lý hàng loạt
Tối đa 100 địa chỉ mỗi request. Gọi tối đa 10 request / phút.

Parameters (JSON Body)

addresses *
Array<string>
Mảng các chuỗi địa chỉ cần phân tích.

Ví dụ Request

{
  "addresses": [
    "Nhà Hát Thành Phố, 7 Công Trường Lam Sơn, Phường Bến Nghé, Quận 1, Thành phố Hồ Chí Minh",
    "50 Cao Thắng, Phường Bàn Cờ, Thành phố Hồ Chí Minh"
  ]
}

Response Thành Công (200 OK) 

{
  "success": true,
  "count": 2,
  "data": [
    {
      "input": "Nhà Hát Thành Phố, 7 Công Trường Lam Sơn, Phường Bến Nghé, Quận 1, Thành phố Hồ Chí Minh",
      "mode": "old_to_new",
      "address_prefix": "Nhà Hát Thành Phố, 7 Công Trường Lam Sơn",
      "full_old_address": "Nhà Hát Thành Phố, 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ố, 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": "regex"
      },
      "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": "50 Cao Thắng, Phường Bàn Cờ, Thành phố Hồ Chí Minh",
      "mode": "new_to_old",
      "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 thông tin phường xã cũ/mới như ở /parse ... */
    }
  ]
}
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 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.