AUTOCOMPLETE (GỢI Ý ĐỊA ĐIỂM)

TỔNG QUAN

Autocomplete API là dịch vụ tự động gợi ý tìm kiếm nhanh địa chỉ, địa điểm dựa trên từ khóa người dùng nhập giúp dễ dàng chọn lựa và chọn đúng kết quả cần tìm kiếm. Khi người dùng nhập từ khóa, dịch vụ sẽ trả về danh sách gợi ý phù hợp, có thể kèm theo giới hạn địa lý nếu cần. Dịch vụ này hỗ trợ hiển thị các gợi ý như tên doanh nghiệp, địa chỉ hoặc các địa điểm yêu thích… dựa trên vị trí địa lý liên quan đến nội dung tìm kiếm.

Goong cho phép các nhà phát triển tích hợp tính năng Autocomplete vào nền tảng hoặc ứng dụng của họ. Khi người dùng nhập thông tin, API sẽ tự động đề xuất các kết quả tiềm năng dựa trên dữ liệu đã nhập. Điều này giúp người dùng dễ dàng và nhanh chóng tìm kiếm, chọn lựa địa điểm chính xác từ danh sách gợi ý đưa ra.

Bạn có thể thêm tính năng Autocomplete vào ứng dụng hoặc trang web của mình bằng cách sử dụng tiện ích Autocomplete địa điểm từ việc tạo một trường nhập dữ liệu văn bản.

 Khi người dùng nhập văn bản, tính năng Autocomplete sẽ trả về các cụm từ gợi ý địa điểm dưới dạng một danh sách danh sách chọn. Khi người dùng chọn một địa điểm trong danh sách, thông tin về địa điểm đó sẽ được trả về và ứng dụng của bạn có thể truy xuất thông tin địa điểm này.

Điều kiện bắt buộc

Để sử dụng Autocomplete API, bạn phải có tài khoản đã được kích hoạt và có API key để bắt đầu tích hợp.

Các tính năng hỗ trợ

Tính năng Autocomplete được thiết kế tối ưu nhất cho người dùng theo các cách như sau:

• Được thiết kế phù hợp với đặc đặc trưng khu vực người dùng Việt Nam, bao gồm cả ngôn ngữ vùng miền, chữ viết tắt, viết sai chính tả…
• Hiệu suất ngày càng được cải thiện, độ chính xác cao và dữ liệu gợi ý chi tiết đến tận các vùng ngoại ô, rìa thành phố, vùng nông thôn và các cột sân bay, cổng, sảnh trung tâm thương mại….

CÁCH THỨC TÍCH HỢP AUTOCOMPLETE

Bạn có thể tích hợp Autocomplete API vào ứng dụng/trang web của bạn trên cả nền bản đồ của Goong hoặc các nền bản đồ khác.

Cách thêm

Trước khi bắt đầu sử dụng dịch vụ Autocomplete API của Goong, bạn cần đảm bảo rằng đã có API key của mình. 

Bạn có thể tham khảo cách đăng ký tài khoản và tạo key chi tiết tại đây.

URL: /place/autocomplete

Phương thức: GET

Ví dụ về request:

curl 'https://rsapi.goong.io/place/autocomplete?input=aqua&location=10.700920276971795%2C%20106.73296613898738&limit=10&radius=10&api_key={YOUR_API_KEY}'

Ví dụ về response:

application/json
{
  "predictions": [
    {
      "description": "91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "matched_substrings": [],
      "place_id": "Hobn8WqBW6rsKtKq2PDrVKp4BJNRtiILxTQbB__muXgRB3v8GRDTfkp_6lc4cbLw/5PUgWrMDrSI/xlqDBt5XA==.ZXhwYW5kMA==",
      "reference": "o/QzXNc_eBKsOWX6kdbOcABtO4zUQz0lzdK1jpi0R__J2vFKeRAM2VSYo38AfaShP/7qpUhrwc0l/t/AIYwRnQ==.ZXhwYW5kMA==",
      "structured_formatting": {
        "main_text": "91 Trung Kính",
        "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội"
      },
      "terms": [],
      "has_children": false,
      "display_type": "expand0",
      "score": 633.7587,
      "plus_code": {
        "compound_code": "+6DW1G Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+6DW1G"
      }
    },
    {
      "description": "43/91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "matched_substrings": [],
      "place_id": "ytdKslLHBd1_mSnLu_bQHGu1yZyLeBt9haGgyFDN1EIOy7I9uEQyTmRkyNZL3BRpT_Knj31YK/Irv3KkEIIZqw==.ZXhwYW5kMA==",
      "reference": "nP7fBjweFzWzkU8gq/ki_xEAF3fpVoZ3aQcfXx4ZRHX7QaQPNBPpNToMKx1KZw09gWUhpnSdXJSLowB4qFlCMg==.ZXhwYW5kMA==","structured_formatting": {
        "main_text": "43/91 Trung Kính",
        "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội"
      },
      "terms": [],
      "has_children": false,
      "display_type": "expand0",
      "score": 597.5509,
      "plus_code": {
        "compound_code": "+63G73 Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+63G73"
      }
    },
    {
      "description": "95 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "matched_substrings": [],
      "place_id": "mUuwMwTPf5/1WFznDr94rtLvQffNhj1NzWQqDJqgsdUfCqTZdUcHTTav64BxPOC6dSdgZ9WUmwARwQlhmYonvA==.ZXhwYW5kMA==",
      "reference": "lPHbKnLx64d2Ikp35RrFcdRphjayJn2rjapjNhjPuBmPxB9GzirgM6NT0OH65gG2Mf4qGswZXQ8d6U4XBfltjQ==.ZXhwYW5kMA==",
      "structured_formatting": {
        "main_text": "95 Trung Kính",
        "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội"
      },
      "terms": [],
      "has_children": false,
      "display_type": "expand0",
      "score": 358.45456,
      "plus_code": {
        "compound_code": "+6DW1M Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+6DW1M"
      }
    },
    {
      "description": "93 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "matched_substrings": [],
      "place_id": "xFchTd18UNmq7/rWipBrI6LtqEcDdReZ8cGV3mxeK4yxmmL7hZat/i8cLBdGhdaeNYFQLk4H5AuP2ntIHfS7EQ==.ZXhwYW5kMA==",
      "reference": "dMG3Lmo6Rux8NsEd9lwoDGUOH22aZbMdzDiMy1RhS73mM/uA0rZsX2M0y0Wm990nx4PGw1jd54YkUeqLzySwaQ==.ZXhwYW5kMA==",
      "structured_formatting": {
        "main_text": "93 Trung Kính",
        "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội"
      },
      "terms": [],
      "has_children": false,
      "display_type": "expand0",
      "score": 358.1594,
      "plus_code": {
        "compound_code": "+6DW1I Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+6DW1I"
      }
    },
    {
      "description": "89 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "matched_substrings": [],
      "place_id": "OTzyxbl3DUoqV90GZW8D_2FCVMaEizDWVmAhzTc2d8KmYL/h2cPpfE97BmSabHzliRz3GSgjXWVRxI0bZMxqew==.ZXhwYW5kMA==",
      "reference": "7ESn5kbjYSJJfOstrAkpIRG26bEQi1atPuZKWKyymY9Q7raTcScHyAFeWejvoiu_aa46E/IYxOvOPsmkZgYfOQ==.ZXhwYW5kMA==",
      "structured_formatting": {
        "main_text": "89 Trung Kính",
        "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội"
      },
      "terms": [],
      "has_children": false,
      "display_type": "expand0",
      "score": 358.14783,
      "plus_code": {
        "compound_code": "+6DW1E Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+6DW1E"
      }
    }
  ],
  "executed_time": 61,
  "executed_time_all": 63,
  "status": "OK"
}

GIỚI HẠN CÁC CỤM TỪ GỢI Ý CỦA AUTOCOMPLE

Theo mặc định, tính năng Autocomplete sẽ hiển thị tất cả các địa điểm có liên quan đến các cụm tìm kiếm dẫn đến nhiều địa điểm không chuẩn. Chính vì vây, ta có thể đặt các tuỳ chọn gợi ý về địa điểm để đưa ra thông tin gợi ý phù hợp hơn bằng cách hạn chế kết quả tìm kiếm.

Mặc định, tính năng Autocomplete sẽ hiển thị tất cả các địa điểm liên quan đến từ khóa tìm kiếm, dẫn đến việc xuất hiện nhiều kết quả không chính xác. Để cải thiện, ta có thể đặt hạn chế các gợi ý địa điểm, giúp thu hẹp kết quả tìm kiếm và đưa ra các đề xuất chính xác hơn.

Việc hạn chế kết quả sẽ khiến tiện ích Autocomplete bỏ qua các kết quả nằm ngoài vùng hạn chế. Một phương pháp phổ biến là giới hạn kết quả trong một phạm vi bán kính nhất định. Kết quả của Autocomplete trả về sẽ chỉ hiển thị kết quả trong khu vực được chỉ định:

• Hạn chế tìm kiếm địa điểm theo bán kính (radius).
• Gợi ý tìm kiếm xung quanh địa chỉ cụ thể (location).

Ví dụ:

• Khi người dùng nhập input là “aqua” và không sử dụng thêm tính năng giới hạn:

curl 'https://rsapi.goong.io/place/autocomplete?input=aqua&api_key={YOUR_API_KEY}'

Kết quả trả về sẽ ưu tiên các kết quả gần Hà Nội:

{
   "predictions": [
       {
          "description": "Aqua, 30 Phan Bội Châu, Phường Cửa Nam, Quận Hoàn Kiếm, Thành phố Hà Nội",
         ...
       },
       {
          "description": "AQUA Cafe, Phường Cổ Nhuế 1, Quận Bắc Từ Liêm, Thành phố Hà Nội",
          ...
       },
        ....
   ],
   "execution_time": "",
    "status": "OK"
}

• Khi người dùng nhập input tương tự “aqua” nhưng thêm địa chỉ (location ở Hồ Chí Minh, 10.700920276971795, 106.73296613898738) và bán kính (radius, 10):

curl 'https://rsapi.goong.io/place/autocomplete?input=aqua&api_key={YOUR_API_KEY}&location=10.700920276971795%2C%20106.73296613898738'

Kết quả trả về sẽ là các địa điểm ở Hồ Chí Minh:

{
   "predictions": [
        {
            "description": "Aqua Clinic, 67 Nguyễn Trãi, Phường Bến Thành, Quận 1, Thành phố Hồ Chí Minh",
            ...
        },
        {
            "description": "Aqua Day spa, Khách sạn Sheraton Sài Gòn, 88 Đồng Khởi, Phường Bến Nghé, Quận 1, Thành phố Hồ Chí Minh",
            ...
        },
        {
            "description": "Aqua sport wear, Chung cư Ngô Gia Tự, 28 Lô L Hòa Hảo, Phường 2, Quận 10, Thành phố Hồ Chí Minh",
            ...
        },
        {
            "description": "Aqua Hotel, 25 Hẻm 207 Nguyễn Văn Đậu, Phường 11, Quận Bình Thạnh, Thành phố Hồ Chí Minh",
            ...
        },
        {
            "description": "Aquarium Cafe, 1117 Phan Văn Trị, Phường 10, Quận Gò Vấp, Thành phố Hồ Chí Minh",
            ...
        }
   ],...
}