Danh mục dùng chung API

Danh mục có mã cho biểu mẫu: 54 dân tộc, tôn giáo được công nhận, quốc tịch, nghề nghiệp VSCO 2020, trình độ học vấn, tình trạng hôn nhân, nhóm máu.

GEThttps://apibox.io.vn/v1/vn-catalogs/{catalog}/{code}

Dữ liệu & JSON▶ Dùng thử online

API danh mục dùng chung cung cấp các danh mục có mã mà biểu mẫu tại Việt Nam thường dùng, kèm hệ mã của từng danh mục: ethnic (54 dân tộc, mã 01–54 theo Quyết định 121-TCTK/PPCĐ, kèm tên gọi khác như Việt, Khmer, Mông), religion (16 tôn giáo được Nhà nước công nhận, Công văn 6955/BNV-TGCP), nationality (mã ISO 3166-1 alpha-2, alpha-3, số kèm tên tiếng Việt), occupation (Danh mục nghề nghiệp Việt Nam VSCO 2020, Quyết định 34/2020/QĐ-TTg, cấp 1–4), education (các cấp học phổ thông và 8 bậc của Khung trình độ quốc gia, kèm mã ISCED), marital_status, blood_type, gender (ISO/IEC 5218), id_document (căn cước, CCCD, hộ chiếu…) và relationship.

Lấy cả danh mục (/v1/vn-catalogs/religion), một mã (/v1/vn-catalogs/ethnic/08, nationality/VNM), hoặc tìm bằng q, có dấu hay không dấu đều được (q=kinh, q=han quoc, q=lap trinh trong nghề nghiệp). Danh mục nghề nghiệp mặc định trả cấp 1; dùng level hoặc parent=25 để xem cấp dưới.

Danh mục dân tộc, tôn giáo và nghề nghiệp được dựng lại bằng script có kiểm tra từ bộ hướng dẫn HL7 Vietnam VN Core (bản số hoá các văn bản chính thức); các danh mục nhỏ được nhập tay và rà soát hằng năm. Mã ghi là mã apibox thì không phải mã chính thức.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc
`catalog`	path\|query	string	không	`ethnic`, `religion`, `nationality`, `occupation`, `education`, `marital_status`, `blood_type`, `gender`, `id_document` hoặc `relationship`; bỏ trống để xem danh sách danh mục.
`code`	path\|query	string	không	Một mã (đường dẫn `/ethnic/08` hoặc `?code=`); quốc tịch nhận alpha-2, alpha-3 hoặc mã số.
`q`	query	string	không	Tìm theo tên, có hoặc không dấu.
`level`	query	number	không	Nghề nghiệp: cấp 1–4.
`parent`	query	string	không	Nghề nghiệp: các mã con của mã này.
`limit`	query	number	không	Số mục tối đa (1–1000).

Ví dụ

curl "https://apibox.io.vn/v1/vn-catalogs/ethnic?q=mong" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-catalogs/ethnic?q=mong', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/vn-catalogs/ethnic?q=mong",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-catalogs/ethnic?q=mong');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "catalog": "ethnic",
  "name_vi": "Dân tộc",
  "name_en": "Ethnic groups",
  "code_system": "QĐ 121-TCTK/PPCĐ (Tổng cục Thống kê, 02/03/1979): 01–54; 55 người nước ngoài, 99 không rõ are technical codes",
  "source": "HL7 Vietnam VN Core FHIR IG (https://vncore-ig.pages.dev/core), version 0.10.0",
  "reviewed": "2026-11-11",
  "query": "mong",
  "count": 1,
  "items": [
    {
      "code": "08",
      "name_vi": "HMông",
      "name_en": "H'Mong",
      "aliases": [
        "Mông",
        "H'Mông",
        "Hmong",
        "Mèo"
      ],
      "official": true
    }
  ]
}

Ứng dụng

Làm ô chọn trong biểu mẫu dịch vụ công, nhân sự, trường học
Chuẩn hoá thông tin hành chính người bệnh trong HIS, FHIR
Kiểm tra mã dân tộc, tôn giáo trong dữ liệu eKYC
Gán mã nghề nghiệp VSCO 2020 cho chức danh công việc

Hỏi đáp

Danh mục dân tộc theo mã nào?

Theo Tổng cục Thống kê (QĐ 121-TCTK/PPCĐ): 01 Kinh … 54 Rơ Măm, kèm mã kỹ thuật 55 (người nước ngoài) và 99 (không rõ).

Tôn giáo được mã hoá thế nào?

Theo thứ tự danh mục tôn giáo được công nhận (CV 6955/BNV-TGCP), dạng 2 chữ số như hệ mã HL7 VN Core; 00 là không tôn giáo.

Tìm không dấu được không?

Được, mọi tìm kiếm đều bỏ dấu và chữ đ; dân tộc có thêm tên gọi khác thông dụng (Việt, Khmer, Mèo…).

API liên quan

{✓}

Danh mục dùng chung API

Tham số

Ví dụ

Kết quả trả về

Ứng dụng

Hỏi đáp

API liên quan

Kiểm tra JSON

Định dạng JSON

CSV sang JSON