V2

Chuyển đổi địa chỉ giữa các định dạng địa giới hành chính cũ và mới. API convert được sử dụng để chuyển đổi địa chỉ theo hệ thống hành chính cũ sang mới và ngược lại.

Endpoint

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

outputFormat

outputFormat	Mô tả
`json` (khuyến nghị)	cho biết đầu ra ở định dạng JavaScript Object Notation (JSON)
`xml`	cho biết đầu ra ở định dạng XML

Parameters

Tham số	Giá trị	Bắt buộc	Mô tả ngắn gọn	Ví dụ
`text`	Chuỗi	✔	Địa chỉ cần chuyển đổi	720A Đường Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh
`migrate_type`	Chuỗi	✔	Loại chuyển đổi: `old_to_new` (cũ qua mới) hoặc `new_to_old` (mới về cũ)	old_to_new
`latlng`	Chuỗi		Tọa độ của địa chỉ (khuyến khích có để việc chuyển đổi chuẩn xác hơn)	20.316,105.667
`key`	Chuỗi	✔	Khóa API (sử dụng key của bạn, public_key bị giới hạn, chỉ dùng test).	public_key

Ví dụ sử dụng

Ví dụ 1: Chuyển từ địa chỉ cũ sang mới

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

Ví dụ 2: Chuyển từ địa chỉ mới sang cũ

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

CurlJavascript

# JSON - Chuyển từ cũ sang mới
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 - Chuyển từ mới sang cũ
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)

Phản hồi

JSON Phản hồi

Phản hồi là một đối tượng JSON với cấu trúc như sau:

status: Chuỗi trạng thái (ví dụ: "OK").
results: Mảng các đối tượng kết quả. Mỗi đối tượng gồm:
- formatted_address: Địa chỉ đầy đủ đã được chuyển đổi.
- address_components: Mảng các đối tượng với:
  - long_name: Tên đầy đủ của thành phần địa chỉ.
  - short_name: Tên rút gọn hoặc viết tắt.
  - types: Mảng phân loại, ví dụ: locality, political, administrative_area_level_1, v.v.
- migrate_type: Loại chuyển đổi đã áp dụng (old_to_new hoặc new_to_old).

XML Phản hồi

Phản hồi XML có cấu trúc tương tự, các trường sẽ là các thẻ XML tương ứng với các trường JSON ở trên. Một số khác biệt:

Kết quả XML được bọc trong phần tử gốc <ConvertResponse>.
Các mảng trong JSON (như results, address_components, types) sẽ là các phần tử lặp lại trong XML (như <result>, <address_component>, <type>).
Các trường rỗng được thể hiện bằng mảng rỗng trong JSON, nhưng sẽ không có phần tử nào trong XML.

Lưu ý quan trọng

API Convert này được thiết kế riêng cho việc chuyển đổi địa chỉ giữa các hệ thống hành chính cũ và mới.
Để có kết quả chính xác nhất, nên cung cấp tọa độ (latlng) của địa chỉ cần chuyển đổi.
Kết quả trả về sẽ bao gồm địa chỉ đã được chuẩn hóa theo hệ thống hành chính tương ứng.

Status

Status	Mô tả
`OK`	cho biết không có lỗi xảy ra; địa chỉ đã được chuyển đổi thành công và ít nhất một kết quả đã được trả về.
`ZERO_RESULTS`	cho biết chuyển đổi thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu địa chỉ không tồn tại hoặc không xác định.

Error messages

Khi dịch vụ trả về mã trạng thái khác OK, có thể có trường error_message bổ sung trong đối tượng phản hồi. Trường này cung cấp thông tin chi tiết hơn về lý do dẫn đến mã trạng thái đó. Trường này không phải lúc nào cũng xuất hiện và nội dung có thể thay đổi.