Autocomplete with Place Detail per Session

Giảm chi phí vận hành và tăng trải nghiệm người dùng với việc cung cấp tính năng tự động đề xuất và hiển thị thông tin địa điểm trong cùng 1 phiên gọi API.

Hướng dẫn dưới đây, sẽ giúp bạn tích hợp tính năng tự động đề xuất và đồng thời có tính năng hiển thị thông tin địa điểm đi kèm trong 1 phiên gọi API. Sau khi hoàn thiện việc tích hợp 2 tính năng trong một phiên gọi API, người dùng của bạn có thể nhanh chóng tìm thấy địa điểm mong muốn và nhận được thông tin chi tiết cho địa điểm đó một cách liền mạch hơn.

🛡️ Giải thích về session token trong Autocomplete + Place Detail

Khi sử dụng tính năng Autocomplete, bạn nên truyền thêm tham số sessiontoken (UUID v4) cho mỗi phiên tìm kiếm của người dùng. Điều này giúp hệ thống nhận biết các truy vấn liên quan trong cùng một phiên, từ đó:

Tối ưu chi phí: Các truy vấn Place Detail sau khi chọn gợi ý từ Autocomplete sẽ không bị tính phí riêng, chỉ tính phí cho phiên truy vấn Autocomplete ban đầu.
Trải nghiệm mượt mà: Người dùng có thể tìm kiếm, chọn địa điểm và xem chi tiết mà không bị tính phí lặp lại cho cùng một kết quả.

Cách hoạt động

Bước 1: Khi người dùng bắt đầu nhập từ khóa, ứng dụng tạo một sessiontoken (UUID v4) và truyền vào mỗi lần gọi Autocomplete.
Bước 2: Người dùng có thể thực hiện nhiều truy vấn Autocomplete với cùng một sessiontoken.
Bước 3: Khi người dùng cuối cùng chọn một địa điểm và bạn gọi Place Detail với cùng sessiontoken, tất cả các truy vấn Autocomplete trước đó và lần gọi Place Detail này sẽ được tính là một phiên truy vấn.
Bước 4: Chỉ phiên truy vấn này được tính phí một lần duy nhất.

Lưu ý:

sessiontoken là một chuỗi UUID v4 do phía client (ứng dụng của bạn) tự tạo và truyền vào mỗi request.

Mỗi sessiontoken chỉ có hiệu lực trong 5 phút kể từ khi được tạo. Sau 5 phút, bạn cần tạo sessiontoken mới cho phiên tìm kiếm tiếp theo.

Nếu gọi Place Detail mà không truyền đúng sessiontoken đã dùng cho Autocomplete, hệ thống sẽ tính phí như một truy vấn độc lập.

Ví dụ minh họa

# 1. Gọi Autocomplete với sessiontoken
GET /autocomplete?input=Lotte Mall Tây Hồ&sessiontoken=576e6543-fbc8-422c-9aad-9884c97df128

# 2. Gọi Place Detail cho một địa điểm trong kết quả autocomplete, dùng lại sessiontoken
GET /place?ids=aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc&sessiontoken=576e6543-fbc8-422c-9aad-9884c97df128

Kết quả:

Chỉ tính phí cho truy vấn Autocomplete.
Truy vấn Place Detail không bị tính phí thêm nếu dùng đúng sessiontoken.

Tóm tắt

Luôn tạo mới sessiontoken cho mỗi phiên tìm kiếm.
Dùng lại sessiontoken đó cho tất cả các truy vấn Place Detail liên quan đến kết quả Autocomplete.
Chỉ tính phí cho Autocomplete, không tính phí cho Place Detail nếu cùng sessiontoken.

Base URL

Mã URL chung cho tất các yêu cầu API: https://mapapis.openmap.vn/v1

Endpoint

GET /autocomplete

Ví dụ

Tạo một session token dạng UUID v4: 576e6543-fbc8-422c-9aad-9884c97df128, lưu nó ở phiên trong ứng dụng của bạn.

Bạn có thể tạo một session token dạng UUID v4 bằng cách sử dụng UUID v4 Generator

Yêu cầu:

GET /autocomplete?input=Lotte Mall Tây Hồ&sessiontoken=576e6543-fbc8-422c-9aad-9884c97df128

Trả về:

{
  "predictions": [
    {
      "description": "Lotte Mall Tây Hồ, 272 Đường Võ Chí Công, phường Phú Thượng, quận Tây Hồ, thành phố Hà Nội",
      "distance_meters": null,
      "matched_substrings": [],
      "place_id": "aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc",
      "structured_formatting": {
        "main_text": "Lotte Mall Tây Hồ",
        "main_text_matched_substrings": [],
        "secondary_text": "272 Đường Võ Chí Công, phường Phú Thượng, quận Tây Hồ, thành phố Hà Nội",
        "secondary_text_matched_substrings": []
      },
      "terms": [
        {
          "offset": 0,
          "value": "Lotte Mall Tây Hồ"
        },
        {
          "offset": 21,
          "value": "272 Đường Võ Chí Công"
        },
        {
          "offset": 51,
          "value": "phường Phú Thượng"
        },
        {
          "offset": 77,
          "value": "quận Tây Hồ"
        },
        {
          "offset": 95,
          "value": "thành phố Hà Nội"
        }
      ],
      "types": ["business_center"]
    }
  ],
  "status": "OK"
}

Sau đó bạn có thể dùng trường id cùng với tham số sessiontoken để có thể biết thêm các thông tin về địa điểm đó như số điện thoại, website, giờ mở cửa,...

Yêu cầu:

GET /place?ids=aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc&sessiontoken=576e6543-fbc8-422c-9aad-9884c97df128&format=google

Trả về:

{
  "result": {
    "address_components": [
      {
        "long_name": "Lotte Mall Tây Hồ",
        "short_name": "Lotte Mall Tây Hồ"
      },
      {
        "long_name": "272 Đường Võ Chí Công",
        "short_name": "272 Đường Võ Chí Công"
      },
      {
        "long_name": "phường Phú Thượng",
        "short_name": "Phú Thượng"
      },
      {
        "long_name": "quận Tây Hồ",
        "short_name": "Tây Hồ"
      },
      {
        "long_name": "thành phố Hà Nội",
        "short_name": "Hà Nội"
      }
    ],
    "formatted_address": "Lotte Mall Tây Hồ, 272 Đường Võ Chí Công, phường Phú Thượng, quận Tây Hồ, thành phố Hà Nội",
    "geometry": {
      "location": {
        "lat": 21.075951,
        "lng": 105.812662
      },
      "viewport": null
    },
    "name": "Lotte Mall Tây Hồ",
    "place_id": "aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc",
    "types": ["business_center"],
    "url": "https://openmap.vn/place/aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc"
  },
  "status": "OK"
}

Yêu cầu:

GET /place?ids=aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc&sessiontoken=576e6543-fbc8-422c-9aad-9884c97df128

Trả về:

{
  "errors": null,
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [105.812662, 21.075951],
        "type": "Point"
      },
      "properties": {
        "name": "Lotte Mall Tây Hồ",
        "housenumber": null,
        "street": null,
        "short_address": "272 Đường Võ Chí Công",
        "postalcode": null,
        "label": "Lotte Mall Tây Hồ, 272 Đường Võ Chí Công, phường Phú Thượng, quận Tây Hồ, thành phố Hà Nội",
        "country": "Việt Nam",
        "country_code": "VN",
        "category": ["business_center"],
        "website": "https://lottemallwestlakehanoi.vn/",
        "opening_hours": [
          [
            [0, 9, 30],
            [0, 22, 0]
          ],
          [
            [1, 9, 30],
            [1, 22, 0]
          ],
          [
            [2, 9, 30],
            [2, 22, 0]
          ],
          [
            [3, 9, 30],
            [3, 22, 0]
          ],
          [
            [4, 9, 30],
            [4, 22, 0]
          ],
          [
            [5, 9, 30],
            [5, 22, 0]
          ],
          [
            [6, 9, 30],
            [6, 22, 0]
          ]
        ],
        "phone": "+842433338000",
        "region": "thành phố Hà Nội",
        "county": "quận Tây Hồ",
        "locality": "phường Phú Thượng",
        "distance": null,
        "id": "aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc",
        "continent": "Asia",
        "source": "openmapvn"
      }
    }
  ],
  "bbox": [],
  "type": "FeatureCollection"
}

Autocomplete with Place Detail per Session

🛡️ Giải thích về session token trong Autocomplete + Place Detail​

Cách hoạt động​

Ví dụ minh họa​

Tóm tắt​

Base URL​

Endpoint​

Ví dụ​

🛡️ Giải thích về session token trong Autocomplete + Place Detail

Cách hoạt động

Ví dụ minh họa

Tóm tắt

Base URL

Endpoint

Ví dụ