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

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

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

Yêu cầu Tìm kiếm lân cận (Mới) sẽ nhận 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. Cần có mặt nạ trường để chỉ định một hoặc nhiều loại dữ liệu. 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 để làm quen với API và các tuỳ chọn API:

Hãy làm thử!

Hãy thử bản minh hoạ tương tác để xem kết quả Tìm kiếm lân cận (Mới) xuất hiện 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à yêu cầu POST qua HTTP tới một URL có 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 đối tượng Place. Đối tượng Place chứa thông tin chi tiết về một địa điểm.
FieldMask (Mặt nạ trường) được chuyển trong 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 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 bằng cách sử dụng tham số URL $fields hoặc fields hay 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 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à các khoản 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 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
```
Lưu ý: Không được dùng dấu cách ở bất cứ đâu 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ể 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ì số lượng lớn dữ liệu 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 phần 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ì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, , , , , , , , , {2, places.shortFormattedAddress, places.location, places.name^*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.typesplaces.utcOffsetMinutesplaces.viewport
  
  places/PLACE_ID Hãy 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.delivery, places.servesBreakfast, places.servesBreakfast, places.delivery, places.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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 tham số này trong yêu cầu của mình 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.

Lưu ý: Các giá trị trong Bảng B chỉ được trả về trong phản hồi. Bạn không thể sử 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 các loại Bảng A 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ả theo loại 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 được liên kết với địa điểm đó. Ví dụ: một nhà hàng có thể có những loại sau: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Hãy sử dụng includedTypes và excludedTypes để lọc kết quả theo danh sách các loại liên kết với một địa điểm.

Nếu một lượt tìm kiếm được chỉ định với nhiều hạn chế về loại, thì chỉ những vị trí đáp ứng tất cả các hạn chế đó mới được trả về. Ví dụ: nếu bạn chỉ định {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, thì các vị trí được trả về 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ì kết quả tìm kiếm sẽ trả về vị trí cho tất cả các loại trong giới hạn giới hạn vị trí.

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 kết quả 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 số includedTypes và không có vị trí 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ì 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 trong 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 trong Bảng A để loại trừ khỏi kết quả tìm kiếm.

Nếu có bất kỳ kiểu chính nào xung đột, chẳng hạn như một kiểu 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 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ể chưa đầ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ề lỗi 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ân địa phương đều có thể đọc được. Để đạt được mục tiêu đó, công cụ này trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang tập lệnh mà người dùng có thể đọc nếu cần, qua đó 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, 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 tập hợp kết quả mà API chọn trả về và thứ tự trả về các kết quả đó. Bộ mã hoá địa lý diễn giải các chữ viết tắt theo cách khác nhau tuỳ thuộc vào 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ệ ở ngôn ngữ này nhưng không hợp lệ ở ngôn ngữ khác.
maxResultCount

Chỉ định số lượng kết quả địa điểm tối đa cần trả về. Phải nằm trong khoảng từ 1 đến 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í đã 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 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ị bỏ qua trong formattedAddress. Thông số này không ảnh hưởng đến adrFormatAddress (luôn bao gồm tên quốc gia) hoặc trên shortFormattedAddress (không bao giờ có tên quốc gia).

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à "uk" (.co.uk) trong khi mã ISO 3166-1 của mã này là "gb" (về mặt kỹ thuật là "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 một yêu cầu Tìm kiếm lân cận (Mới) đối với 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. Sau đó, 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 để trả về thông tin bổ sung. Ví dụ: thêm places.formattedAddress,places.types,places.websiteUri để đưa địa chỉ, loại và địa chỉ web của nhà hàng vào 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 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 phạm vi 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ạ trường để phản hồi bao gồm thông tin về loại về từng địa điểm, giúp bạn dễ dàng chọn địa điểm phù hợp trong kết quả.

Loại trừ 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 về tính năng 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 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 tham số rankPreference vào để 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 đưa ra các yêu cầu mẫu để có thể làm quen với 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 tuỳ chọn Show standard parameters (Hiện các tham số chuẩn) và đặt tham số fields thành fieldMask (mặt nạ trường).
Chỉnh sửa Nội dung yêu cầu (không bắt buộc).
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)

Câu trả lời cho 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