Trang này được dịch bởi Cloud Translation API.

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

Yêu cầu Tìm kiếm lân cận (Mới) yêu cầu một hoặc nhiều loại địa điểm và trả về danh sách các địa điểm phù hợp trong khu vực đã chỉ định. Bạn cần phải có mặt nạ trường (field mask) chỉ định một hoặc nhiều loại dữ liệu. 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à các tuỳ chọn API:

Hãy làm thử!

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 cho một URL ở dạng:

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

Truyền tất cả tham số trong nội dung yêu cầu JSON hoặc trong tiêu đề như 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

Phản hồi về tính năng Tìm kiếm lân cận (Mới)

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 đối tượng Place. Đối tượng Place chứa thông tin chi tiết về một địa điểm duy nhất.
FieldMask (Mặt nạ) được truyền vào yêu cầu sẽ chỉ định danh sách các trường được 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 trường cần trả về trong phản hồi bằng cách tạo 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 bằng cách sử dụng tham số URL $fields hay fields, hoặc bằng tiêu đề HTTP X-Goog-FieldMask. Không có danh sách mặc định các trường được trả về trong phản hồi. Nếu bạn bỏ qua mặt nạ trường (field mask), phương thức sẽ trả về một lỗi.

Che giấu trường là một phương pháp thiết kế hay để đảm bảo bạn không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý và phí thanh toán không cần thiết.

Chỉ định danh sách các loại dữ liệu địa điểm cần trả về, được phân tách bằng dấu phẩy. 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
```
Lưu ý: Không được sử dụng dấu cách ở bất cứ vị trí nào trong danh sách trường.

Sử dụng * để truy xuất tất cả các trường.
```
X-Goog-FieldMask: *
```
Ký tự đại diện "*" chọn tất cả các trường. Tuy nhiên, mặc dù bạn có thể sử dụng ký tự đại diện đó trong quá trình phát triển, nhưng Google không khuyến khích việc sử dụng mặt nạ trường phản hồi ký tự đại diện (*) trong phiên bản chính thức vì lượng dữ liệu lớn có thể được trả về.

Bạn có thể xem thêm hướng dẫn về cách sử dụng places.iconMaskBaseUri và places.iconBackgroundColor trong mục Biểu tượng địa điểm.

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ính năng Tìm kiếm lân cận (Cơ bản):
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, 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.subDestinations, , , places.nameplaces.typesplaces.utcOffsetMinutesplaces.viewport
  
  places/PLACE_ID Sử dụng places.displayName để truy cập vào tên văn bản của địa điểm.
- Các trường sau đây kích hoạt SKU của tính năng 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 sẽ 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.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.servesBeer, places.delivery, places.menuForChildren, places.menuForChildrenplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout
locationRestriction

Khu vực cần tìm kiếm được chỉ định dưới dạng một vòng 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. Bán kính mặc định là 0,0. Bạn phải đặt tham số này trong yêu cầu của mình thành một giá trị lớn hơn 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 thuộ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ế về loại.

Lưu ý: Các giá trị trong Bảng B chỉ được trả về trong phản hồi. Bạn không thể dùng các giá trị trong Bảng B làm bộ lọc.

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

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

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

Nếu bạn bỏ qua includedTypes, excludedTypes, includedPrimaryTypes và excludedPrimaryTypes khỏi yêu cầu, thì lượt tìm kiếm sẽ trả về các địa điểm cho tất cả các loại trong giới hạn giới hạn về vị trí.

includedTypes

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

excludedTypes

Danh sách các loại địa điểm được phân tách bằng dấu phẩy từ 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ì phản hồi sẽ bao gồm các vị trí được phân loại là "school" chứ không phải là "primary_school". Phản hồi bao gồm các vị trí khớp với ít nhất một trong includedTypes và không có nơi nào trong 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ì lỗi INVALID_REQUEST sẽ được trả về.

includedPrimaryTypes

Danh sách các loại địa điểm chính được phân tách bằng dấu phẩy từ Bảng A để đưa vào nội dung 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 từ Bảng A để loại trừ khỏi kết quả 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ả includedPrimaryTypes và excludedPrimaryTypes, thì lỗi INVALID_ARGUMENT sẽ được trả về.
languageCode

Ngôn ngữ mà kết quả trả về.
- Xem danh sách các ngôn ngữ được hỗ trợ. Google thường cập nhật các ngôn ngữ được hỗ trợ, nên danh sách này có thể chưa đầy đủ.
- Nếu bạn không cung cấp languageCode, 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ề lỗi INVALID_ARGUMENT.
- API sẽ cố gắng hết sức để cung cấp một địa chỉ đường phố mà cả người dùng và người dân địa phương đều có thể đọc được. Để đạt được mục tiêu đó, phương thức này 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, đồng thời quan sát ngôn ngữ ưu tiên. Tất cả các địa chỉ khác sẽ được trả về bằng ngôn ngữ ưu tiên. Tất cả các thành phần địa chỉ đều đượ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, thì API sẽ sử dụng kết quả khớp nhất.
- Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến tập hợp kết quả mà API chọn để trả về, cũng như thứ tự trả về các kết quả đó. Bộ mã hoá địa lý diễn giải các từ viết tắt theo cách khác nhau tuỳ theo ngôn ngữ, chẳng hạn như cách viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ ở một ngôn ngữ nhưng không hợp lệ trong 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 từ 1 đến 20 (mặc định).
rankPreference

Loại xếp hạng sẽ sử dụng. Nếu thông số này bị bỏ qua, thì các kết quả sẽ đượ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í đã chỉ định.
regionCode

Mã vùng dùng để định dạng phản hồi, được chỉ định dưới dạng giá trị 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, thì mã quốc gia sẽ bị loại khỏi formattedAddress. Tham số này không ảnh hưởng đến adrFormatAddress (luôn bao gồm tên quốc gia) hoặc đối với shortFormattedAddress (không bao giờ bao gồm tên quốc gia).

Hầu hết các mã CLDR đều giống hệt với mã ISO 3166-1, trừ một số trường hợp 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à "uk" (.co.uk) trong khi mã ISO 3166-1 là "gb" (về mặt kỹ thuật, là pháp nhân của "Vương quốc Anh và Bắc Ireland"). Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

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

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

Ví dụ sau đây cho thấy một yêu cầu Tìm kiếm lân cận (Mới) cho tên hiển thị 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. Khi đó, phản hồi 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 (field mask) để trả về thông tin bổ sung. Ví dụ: thêm places.formattedAddress,places.types,places.websiteUri để đưa địa chỉ nhà hàng, loại và địa chỉ web vào phản hồ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 có 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 cho thấy một yêu cầu Tìm kiếm lân cận (Mới) cho tên hiển thị của tất cả các cửa hàng tiện lợi và cửa hàng rượu trong bán kính 1.000 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 thêm places.primaryType và places.types vào mặt nạ cho trường (field mask) để phản hồi bao gồm thông tin loại về từng địa điểm, giúp bạn dễ dàng chọn địa điểm thích hợp trong kết quả.

Loại trừ một loại địa điểm khỏi kết quả tìm kiếm

Ví dụ sau đây cho thấy một yêu cầu Tìm kiếm lân cận (Mới) cho tất cả các địa điểm thuộc loại "school", ngoại trừ tất cả cá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 một yêu cầu Tìm kiếm lân cận (Mới) cho các địa điểm gần một điểm trong trung tâm thành phố San Francisco. Trong ví dụ này, bạn đưa vào tham số rankPreference để xếp hạng các 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 để bạn có thể làm quen với các API và các tuỳ chọn API.

Chọn biểu tượng API ở bên phải của trang.
(Không bắt buộc) Mở rộng mục Show standard parameters (Hiện thông số chuẩn) và đặt tham số fields thành field mask (mặt nạ trường).
Chỉnh sửa Nội dung yêu cầu nếu muốn.
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.
Trong bảng điều khiển API Explorer, hãy chọn biểu tượng mở rộng, , để mở rộng cửa sổ API Explorer.

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

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

Phản hồi về tính năng Tìm kiếm lân cận (Mới)

Thông số bắt buộc

FieldMask

locationRestriction

Thông số tùy chọn

includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode