Vietnam Provinces

English | Tiếng Việt

A Flutter package for managing Vietnam's administrative divisions: provinces, districts, and wards.

Supports both v1 (3-level structure) and v2 (2-level structure) administrative divisions.

Left: v1 (3-level structure) | Right: v2 (2-level structure)

📄 Data source

The data for this package is sourced from the Vietnam Provinces Open API

✨ Features

• Retrieve provinces, districts, and wards.
• Search by name (query) or code.
• Support for both administrative division versions:
  • v1 (3-level): Province > District > Ward (used before July 2025)
  • v2 (2-level): Province > Ward (used from July 2025 onwards)
• Lightweight and simple to integrate.

🚀 Getting Started

1. Add the package to your pubspec.yaml:

   dependencies:
     vietnam_provinces: ^1.0.2
   

2. Load the data in your app:

   import 'package:vietnam_provinces/vietnam_provinces.dart';
   
   void main() async {
    WidgetsFlutterBinding.ensureInitialized();
       
    // Initialize with v2 (2-level structure) - default
    await VietnamProvinces.initialize(version: AdministrativeDivisionVersion.v2);
       
    // Or initialize with v1 (3-level structure)
    // await VietnamProvinces.initialize(version: AdministrativeDivisionVersion.v1);
   }
   

🔧 Usage

Version 2 (2-Level Structure: Province > Ward)

Used from July 2025 onwards

• Get provinces or query:

  final provinces = VietnamProvinces.getProvinces(code: 1);
  

  final provinces = VietnamProvinces.getProvinces(query: "Hà");
  

• Get wards directly by province code:

  final wards = VietnamProvinces.getWards(
    provinceCode: 1,
    query: "Phường",
  );
  

Version 1 (3-Level Structure: Province > District > Ward)

Used before July 2025

• Get provinces or query:

  final provinces = VietnamProvinces.getProvinces(code: 1);
  

  final provinces = VietnamProvinces.getProvinces(query: "Hà");
  

• Get districts by province code:

  final districts = VietnamProvinces.getDistricts(
    provinceCode: 1,
    query: "Quận",
  );
  

• Get wards by province code and district code:

  final wards = VietnamProvinces.getWards(
    provinceCode: 1,
    districtCode: 10,
    query: "Phường",
  );
  

📱 Example

To see vietnam_provinces in action, check out the example project in the example.

The example app demonstrates both v1 and v2 administrative division structures with a version switcher.

🛠️ Contributions

We welcome contributions! If you have ideas for features, bug fixes, or improvements, feel free to open an issue or submit a pull request.

🐞 Issues and feedback

Please file issues to send feedback or report a bug. Thank you!

📜 License

MIT License