Dorabot – Vietnam address after 2025 merger

@dorabot-io/dia-chi

Địa chỉ hành chính Việt Nam sau sáp nhập 2025 cho JavaScript / TypeScript: 34 tỉnh, 3.321 xã/phường/đặc khu mới, bảng đổi 11.559 xã cũ sang mới theo đúng nghị quyết của Ủy ban Thường vụ Quốc hội (kèm số khoản), và form chọn địa chỉ 2 cấp cho React.

Từ 01/7/2025 địa chỉ ở Việt Nam chỉ còn 2 cấp: xã/phường/đặc khu → tỉnh/thành phố. Không còn quận/huyện. Form 3 cấp (tỉnh → huyện → xã) là kiểu cũ.

npm i @dorabot-io/dia-chi

Chạy offline, không cần khoá, không gọi mạng (trừ doiDiaChi). Node ≥ 18, trình duyệt, Vite, Next.js, Bun, Deno, Cloudflare Workers.

Dùng nhanh

import { tinh, xa, timXaCu, kiemDiaChi, doiDiaChi } from '@dorabot-io/dia-chi';

tinh();                 // 34 tỉnh/thành: { slug, tenDayDu, gomTinhCu, nghiQuyet, soXa }
xa('ha-noi');           // xã/phường mới của Hà Nội (nhận cả "Hà Nội", "Thái Bình" → Hưng Yên)

await timXaCu('Bách Khoa', { huyen: 'Hai Bà Trưng', tinh: 'Hà Nội' });
// [{ xaCu: 'Phường Bách Khoa', huyenCu: 'Quận Hai Bà Trưng', den: [{ tenDayDu: 'Phường Bạch Mai', phan: 'toan_bo', khoan: 8 }],
//    nghiQuyet: { so: '1656/NQ-UBTVQH15', hieu_luc: '2025-07-01', url: '…' } }]

await kiemDiaChi('12 Tạ Quang Bửu, phường Bách Khoa, quận Hai Bà Trưng, Hà Nội');
// { trangThai: 'dia_chi_cu', lyDo: 'Còn cấp quận/huyện …' }   ← dùng ở bước kiểm form / nhập dữ liệu
await kiemDiaChi('12 Tạ Quang Bửu, Phường Bạch Mai, Thành phố Hà Nội');
// { trangThai: 'hop_le', diaChiChuan: '12 Tạ Quang Bửu, Phường Bạch Mai, Thành phố Hà Nội' }

// Đổi địa chỉ đầy đủ, chuỗi lộn xộn/viết tắt (gọi API dorabot.io):
await doiDiaChi('12 Tạ Quang Bửu, P. Bách Khoa, Q. Hai Bà Trưng, HN');
// { thanh_cong: true, dia_chi_moi: '12 Tạ Quang Bửu, Phường Bạch Mai, Thành phố Hà Nội', tin_cay: { muc: 'cao' } }
await doiDiaChi([...5000DiaChiKhachHang], { apiKey: process.env.DORABOT_API_KEY }); // tối đa 200/lần

doiDiaChi không khoá: 20 địa chỉ/ngày/IP. Khoá miễn phí dk_… (100/ngày, đăng nhập Google): https://dorabot.io/dia-chi/nha-phat-trien/ — gói doanh nghiệp đổi hàng loạt: https://dorabot.io/dia-chi/doanh-nghiep/

Form chọn địa chỉ 2 cấp (React)

import { ChonDiaChi } from '@dorabot-io/dia-chi/react';

<ChonDiaChi
  choDoiDiaChiCu            // thêm ô "dán địa chỉ cũ để đổi"
  onChange={(v) => setForm({ ...form, tinh: v.tinh, xa: v.xa, diaChi: v.diaChi })}
  selectClassName="border rounded px-2 py-1"
/>

Không phụ thuộc thư viện UI (2 thẻ <select>). Lưu slug tỉnh + slug xã vào DB, hiển thị tenDayDu.

Lưu trong cơ sở dữ liệu

-- địa chỉ mới: 2 cấp
dia_chi_chi_tiet text,      -- số nhà, đường, thôn/xóm
xa_slug   text,             -- 'phuong-bach-mai'
tinh_slug text              -- 'ha-noi'
-- giữ cột địa chỉ cũ (nếu có) để đối chiếu, đừng xoá ngay

Còn có

• MCP cho Claude / ChatGPT / Cursor: https://dorabot.io/dia-chi/mcp (công cụ tra_cuu_xa_cu, doi_dia_chi, kiem_dia_chi, danh_sach_xa_moi, danh_sach_tinh).
• REST: POST https://dorabot.io/dia-chi/api/v1/doi.php {"addresses": [...]} — OpenAPI ở trang nhà phát triển.
• Python: pip install dorabot-dia-chi.
• Dữ liệu mở CSV/JSON: https://github.com/Dorabot-io/sap-nhap-2025
• Tra tay, đổi file Excel: https://dorabot.io/dia-chi/

Giấy phép

Code MIT. Dữ liệu CC BY 4.0 — ghi nguồn "Dorabot (dorabot.io)" ở đâu đó trong app hoặc tài liệu (component React đã có dòng nhỏ, tắt bằng ghiNguon={false} nếu bạn ghi nguồn chỗ khác).

Dữ liệu chép từ nghị quyết UBTVQH 2025 về sắp xếp đơn vị hành chính cấp xã của từng tỉnh và Nghị quyết 202/2025/QH15. Thấy sai: [email protected] hoặc mở issue.

Dorabot (dorabot.io) là công cụ của Việt Nam, không liên quan tới công ty robot Dorabot ở Thâm Quyến (dorabot.com).

---

English. Vietnam administrative divisions after the 1 July 2025 merger (34 provinces, 2 levels: commune/ward → province, no districts). Offline list of provinces and 3,321 new communes, old→new commune mapping for 11,559 old communes with the official resolution clause, a validator for new-format addresses, a React 2-level address picker, and doiDiaChi() which calls the dorabot.io API to convert full free-text old addresses. Code MIT, data CC BY 4.0.

Trong repo này

• js/ — gói npm @dorabot-io/dia-chi (+ /react)
• python/ — PyPI dorabot-dia-chi
• vi-du/ — ví dụ React/Vite, Node đổi file CSV, Python Excel, PHP/Laravel, Flutter
• Dữ liệu CSV/JSON đầy đủ: https://github.com/Dorabot-io/sap-nhap-2025