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) lấy một hoặc nhiều loại địa điểm và trả về danh sách các địa điểm trùng khớp trong khu vực đã chỉ định. Bạn bắt buộc phải có mặt nạ trường 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.

Trình khám phá API cho phép bạn tạo 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ả của tính năng Tìm kiếm lân cận (Mới) 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à 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ả tham số trong phần 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

Câu trả lời cho Nearby Search (Mới)

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

  • Mảng places chứa tất cả địa điểm trùng khớ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 hoặc bằng cách sử dụng tiêu đề HTTP X-Goog-FieldMask. Không có danh sách mặc định về 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.

    Việc che trường là một phương pháp thiết kế hay để đả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í 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 để 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.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name**, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport

      * Trường places.googleMapsLinks đang ở giai đoạn Bản dùng thử trước khi phát hành công khai và không tính phí, tức là khoản thanh toán là 0 USD khi sử dụng trong Bản dùng thử.

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

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

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

    • Các trường sau đây sẽ kích hoạt SKU Tìm kiếm địa phương (Ư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.routingSummaries,* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout

      * Chỉ tìm kiếm bằng văn bản và tìm kiếm xung quanh

  • locationRestriction

    Khu vực cần tìm được chỉ định dưới dạng một hình tròn, được xác định bằng tâm điể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 đến 50000. Bán kính mặc định là 0.0. Bạn phải đặt giá trị 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

  • includedTypes/excludedTypes, includedPrimaryTypes/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 quy định hạn chế về loại.

    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". Sử dụng includedPrimaryTypes và excludedPrimaryTypes để lọc kết quả theo loại chính của đị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 đị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". 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.

    Khi bạn chỉ định một loại chính chung, chẳng hạn như "restaurant" hoặc "hotel", phản hồi có thể chứa các địa điểm có loại chính cụ thể hơn so với loại đã chỉ định. Ví dụ: bạn chỉ định thêm một loại chính là "restaurant". Sau đó, phản hồi có thể chứa các địa điểm có loại chính là "restaurant", nhưng phản hồi cũng có thể chứa các địa điểm có loại chính cụ thể hơn, chẳng hạn như "chinese_restaurant" hoặc "seafood_restaurant".

    Nếu một nội dung tìm kiếm được chỉ định với nhiều quy định hạn chế về loại, thì hệ thống sẽ chỉ trả về những địa điểm đáp ứng tất cả các quy định hạn chế đó. 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".

    includedTypes

    Danh sách được phân tách bằng dấu phẩy gồm các loại địa điểm trong Bảng A để tìm kiếm. Nếu bạn bỏ qua tham số này, hệ thống sẽ trả về tất cả các đị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 những địa điểm được phân loại là "school" nhưng không phải là "primary_school". Phản hồi bao gồm những địa điểm khớp với ít nhất một trong số includedTypes và không có địa điểm nào khớp với excludedTypes.

    Nếu có bất kỳ loại nào xung đột, 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ỳ loại chính nào xung đột, 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ữ dùng để trả về kết quả.

    • 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 cố gắng 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 đó, API 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 được nếu cần, tuân theo 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 không có tên nào bằng ngôn ngữ ưu tiên, thì API sẽ sử dụng tên gần 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ề và thứ tự trả về các kết quả đó. Trình dịch địa lý diễn giải các từ viết tắt khác nhau tuỳ theo ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường hoặc từ đồng nghĩa có thể hợp lệ trong 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ề. Phải nằm trong khoảng từ 1 đến 20 (mặc định).

  • rankPreference

    Loại thứ hạng cần sử dụng. Nếu bạn bỏ qua thông số này, kết quả sẽ được sắp xếp theo mức độ phổ biến. Có thể là một trong những loạ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 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 shortFormattedAddress (không bao giờ bao gồm tên quốc gia).

    Hầu hết mã CLDR giống hệt với mã ISO 3166-1, ngoại trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD 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à cho thực thể "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ề Nearby Search (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) về tên hiển thị của tất 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 nhà hàng 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 nhiều 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) về tên hiển thị của tất cả cửa hàng tiện lợi và cửa hàng bán đồ uống có cồn trong bán kính 1.000 mét của circle đã 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 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ả.

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, đượ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) về các địa điểm gần một điểm ở trung tâm thành phố San Francisco. Trong ví dụ này, bạn thêm tham số rankPreference để 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ử!

Trình khám phá API cho phép bạn tạo các yêu cầu mẫu để 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 Trình khám phá API., ở bên phải trang.
  2. Bạn có thể mở rộng phần Hiện các tham số chuẩn và đặt tham số fields thành mặt nạ trường.
  3. Chỉnh sửa Phần 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 để tạo yêu cầu.

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