Zipcode Introduction

ZIPCODE is a normalized commune/ward-level administrative identifier system for Vietnam, developed by NDAMaps.

1. Overview

1.1 What is Zipcode?

Zipcode is a standardized ID system for commune/ward/special-zone administrative units in Vietnam. Unlike traditional postal codes (VNPost zip/postal codes), which are typically 5-6 digits and mainly used for mail delivery, NDAMaps Zipcode provides a unique, stable, and system-friendly identifier for each local administrative unit in digital mapping workflows.

The system covers all 34 provinces/cities (based on the latest merger plan) with 3,321 communes/wards/special zones nationwide, helping POI (Point of Interest) management, analytics, and geospatial localization stay consistent and accurate.

1.2 How does Zipcode work?

Instead of storing long administrative text strings that are easy to mistype (for example: "Phuong Cau Giay", "P. Cau Giay", "Phuong C.Giay"), each commune/ward is assigned standardized identifiers:

Numeric code (Zipcode): A unique numeric ID optimized for database queries (for example, 27003 for Cau Giay Ward, Hanoi City).
Standardized name: The official and normalized administrative unit name.

1.3 Key benefits

Benefit	Description	Real-world example
🎯 Consistency	Standardizes administrative naming across systems	Easier linking of location data from multiple sources
⚡ Performance	Uses numeric IDs (`u32`) instead of free-text strings	Faster DB indexing, filtering, and lookup
🇻🇳 Up-to-date	Reflects post-merger administrative maps	Avoids outdated boundaries and naming

1.4 Comparison with other approaches

Method	Example	Pros	Cons
Traditional text	`"Phuong Cau Giay"`	Human-readable	Typos, hard DB querying, larger storage
VNPost postal code	`"10000"`	Postal standard	Often not precise to commune/ward level, can change over time
🚀 NDAMaps Zipcode	`27003`	Precise to commune level, software-friendly numeric ID	Proprietary standard, requires API/table lookup

2. System Structure

The Zipcode system is hierarchically organized by Province/City and Commune/Ward, making grouping and filtering straightforward.

2.1 Code range structure

Provinces/cities are allocated system ID ranges for easier scoping. Their child communes/wards receive Zipcodes inside the corresponding province range.

Sample Province ID ranges:

Region/Province	Province ID	Commune-level Zipcode range	Example commune/ward
Hanoi	`27000`	`27001` - `27999`	`27003` (Cau Giay Ward)
Ho Chi Minh City	`25000`	`25001` - `25999`	`25005` (Ben Thanh Ward)

3. Easy Integration

Simple API patterns

1. Decode Zipcode:

Input: Zipcode (for example, 27003)
Output: Detailed ward/commune information.

{
  "zipcode": 27003,
  "name": "Phường Cầu Giấy",
  "province": "Thành Phố Hà Nội",
  "province_id": 27000
}

2. List communes/wards by province:

Input: Province ID (for example, 27000)
Output: Full list of communes/wards in Hanoi City.

3. Use with POI APIs:

All NDAMaps POI-related APIs (Autocomplete, Geocoding, etc.) return zipcode for precise administrative localization.

{
  "bbox": [
    105.77673532307692,
    21.018671899999998,
    105.79673532307693,
    21.0386719
  ],
  "features": [
    {
      "geometry": {
        "coordinates": [
          105.78673532307693,
          21.0286719
        ],
        "type": "Point"
      },
      "properties": {
        "country": "Việt Nam",
        "country_code": "VN",
        "forcodes": "HNCGDXJ1TXUUMS",
        "housenumber": "96",
        "id": "fmKyXEkDGglX3F7d-mFZJTJuZOXk",
        "label": "Trụ sở Đảng ủy - UBND phường Cầu Giấy, 96, phố Trần Thái Tông, phường Cầu Giấy, phường Cầu Giấy, thành phố Hà Nội",
        "locality": "phường Cầu Giấy",
        "name": "Trụ sở Đảng ủy - UBND phường Cầu Giấy",
        "region": "thành phố Hà Nội",
        "short_address": "96, phố Trần Thái Tông, phường Cầu Giấy",
        "street": "Phố Trần Thái Tông",
        "zipcode": "27003"
      },
      "type": "Feature"
    }
  ],
  "type": "FeatureCollection"
}

Multi-platform integration

📱 Mobile Apps: Smooth address selection flow (Province/City -> Commune/Ward) using hierarchical codes.
🌐 Website: Accurate address autofill with fewer user input errors.
🔧 Backend: Use zipcode as a Foreign Key to optimize database queries.
🗺️ Maps: Fast POI density (heatmap) analysis at commune/ward level.

Zipcode Introduction

1. Overview​

1.1 What is Zipcode?​

1.2 How does Zipcode work?​

1.3 Key benefits​

1.4 Comparison with other approaches​

2. System Structure​

2.1 Code range structure​

3. Easy Integration​

Simple API patterns​

Multi-platform integration​