V2

Tìm địa điểm hoặc địa chỉ gần cặp kinh độ/vĩ độ

Endpoint

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

outputFormat

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

Tham số

Tham số	Giá trị	Bắt buộc	Mô tả	Ví dụ
`latlng`	`{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
`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
`radius`	Số nguyên		Bán kính tìm kiếm tính bằng mét (m).	500, 100, 50, etc.
`new_admin`	`true` , `false` (mặc định)		Trả về địa chỉ theo địa giới hành chính mới	`true`
`include_old_admin`	Boolean		Trả về song song cả địa chỉ cũ và mới (chỉ khả dụng khi `new_admin=true`).	`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/geocode/json?latlng=10.7952219,106.7217912&key=public_key&new_admin=true&include_old_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/geocode/xml?latlng=10.7952219,106.7217912&key=public_key&new_admin=true

CurlJavascript

# JSON
curl -G "https://maps.track-asia.com/api/v2/geocode/json?" \
  --data-urlencode "latlng=10.7952219,106.7217912" \
  --data-urlencode "key=public_key" \
  --data-urlencode "new_admin=true" \
  --data-urlencode "include_old_admin=true"

# XML
curl -G "https://maps.track-asia.com/api/v2/geocode/xml?" \
  --data-urlencode "latlng=10.7952219,106.7217912" \
  --data-urlencode "key=public_key" \
  --data-urlencode "new_admin=true" \

// JSON
const response = await fetch("https://maps.track-asia.com/api/v2/geocode/json?latlng=10.7952219,106.7217912&key=public_key&new_admin=true&include_old_admin=true")
const data = await response.json()
console.log(data)

 // XML
const response = await fetch("https://maps.track-asia.com/api/v2/geocode/xml?latlng=10.7952219,106.7217912&key=public_key&new_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:

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:
- official_id: Mã hành chính chính thức từ Danh mục hành chính Quốc gia.Trường này chỉ trả về khi kết quả là đơn vị hành chính (phường, tỉnh/thành phố).
- place_id: Định danh duy nhất cho địa điểm.
- name: Tên địa điểm.
- types: Mảng các loại đối tượng (ví dụ: "point_of_interest", "establishment"). Dùng để phân loại địa điểm.
- formatted_address: Địa chỉ đầy đủ đã được chuẩn hóa.
- address_components: Mảng các đối tượng với:
  - id, long_name, short_name, và types cho từng thành phần địa chỉ.
  - official_id: Mã hành chính chính thức từ Danh mục hành chính Quốc gia. Trường này chỉ trả về khi kết quả là đơn vị hành chính (ví dụ: phường, tỉnh/thành phố).
- geometry: Đối tượng với location (lat/lng), location_type, và viewport (northeast/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ả).
- partial_match: Boolean cho biết kết quả có phải là khớp một phần không.
- icon, icon_background_color: Thông tin hiển thị biểu tượng (nếu có).
- navigation_points: Mảng điểm điều hướng. Mỗi phần tử có location gồm latitude và longitude.
- old_address_components: (Chỉ có khi include_old_admin=true) Mảng các thành phần địa chỉ theo địa giới cũ, cùng cấu trúc với address_components
- old_formatted_address: (Chỉ có khi 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, old_address_components, types, navigation_points) sẽ là các phần tử lặp lại trong XML (như <result>, <address_component>, <old_address_component>, <type>, <navigation_point>).
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

Các trường trong phản hồi tuân theo Google Maps Geocoding API standard - Reverse Geocoding v3.
Phản hồi không bao gồm toàn bộ thông tin chi tiết của địa điểm. Để lấy thông tin đầy đủ nhất, hãy sử dụng API Place Detail.

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 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