Skip to content

Convert addresses between old and new administrative boundary formats. The Convert API is used to convert addresses between the old and new administrative systems.

Endpoint

https://maps.track-asia.com/api/v2/place/convert/{outputFormat}

outputFormat

outputFormat Description
json (recommended) indicates output in JavaScript Object Notation (JSON)
xml indicates output in XML

Parameters

Parameter Values Require Short Description Example
text String ✔ The address to be converted 720A Đường Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh
migrate_type String ✔ Conversion type: old_to_new or new_to_old old_to_new
latlng String Coordinates of the address (recommended for more accurate conversion) 20.316,105.667
key String ✔ API key (use your own key; public_key is limited and for testing only) public_key

Example Usage

Example 1: Convert from old to new address 

https://maps.track-asia.com/api/v2/place/convert/json?text=Landmark 81 720A Đường Điện Biên Phủ, Phường 22, Quận Bình Thạnh, Thành phố Hồ Chí Minh&migrate_type=old_to_new&latlng=10.795067,106.722045&key=public_key

Example 2: Convert from new to old address 

https://maps.track-asia.com/api/v2/place/convert/xml?text=Landmark 81 720A Đường Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh&migrate_type=new_to_old&latlng=10.795067,106.722045&key=public_key


# JSON - old to new
curl -G "https://maps.track-asia.com/api/v2/place/convert/json?" \
--data-urlencode "text=720A Đường Điện Biên Phủ, Phường 22, Quận Bình Thạnh, Thành phố Hồ Chí Minh" \
--data-urlencode "migrate_type=old_to_new" \
--data-urlencode "key=public_key"

# XML - new to old
curl -G "https://maps.track-asia.com/api/v2/place/convert/xml?" \
--data-urlencode "text=720A Đường Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh" \
--data-urlencode "migrate_type=new_to_old" \
--data-urlencode "key=public_key"

// JSON
const response = await fetch("https://maps.track-asia.com/api/v2/place/convert/json?text=Landmark 81 720A Đường Điện Biên Phủ, Phường 22, Quận Bình Thạnh, Thành phố Hồ Chí Minh&migrate_type=old_to_new&latlng=10.795067,106.722045&key=public_key")
const data = await response.json()
console.log(data)

 // XML
const response = await fetch("https://maps.track-asia.com/api/v2/place/convert/xml?text=Landmark 81 720A Đường Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh&migrate_type=new_to_old&latlng=10.795067,106.722045&key=public_key")
const data = await response.text()
console.log(data)

Response

JSON Response

The response is a JSON object with the following structure:

  • status: Status string (e.g., "OK").
  • results: Array of result objects. Each object includes:
    • formatted_address: Full formatted address after conversion.
    • address_components: Array of objects with:
      • long_name: Full name of the address component.
      • short_name: Abbreviated or short name.
      • types: Array of types, e.g., locality, political, administrative_area_level_1, etc.
    • migrate_type: The conversion type applied (old_to_new or new_to_old).
XML Response

The XML response has a similar structure, with elements corresponding to the JSON fields above. Notable differences:

  • XML results are wrapped in a root <ConvertResponse> element.
  • Arrays in JSON (such as results, address_components, types...) become repeated elements in XML.
  • Blank elements are indicated by empty arrays in JSON, but by the absence of such elements in XML.

Important Notes

  • This Convert API is specifically designed for converting addresses between old and new administrative systems.
  • For the most accurate results, it's recommended to provide the coordinates (latlng) of the address being converted.
  • The returned results will include addresses standardized according to the corresponding administrative system.

Status

Status Description
OK Indicates no errors occurred; the address was successfully converted and at least one result was returned.
ZERO_RESULTS Indicates the conversion was successful but returned no results. This may occur if the address doesn't exist or is indeterminable.

Error messages

When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field provides more detailed information about the reasons behind the given status code. This field is not always returned, and its content is subject to change.