API Đơn vị hành chính Việt Nam

1. Lấy danh sách tất cả Tỉnh/Thành phố

API này trả về danh sách toàn bộ 34 tỉnh/thành phố của Việt Nam.

Tham số: Không có.

Ví dụ yêu cầu:

https://34tinhthanh.com/api/provinces

Ví dụ kết quả trả về (JSON):

[
  {
    "province_code": "01",
    "name": "Thành phố Hà Nội"
  },
  {
    "province_code": "02",
    "name": "Tỉnh Hà Giang"
  },
  // ...
]

Trong kết quả trả về, bạn sẽ thấy các trường sau:

• province_code: Mã định danh duy nhất của tỉnh/thành phố.
• name: Tên đầy đủ của tỉnh/thành phố.

Mã lỗi có thể gặp:

2. Lấy danh sách Phường/Xã theo Tỉnh/Thành

API này trả về danh sách các phường/xã thuộc một tỉnh/thành phố cụ thể dựa vào mã của tỉnh/thành đó.

Tham số:

• province_code (bắt buộc): Mã của tỉnh/thành phố.

Ví dụ yêu cầu (lấy danh sách phường/xã của Hà Nội):

https://34tinhthanh.com/api/wards?province_code=01

Ví dụ kết quả trả về (JSON):

[
  {
    "ward_code": "00123",
    "ward_name": "Phường Phúc Xá",
    "province_code": "01",
    // ...
  },
  // ...
]

Mô tả các trường:

• ward_code: Mã định danh của phường/xã.
• ward_name: Tên phường/xã.
• province_code: Mã tỉnh/thành phố chứa đơn vị này.
• ... và các trường khác.

3. Tìm kiếm Tỉnh/Thành hoặc Phường/Xã

API này cho phép tìm kiếm dựa trên tên của tỉnh/thành hoặc phường/xã. Kết quả tìm kiếm không phân biệt chữ hoa/thường, có dấu/không dấu, và hỗ trợ tìm kiếm theo cả tên đơn vị hành chính cũ đã sáp nhập. Tối đa 50 kết quả.

Tham số:

• q (bắt buộc): Từ khóa tìm kiếm (tối thiểu 2 ký tự).

Ví dụ yêu cầu (tìm kiếm "ha noi"):

https://34tinhthanh.com/api/search?q=ha noi

Ví dụ kết quả trả về (JSON):

[
  {
    "type": "province",
    "province_code": "01",
    "name": "Thành phố Hà Nội"
  },
  {
    "type": "ward",
    "ward_code": "00123",
    "ward_name": "Phường Phúc Xá",
    // ...
  },
  // ...
]

Mô tả các trường:

• type: province hoặc ward.
• is_merger_match: true nếu kết quả được tìm thấy dựa trên tên của một đơn vị cũ.
• matched_old_unit: Tên của đơn vị cũ đã khớp với từ khóa tìm kiếm.
• ... và các trường khác.

4. Lấy thông tin thống kê

API này cung cấp các số liệu thống kê tổng quan về dữ liệu đơn vị hành chính.

Tham số:

• province_code (tùy chọn): Nếu được cung cấp, kết quả sẽ bao gồm cả số lượng phường/xã của riêng tỉnh/thành đó.

Ví dụ yêu cầu (thống kê chung):

https://34tinhthanh.com/api/stats

Ví dụ kết quả trả về (JSON):

{
  "numProvinces": 63,
  "numWards": 8940,
  "currentWards": 0,
  "numMergedProvinces": 48,
  "mergedWardsPercentage": "36.5"
}

Ví dụ yêu cầu (thống kê cho Hà Nội):

https://34tinhthanh.com/api/stats?province_code=01

Ví dụ kết quả trả về (JSON):

{
  "numProvinces": 63,
  "numWards": 8940,
  "currentWards": 386,
  "numMergedProvinces": 48,
  "mergedWardsPercentage": "36.5"
}

Mô tả các trường:

• numProvinces: Tổng số tỉnh/thành.
• numWards: Tổng số phường/xã trên cả nước.
• currentWards: Số phường/xã của tỉnh được chọn (nếu có).
• numMergedProvinces: Số tỉnh/thành có phường/xã đã sáp nhập.
• mergedWardsPercentage: Tỷ lệ phần trăm phường/xã đã sáp nhập trên toàn quốc.

5. Giới hạn Yêu cầu (Rate Limiting)

Để đảm bảo sự ổn định của hệ thống cho tất cả người dùng, chúng tôi áp dụng cơ chế giới hạn số lượng yêu cầu (rate limiting) dựa trên địa chỉ IP.

• Tất cả các API: Tối đa 200 yêu cầu / 15 phút cho mỗi IP.
• API Tìm kiếm (/api/search): Áp dụng giới hạn nghiêm ngặt hơn là 60 yêu cầu / 15 phút cho mỗi IP.

Nếu bạn vượt quá giới hạn này, API sẽ trả về mã lỗi 429 Too Many Requests cùng với một thông báo tiếng Việt. Vui lòng chờ hết khoảng thời gian giới hạn trước khi gửi yêu cầu tiếp theo.