Working with Vietnam Administrative Boundaries: Province, District, and Ward Data

For delivery, logistics, and mapping applications, locating an address on a map is only half the battle. To run operations effectively, backend services must know which administrative zone the address belongs to.

Whether you are calculating local shipping fees, segmenting customers by region, or assigning couriers to specific zones, having clean Vietnam administrative division data is critical.

The hierarchy of Vietnamese divisions

Vietnam's administrative structure is divided into three tiers:

1. First-tier: Provinces (Tỉnh) and Municipalities (Thành phố trực thuộc trung ương).
2. Second-tier: Districts (Quận, Huyện, Thị xã, Thành phố thuộc tỉnh).
3. Third-tier: Wards (Phường), Communes (Xã), and Townships (Thị trấn).

For database architectures, modeling these divisions requires managing strict parent-child relationships: a Ward always belongs to a single District, which belongs to a single Province.

{
  "province": {
    "code": "79",
    "name": "Thành phố Hồ Chí Minh"
  },
  "district": {
    "code": "760",
    "name": "Quận 1"
  },
  "ward": {
    "code": "26734",
    "name": "Phường Bến Thành"
  }
}

The problem of fluid boundaries

One of the biggest challenges for backend engineers in Vietnam is data accuracy over time. Administrative boundaries are fluid:

• Wards are frequently merged to optimize administration.
• Districts are split or upgraded to cities (e.g., Thu Duc District upgraded to Thu Duc City).
• Boundary coordinates shift as municipal zoning updates.

If your database uses hardcoded SQL seed tables, your shipping zones will gradually drift, causing delivery pricing errors or API lookup failures.

Designing an administrative mapping API

Rather than hosting and maintaining spatial shapefiles manually in PostGIS, developers can query localized mapping platforms like GoGoDuk.

Using their administrative divisions API, backend applications can fetch updated JSON listings of provinces, districts, and wards dynamically.

Here is a backend Node.js service demonstrating how to query and map coordinates to administrative segments (reverse geocoding to administrative levels):

import axios from "axios";

interface AdminBoundaryResponse {
  province: { code: string; name: string };
  district: { code: string; name: string };
  ward: { code: string; name: string };
  formattedAddress: string;
}

class LocationRoutingService {
  private readonly apiKey = process.env.GOGODUK_API_KEY!;
  private readonly apiUrl = "https://api.gogoduk.com/v1";

  /**
   * Identifies administrative divisions from coordinates
   * to determine shipping hubs and local delivery zones.
   */
  async resolveCoordinatesToBoundary(lat: number, lng: number): Promise<AdminBoundaryResponse | null> {
    try {
      const response = await axios.get(`${this.apiUrl}/reverse-geocode`, {
        params: {
          lat,
          lng,
        },
        headers: {
          "X-API-Key": this.apiKey,
        },
      });

      const { data } = response;
      if (!data) return null;

      return {
        province: {
          code: data.province_code,
          name: data.province,
        },
        district: {
          code: data.district_code,
          name: data.district,
        },
        ward: {
          code: data.ward_code,
          name: data.ward,
        },
        formattedAddress: data.formatted_address,
      };
    } catch (error) {
      console.error("Reverse geocoding boundary lookup failed:", error);
      return null;
    }
  }
}

Logistics use case: Spatial boundary routing

In hyper-local delivery apps, operations are divided into physical segments. Courier dispatch systems map coordinates (latitude, longitude) to specific operations polygons.

Using reverse geocoding to retrieve the official ward code allows you to:

1. Assign Tasks Instantly: Identify the closest courier assigned to Phường Bến Thành.
2. Calculate Dynamic Shipping Rates: Apply surcharge multipliers based on the ward's density or distance from central hubs.
3. Analyze Sales Performance: Aggregate transaction metrics directly by District or Province to identify high-performing markets.

Conclusion

Structuring and maintaining administrative region boundaries is essential for logistics and CRM segmentations in Vietnam. Instead of building and maintaining a GIS database from scratch, using a dedicated service like GoGoDuk gives you access to updated datasets and robust reverse geocoding APIs with zero database overhead.