Hướng dẫn chọn dịch vụ API Search và Autocomplete của TrackAsia

TrackAsia cung cấp các dịch vụ API bản đồ số chất lượng cao, được thiết kế đặc biệt cho thị trường Việt Nam, với mục tiêu tối ưu hóa chi phí, tích hợp dễ dàng và dữ liệu chính xác. Trong số các dịch vụ của TrackAsia, API Search và API Autocomplete là hai công cụ mạnh mẽ hỗ trợ tìm kiếm địa điểm và địa chỉ. Bài viết này sẽ hướng dẫn cách chọn giữa hai API này, giải thích sự khác biệt và các trường hợp sử dụng phù hợp để giúp bạn đưa ra quyết định đúng đắn.

Tổng quan về API Search và API Autocomplete của TrackAsia

API Search

API Search cho phép tìm kiếm địa chỉ, địa điểm hoặc thông tin địa lý dựa trên từ khóa hoặc điều kiện cụ thể.

Đặc điểm chính

• Có địa chỉ đầy đủ và cần tọa độ chính xác
• Tìm kiếm địa điểm cụ thể
• Cần kết quả cuối cùng thay vì gợi ý

Ví dụ sử dụng

// Tìm kiếm địa chỉ đầy đủ
const params = new URLSearchParams({
  query: 'Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh',
  key: 'public_key'
});

fetch(`https://maps.track-asia.com/api/v2/place/textsearch/json?${params}`)
  .then(res => res.json())
  .then(data => {
    const location = data?.results?.[0]?.geometry?.location;
    console.log('Tọa độ:', location);
  })
  .catch(err => {
    console.error('Lỗi truy vấn:', err);
  });

Kết quả

Từ khóa: "Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh"
Kết quả: Trả về tọa độ địa lý tương ứng với địa điểm được tìm kiếm

• "{ lat: 10.795845, lng: 106.716234 }"
  

Thông tin kết quả bao gồm tọa độ chính xác (vĩ độ, kinh độ) dùng để hiển thị địa điểm trên bản đồ hoặc xử lý các yêu cầu định vị tiếp theo. Kết quả thường là một đối tượng duy nhất phù hợp nhất với truy vấn văn bản tự nhiên.

API Autocomplete

API Autocomplete được thiết kế để gợi ý tìm kiếm nhanh địa chỉ hoặc địa điểm dựa trên một phần từ khóa mà người dùng nhập. Mục tiêu là hỗ trợ quá trình nhập liệu nhanh chóng và chính xác hơn, dựa trên dữ liệu địa danh chuẩn hóa trong hệ thống.

Đặc điểm chính

• Gợi ý tức thời: Trả về danh sách các địa điểm hoặc địa chỉ phù hợp ngay khi người dùng nhập một vài ký tự.
• Tối ưu trải nghiệm người dùng: Giúp người dùng nhanh chóng chọn đúng địa điểm mà không cần nhập toàn bộ từ khóa.
• Chỉ có từ khóa ngắn hoặc không rõ ràng

Ví dụ sử dụng

const params = new URLSearchParams({
  input: 'Landmark 81',
  bounds: '21.6463420,104.8429379;21.7503187,104.9330227',
  size: '2',
  new_admin: 'true',
  key: 'public_key'
});

const autocompleteUrl = 'https://maps.track-asia.com/api/v2/place/autocomplete/json?' + params;

fetch(autocompleteUrl)
  .then(res => res.json())
  .then(data => {
    console.log('Gợi ý:', data.predictions);
  })
  .catch(err => {
    console.error('Lỗi API:', err);
  });

Kết quả

Từ khóa: "Landmark 81"
Kết quả: Trả về danh sách gợi ý địa điểm phù hợp

• "KIMMAY Landmark 81, 772 Đường Điện Biên Phủ, Phường Vườn Lài, Thành phố Hồ Chí Minh"
  

• "MK Restaurant Landmark 81, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh"

Các kết quả bao gồm mô tả địa điểm, thường có thông tin phường/xã, tỉnh/thành. Dữ liệu gợi ý chủ yếu phục vụ mục tiêu hỗ trợ nhập liệu nhanh.

So sánh chi tiết

Luồng sử dụng thực tế

Kịch bản 1: Tìm địa chỉ cụ thể

// Bước 1: Gợi ý từ khóa với Autocomplete
const suggestions = 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')
  .then(r => r.json());

// Hiển thị gợi ý
console.log('Gợi ý địa điểm:', suggestions.predictions);

// Bước 2: Người dùng chọn địa điểm -> lấy tọa độ qua TextSearch
const selectedPlace = 'Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh';
const coordinates = await fetch(`https://maps.track-asia.com/api/v2/place/textsearch/json?query=${encodeURIComponent(selectedPlace)}&key=public_key`)
  .then(r => r.json());

// Lấy tọa độ
const placeLocation = coordinates.results[0].geometry.location;
console.log('Tọa độ:', placeLocation);

Kịch bản 2: Tìm kiếm trực tiếp

// Sử dụng Search ngay khi có địa chỉ đầy đủ
const fullAddress = 'Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh';

const result = await fetch(`https://maps.track-asia.com/api/v2/place/textsearch/json?query=${encodeURIComponent(fullAddress)}&key=public_key`)
  .then(r => r.json());

const coordinates = result.results[0].geometry.location;
console.log('Tọa độ:', coordinates);