V2

Giúp người dùng tìm kiếm địa điểm mà không cần nhập đầy đủ từ khóa.

Endpoint

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

outputFormat

outputFormat	Mô tả
`json` (khuyến nghị)	định dạng JSON
`xml`	định dạng XML

Tham số

Tham số	Giá trị	Mô tả	Ví dụ
`input`	Chuỗi (bắt buộc)	Chuỗi đầu vào cần tự động hoàn thành. Có thể là địa chỉ chưa đầy đủ, tên địa điểm, hoặc bất kỳ chuỗi nào cần tìm kiếm	Toa nha BW
`key`	Chuỗi (bắt buộc)	Khóa API	public_key
`bounds`	`{vĩ độ},{kinh độ};{vĩ độ},{kinh độ}`	Vùng giới hạn không gian để ưu tiên kết quả tìm kiếm. Tham số này chỉ định hướng, không bắt buộc kết quả phải nằm trong vùng này	21.6463420,104.8429379;21.7503187,104.9330227
`size`	Số nguyên	Số lượng kết quả tối đa cần trả về	5
`location`	`{vĩ độ},{kinh độ}`	Tọa độ địa điểm để tìm địa chỉ gần nhất có thể đọc được bằng tiếng người dùng	10.7952219,106.7217912
new_admin	Boolean	Trả về địa chỉ theo địa giới hành chính mới	`true`
include_old_admin	Boolean	(Dùng kèm new_admin) Trả song song cả địa chỉ cũ và mới	`true`

Mã ví dụ

Ví dụ này minh họa cách sử dụng định dạng JSON trong phản hồi.

https://maps.track-asia.com/api/v2/place/autocomplete/json?input=Landmark 81&bounds=21.6463420,104.8429379;21.7503187,104.9330227&size=2&key=public_key&new_admin=true

Ví dụ này minh họa cách sử dụng định dạng XML trong phản hồi

https://maps.track-asia.com/api/v2/place/autocomplete/json?input=Landmark 81&bounds=21.6463420,104.8429379;21.7503187,104.9330227&size=2&key=public_key&new_admin=true&include_old_admin=true

CurlJavascript

# JSON
curl -G "https://maps.track-asia.com/api/v2/place/autocomplete/json" \
--data-urlencode "input=Toa nha BW" \
--data-urlencode "bounds=21.6463420,104.8429379;21.7503187,104.9330227" \
--data-urlencode "location=10.7952219,106.7217912" \
--data-urlencode "size=5" \
--data-urlencode "key=public_key" \
--data-urlencode "new_admin=true" \
--data-urlencode "new_include_old_admin=true"


# XML
curl -G "https://maps.track-asia.com/api/v2/place/autocomplete/xml" \
--data-urlencode "input=Toa nha BW" \
--data-urlencode "bounds=21.6463420,104.8429379;21.7503187,104.9330227" \
--data-urlencode "location=10.7952219,106.7217912" \
--data-urlencode "size=5" \
--data-urlencode "key=public_key" \
--data-urlencode "new_admin=true" \
--data-urlencode "new_include_old_admin=true"

// JSON
const response = await fetch("https://maps.track-asia.com/api/v2/place/autocomplete/json?input=Landmark 81&bounds=21.6463420,104.8429379;21.7503187,104.9330227&size=2&key=public_key&new_admin=true")
const data = await response.json()
console.log(data)

// XML
const response = await fetch("https://maps.track-asia.com/api/v2/place/autocomplete/json?input=Landmark 81&bounds=21.6463420,104.8429379;21.7503187,104.9330227&size=2&key=public_key&new_admin=true&include_old_admin=true")
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").
warning_message: (Có thể có) Thông báo cảnh báo về tham số hoặc truy vấn, ví dụ: "Invalid Parameter: bounds".
predictions: Mảng các đối tượng gợi ý. Mỗi đối tượng gồm:
- place_id: Định danh duy nhất cho địa điểm.
- reference: Tham chiếu cho địa điểm (có thể trùng với place_id).
- name: Tên địa điểm.
- description: Mô tả đầy đủ về địa điểm.
- formatted_address: Địa chỉ đầy đủ đã được chuẩn hóa.
- icon: Mã biểu tượng đại diện loại địa điểm.
- matched_substrings: Mảng các đối tượng thể hiện vị trí khớp với chuỗi nhập vào.
- structured_formatting: Đối tượng gồm main_text, main_text_matched_substrings, và secondary_text để hiển thị.
- terms: Mảng các đối tượng với offset và value cho từng thành phần kết quả.
- types: Mảng các phân loại của địa điểm.
- old_description: (Có thể có) Mô tả địa chỉ cũ nếu có.
- old_formatted_address: (Có thể có) Địa chỉ cũ nếu có.

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 <AutocompletionResponse>.
Các mảng trong JSON (như predictions, terms) sẽ là các phần tử lặp lại trong XML (như <prediction>, <term>).
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.

Status

Status	Mô tả
`OK`	cho biết API request đã thành công.
`ZERO_RESULTS`	chỉ ra rằng tìm kiếm đã thành công nhưng không trả lại kết quả. Điều này có thể xảy ra nếu tìm kiếm được thông qua một giới hạn ở một vị trí xa.

Error messages

Khi geocoder 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 Geocoding. Trường này chứa thông tin chi tiết hơn về lý do đằng sau mã trạng thái đã cho.

Các bước tiếp theo

Thử API playground