V2

Tìm kiếm các từ khóa và trả về danh sách các địa điểm liên quan.

Endpoint

https://maps.track-asia.com/api/v2/place/textsearch/{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

Parameter	Values	Mô tả ngắn gọn	Ví dụ
`query`	String (required)	Giá trị truyền vào bắt buộc phải là tên địa điểm, địa chỉ, hoặc danh mục địa điểm (ví dụ: cà phê, bệnh viện, ATM...).	Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh
`radius`	Number	Bán kính tìm kiếm (tính bằng mét) để giới hạn phạm vi trả về kết quả.	5000
`key`	String (required)	API key	public_key
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

Ví dụ sử dụng

Ví dụ 1: Trả về địa giới mới

https://maps.track-asia.com/api/v2/place/textsearch/json?language=vi&key=public_key&query=Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh&new_admin=true

Ví dụ 2: Trả song song địa chỉ cũ và mới

https://maps.track-asia.com/api/v2/place/textsearch/json?language=vi&key=public_key&query=Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh&new_admin=true&include_old_admin=true

CurlJavascript

curl -G "https://maps.track-asia.com/api/v2/place/textsearch/json" \
--data-urlencode "language=vi" \
--data-urlencode "key=public_key" \
--data-urlencode "query=Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh" \
--data-urlencode "new_admin=true" \
--data-urlencode "include_old_admin=true"

const response = await fetch("https://maps.track-asia.com/api/v2/place/textsearch/xml?language=vi&key=public_key&query=Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh&new_admin=true&include_old_admin=true")
const data = await response.json()
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:

plus_code: Đối tượng với global_code (và có thể có compound_code).
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:
- place_id: Định danh duy nhất cho địa điểm.
- name: Tên địa điểm.
- formatted_address: Địa chỉ đầy đủ đã được chuẩn hóa.
- 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ụ: street_number, route, administrative_area_level_1, v.v.
- geometry: Đối tượng mô tả thông tin vị trí, gồm:
  - location: Tọa độ địa lý với lat và lng.
  - location_type: Loại vị trí định vị (ví dụ: "ROOFTOP").
  - viewport: Phạm vi khung nhìn gợi ý, gồm northeast và southwest.
- plus_code: Đối tượng với compound_code và global_code (có thể lặp lại trong từng kết quả).
- adr_address: Chuỗi địa chỉ đã được gắn thẻ HTML (ví dụ: <span class="...">) để hiển thị định dạng trên giao diện người dùng.
- partial_match: Boolean cho biết kết quả có phải là khớp một phần với truy vấn không.
- icon: Mã biểu tượng đại diện loại địa điểm.
- icon_background_color: Màu nền của biểu tượng (mã màu HEX).
- types: Mảng các phân loại của địa điểm, ví dụ: point_of_interest, establishment, v.v.
- old_address_components: (Chỉ có khi truyền include_old_admin=true) Mảng các đối tượng thành phần địa chỉ theo địa giới cũ, cấu trúc giống address_components.
- old_formatted_address: (Chỉ có khi truyền include_old_admin=true) Địa chỉ đầy đủ theo địa giới 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 <GeocodeResponse>.
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.

Status

Status	Mô tả
`OK`	cho biết không có lỗi xảy ra; địa chỉ đã được phân tích cú pháp thành công và ít nhất một geocode đã được trả về.
`ZERO_RESULTS`	cho biết geocode 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 geocoder được truyền một địa chỉ không tồn tại.

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.

Các bước tiếp theo

Thử API playground