Tìm kiếm lân cận (Mới)

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

Tìm kiếm lân cận (Mới) yêu cầu nhận một hoặc nhiều loại địa điểm và trả về một danh sách các địa điểm phù hợp trong vùng cụ thể. Mặt nạ trường chỉ định một hoặc nhiều loại dữ liệu là trường bắt buộc. Tính năng Tìm kiếm lân cận (Mới) chỉ hỗ trợ các yêu cầu POST.

API Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để bạn có thể làm quen với API và Tuỳ chọn API:

Hãy làm thử!

Hãy thử thuộc tính tương tác bản minh hoạ để xem kết quả Tìm kiếm lân cận (Mới) được hiển thị trên bản đồ.

Yêu cầu Tìm kiếm lân cận (Mới)

Yêu cầu Tìm kiếm lân cận (Mới) là một yêu cầu POST qua HTTP tới một URL trong biểu mẫu:

https://places.googleapis.com/v1/places:searchNearby

Truyền tất cả các tham số trong nội dung của yêu cầu JSON hoặc trong tiêu đề dưới dạng một phần của Yêu cầu POST. Ví dụ:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Câu trả lời cho tính năng Tìm kiếm lân cận (Mới)

Tính năng Tìm kiếm lân cận (Mới) trả về một đối tượng JSON làm phản hồi. Trong câu trả lời:

  • Mảng places chứa tất cả các địa điểm phù hợp.
  • Mỗi vị trí trong mảng được biểu thị bằng một Place . Đối tượng Place chứa thông tin chi tiết về một địa điểm.
  • FieldMask được chuyển trong yêu cầu chỉ định danh sách các trường đã trả về trong đối tượng Place.

Đối tượng JSON hoàn chỉnh có dạng:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Thông số bắt buộc

  • FieldMask

    Chỉ định danh sách các trường sẽ trả về trong phản hồi bằng cách tạo một mặt nạ trường phản hồi. Truyền mặt nạ trường phản hồi đến phương thức này bằng cách sử dụng tham số URL $fields hoặc fields hoặc bằng cách sử dụng tiêu đề HTTP X-Goog-FieldMask. Không có danh sách mặc định gồm các trường được trả về trong phản hồi. Nếu bạn bỏ qua mặt nạ trường, phương thức này sẽ trả về lỗi.

    Tạo mặt nạ cho trường là một phương pháp thiết kế hiệu quả để đảm bảo r��ng bạn sẽ không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý không cần thiết và các khoản phí thanh toán.

    Chỉ định danh sách các loại dữ liệu địa điểm được phân tách bằng dấu phẩy cần trả về. Ví dụ: để truy xuất tên hiển thị và địa chỉ của địa điểm.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Sử dụng * để truy xuất tất cả các trường.

    X-Goog-FieldMask: *

    Chỉ định một hoặc nhiều trường sau:

    • Các trường sau đây kích hoạt SKU của Tìm kiếm lân cận (Cơ bản):

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport

      * Trường places.name chứa địa điểm tên tài nguyên trong biểu mẫu: places/PLACE_ID. Sử dụng places.displayName để truy cập vào tên dạng văn bản của địa điểm.

    • Các trường sau đây kích hoạt SKU của Tìm kiếm lân cận (Nâng cao):

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri

    • Các trường sau đây kích hoạt SKU của Tìm kiếm lân cận (Ưu tiên):

      places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout

  • locationRestriction

    Vùng để tìm kiếm được chỉ định dưới dạng một hình tròn, được xác định bởi điểm tâm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng từ 0,0 đến 50000,0, bao gồm cả hai giá trị đó. Bán kính mặc định là 0.0. Bạn phải đặt nó trong yêu cầu của bạn thành một giá trị lớn hơn 0,0.

    Ví dụ: 

    "locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

Thông số tùy chọn

  • includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

    Cho phép bạn chỉ định danh sách các loại trong các loại Bảng A dùng để lọc kết quả tìm kiếm. Bạn có thể chỉ định tối đa 50 loại trong mỗi danh mục hạn chế loại.

    Một địa điểm chỉ có thể có một loại chính duy nhất trong các loại Bảng A được liên kết với nó. Ví dụ: loại chính có thể là "mexican_restaurant" hoặc "steak_house". Sử dụng includedPrimaryTypes và excludedPrimaryTypes để lọc kết quả loại hình chính của một địa điểm.

    Một địa điểm cũng có thể có nhiều giá trị loại từ các loại Bảng A liên kết với cuộc trò chuyện đó. Ví dụ: một nhà hàng có thể có các loại sau: "seafood_restaurant", "restaurant", "food" "establishment", "point_of_interest". Sử dụng includedTypes và excludedTypes để lọc kết quả trên danh sách các loại được liên kết với một địa điểm.

    Khi bạn chỉ định một loại chính chung, chẳng hạn như "restaurant" hoặc "hotel", câu trả lời có thể chứa các địa điểm có loại chính cụ thể hơn đồng hồ hẹn giờ được chỉ định. Ví dụ: bạn chỉ định bao gồm loại chính "restaurant". Sau đó, câu trả lời có thể chứa địa điểm có loại chính là "restaurant", nhưng câu trả lời cũng có thể chứa những địa điểm có từ khoá cụ thể hơn loại chính, chẳng hạn như "chinese_restaurant" hoặc "seafood_restaurant".

    Nếu nội dung tìm kiếm được chỉ định với hạn chế nhiều loại, thì chỉ địa điểm đáp ứng tất cả các hạn chế sẽ được trả về. Ví dụ: nếu bạn chỉ định {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, địa điểm được trả lại cung cấp "restaurant" dịch vụ liên quan nhưng không hoạt động chủ yếu dưới dạng "steak_house".

    includedTypes

    Danh sách các loại địa điểm được phân tách bằng dấu phẩy trong Bảng A cần tìm. Nếu tham số này bị bỏ qua, hàm sẽ trả về tất cả các loại địa điểm.

    excludedTypes

    Danh sách các loại địa điểm được phân tách bằng dấu phẩy trong Bảng A để loại trừ khỏi tìm kiếm.

    Nếu bạn chỉ định cả includedTypes ( chẳng hạn như "school") và excludedTypes (chẳng hạn như "primary_school") trong yêu cầu thì hàm này câu trả lời bao gồm các địa điểm được phân loại là "school" nhưng không phải là "primary_school". Câu trả lời bao gồm các địa điểm khớp với ít nhất một của includedTypes và không có mục nào trong số excludedTypes.

    Nếu có bất kỳ loại xung đột nào, chẳng hạn như một loại xuất hiện trong cả includedTypes và excludedTypes thì hệ thống sẽ trả về lỗi INVALID_REQUEST.

    includedPrimaryTypes

    Danh sách các loại địa điểm chính được phân tách bằng dấu phẩy trong Bảng A cần bao gồm trong một tìm kiếm.

    excludedPrimaryTypes

    Danh sách các loại địa điểm chính được phân tách bằng dấu phẩy trong Bảng A cần loại trừ khỏi một lượt tìm kiếm.

    Nếu có bất kỳ loại chính nào xung đột với nhau, chẳng hạn như một loại xuất hiện trong cả hai includedPrimaryTypes và excludedPrimaryTypes, một thuộc tính Trả về lỗi INVALID_ARGUMENT.

  • languageCode

    Ngôn ngữ mà kết quả trả về.

    • Xem danh sách ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể không đầy đủ.
    • Nếu bạn không cung cấp languageCode, thì API mặc định sẽ là en. Nếu bạn chỉ định mã ngôn ngữ không hợp lệ, API sẽ trả về INVALID_ARGUMENT .
    • API này sẽ cố gắng hết sức để cung cấp địa chỉ đường phố mà cả người dùng và người dùng có thể đọc được tại địa phương. Để đạt được mục tiêu đó, công cụ này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một tập lệnh mà người dùng có thể đọc nếu cần, tuân theo ngôn ngữ. Tất cả các địa chỉ khác sẽ được trả về bằng ngôn ngữ ưu tiên. Các thành phần địa chỉ là tất cả được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
    • Nếu tên không có sẵn bằng ngôn ngữ ưu tiên, API sẽ sử dụng kết quả phù hợp nhất.
    • Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến nhóm kết quả mà API chọn trả lại hàng và thứ tự mà chúng được trả về. Bộ mã hoá địa lý giải thích các chữ viết tắt khác nhau tuỳ theo ngôn ngữ, chẳng hạn như từ viết tắt cho loại đường phố hoặc từ đồng nghĩa có thể hợp lệ bằng một ngôn ngữ nhưng không hợp lệ bằng ngôn ngữ khác.

  • maxResultCount

    Chỉ định số lượng kết quả địa điểm tối đa cần trả về. Giá trị phải nằm trong khoảng 1 và 20 (mặc định).

  • rankPreference

    Loại thứ hạng sẽ sử dụng. Nếu tham số này bị bỏ qua, các kết quả được xếp hạng theo mức độ phổ biến. Có thể là một trong những trạng thái sau:

    • POPULARITY (mặc định) Sắp xếp kết quả dựa trên mức độ phổ biến.
    • DISTANCE Sắp xếp các kết quả theo thứ tự tăng dần theo khoảng cách từ vị trí được chỉ định.

  • regionCode

    Mã vùng dùng để định dạng phản hồi, được chỉ định làm mã CLDR gồm hai ký tự. Không có giá trị mặc định.

    Nếu tên quốc gia của trường formattedAddress trong phản hồi khớp với regionCode, mã quốc gia bị bỏ khỏi formattedAddress. Thông số này không ảnh hưởng đến adrFormatAddress (luôn bao gồm quốc gia) tên hoặc trên shortFormattedAddress, mà không bao giờ có tên đó.

    Hầu hết mã CLDR đều giống với mã ISO 3166-1, với một số ngoại lệ đáng chú ý. Ví dụ: ccTLD (miền cấp cao nhất theo mã quốc gia) của Vương quốc Anh là "Vương quốc Anh" (.co.uk) trong khi mã ISO 3166-1 của trang web là "gb" (về mặt kỹ thuật cho pháp nhân "Vương quốc Anh và Bắc Ireland"). Tuỳ theo luật hiện hành, thông số này có thể ảnh hưởng đến kết quả.

Ví dụ về tính năng Tìm kiếm lân cận (Mới)

Tìm địa điểm thuộc một loại

Ví dụ sau đây cho thấy yêu cầu Tìm kiếm lân cận (Mới) đối với màn hình tên của tất cả các nhà hàng trong bán kính 500 mét, do circle xác định: 

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Xin lưu ý rằng tiêu đề X-Goog-FieldMask chỉ định rằng phản hồi chứa các trường dữ liệu sau: places.displayName. Phản hồi thì sẽ có dạng:

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

Thêm các loại dữ liệu khác vào mặt nạ trường để trả về thông tin bổ sung. Ví dụ: thêm places.formattedAddress,places.types,places.websiteUri để bao gồm địa chỉ nhà hàng, loại và địa chỉ web trong câu trả lời:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

Phản hồi hiện ở dạng:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Tìm địa điểm thuộc nhiều loại

Ví dụ sau đây thể hiện yêu cầu Tìm kiếm lân cận (Mới) đối với lệnh hiển thị tên tất cả các cửa hàng tiện lợi và cửa hàng rượu trong vòng bán kính 1000 mét của circle được chỉ định:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
Ví dụ này sẽ thêm places.primaryType và places.types vào mặt nạ trường để câu trả lời bao gồm thông tin về loại về mỗi địa điểm, giúp bạn dễ dàng chọn vị trí thích hợp khỏi kết quả.

Ví dụ sau đây thể hiện yêu cầu về tính năng Tìm kiếm lân cận (Mới) cho tất cả địa điểm loại "school", không bao gồm tất cả địa điểm thuộc loại "primary_school", xếp hạng kết quả theo khoảng cách:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Tìm kiếm tất cả địa điểm gần một khu vực, xếp hạng theo khoảng cách

Ví dụ sau đây cho thấy yêu cầu về tính năng Tìm kiếm lân cận (Mới) cho các địa điểm gần một địa điểm trong trung tâm thành phố San Francisco. Trong ví dụ này, bạn đưa rankPreference vào tham số để xếp hạng kết quả theo khoảng cách:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Hãy dùng thử!

API Explorer cho phép bạn thực hiện các yêu cầu mẫu để mà bạn có thể làm quen với API và các tuỳ chọn API.

  1. Chọn biểu tượng API, Mở rộng API Explorer. ở bên phải của trang.
  2. (Không bắt buộc) Mở rộng tuỳ chọn Hiển thị các tham số chuẩn rồi đặt tham số fields vào mặt nạ trường.
  3. Chỉnh sửa Nội dung yêu cầu (không bắt buộc).
  4. Chọn nút Thực thi. Trong cửa sổ bật lên, hãy chọn tài khoản mà bạn muốn dùng để gửi yêu cầu.

  5. Trong bảng điều khiển API Explorer, hãy chọn biểu tượng mở rộng Mở rộng API Explorer., để mở rộng cửa sổ API Explorer.