Administrative Boundary API Update: Flexible Support for Both Old & New Addresses

July 1, 2025 marks a major milestone as Vietnam officially implements the new administrative boundaries, streamlining from 63 to just 34 provinces and cities. This is not only an administrative change but also raises urgent requirements for updating map data, identification systems, and addresses in technology systems.

To support businesses and developers during this transition, TrackAsia Maps officially upgrades its API with the ability to:

✅ Support searching and displaying addresses according to the new administrative boundaries.

✅ Flexibly switch and retrieve both old and new addresses in parallel.

✅ Backward compatibility, ensuring no disruption to existing systems.               
 

API Update: Switch from v1 ➝ v2

If you are using trackasia-gl to display maps, please update your initialization code to the new standard:

Previously (v1):

Now (v2):

Note: v2 uses the latest map dataset, compatible with the new administrative boundaries effective from July 1, 2025.                
    
👉 Quick integration guide here: TrackAsia API Documentation         

⚙️ How it works

– By default, the API returns addresses according to the old administrative boundaries (before July 1, 2025) to ensure compatibility with current systems.                 

The search/autocomplete /place detail APIs have been updated to support the new administrative units. Users can easily adjust API behavior via 2 new parameters:

1. new_admin=true

When added to the query, the API will return addresses according to the new administrative boundaries (updated after July 1, 2025). If this parameter is not provided, the API will default to the old address for backward compatibility.

2. include_old_admin=true

This parameter is used together with new_admin=true so the API returns both new and old addresses in parallel. The old address will be shown in fields prefixed with old_*                  

example:

• old_formatted_address
• old_address_components

Example 1: Default query (old boundaries)

OUTPUT:

• This is the default result when not passing new_admin=true, the system will use the old boundaries to ensure backward compatibility.
• The displayed address is Ward 8, Vung Tau City, Ba Ria-Vung Tau Province.

Example 2: Return new boundaries     

OUTPUT:

• When adding new_admin=true, the returned address will reflect the new administrative boundaries effective from 01/07/2025. 
• The displayed address is: Ward Tam Thang, Ho Chi Minh City.

|Example 3: Return both old and new addresses

OUTPUT:

• The new address reflects the post-merger administrative unit: Ward Tam Thang, Ho Chi Minh City
• The old address is still fully accessible: Ward 8, Vung Tau City, Ba Ria-Vung Tau Province 

👉 See more at: TrackAsia API Documentation         

Why is this feature important?

• Compatible with both old and new data: Your system, partners, and customers may be using different address versions.
• Reduce delivery and routing errors: Displaying both helps increase accuracy and reduce confusion.
• Prepare for nationwide transition: Proactively updating helps you stay ahead instead of reactively handling issues.                 
   

USAGE SUGGESTIONS

• When displaying addresses to end users: Use include_old_admin=true to show both old and new addresses, avoiding confusion.
• When syncing backend systems: You can call new_admin=true to start gradually updating data to the new standard.
• When processing orders, CRM, ERP, logistics: Should record both to support accurate lookup, comparison, and historical analysis.                  
   

TrackAsia is committed to supporting businesses, developers, and the ecosystem during Vietnam's administrative boundary transition. With this update, you can:

• Proactively manage data according to the new standard
• Ensure system flexibility and stability
• Minimize risks when addresses change

If you need technical support or implementation advice, the TrackAsia team is ready to assist you!

👉 See more at: TrackAsia API Documentation                  
📬 Contact support: [email protected]