搜尋附近地點 (新)

選取平台： Android iOS JavaScript 網頁服務

Nearby Search (新版) 要求會採用一或多個地點類型，傳回指定區域內相符地點的清單。您必須指定一或多個資料類型的欄位遮罩。Nearby Search (新版) 僅支援 POST 要求。

您可以透過 API Explorer 提出即時要求，熟悉 API 和 API 選項：

試試看！

請試用互動式示範，瞭解鄰近搜尋 (新版) 結果如何顯示在地圖上。

Nearby Search (新版) 要求

附近搜尋 (新版) 要求是對下列格式中的網址發出的 HTTP POST 要求：

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

在 JSON 要求主體或標頭中，將所有參數傳遞為 POST 要求的一部分。例如：

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

Nearby Search (新版) 回應

Nearby Search (新版) 會傳回 JSON 物件做為回應。在回應中：

  • places 陣列包含所有相符的地點。
  • 陣列中的每個位置都由 Place 物件表示。Place 物件包含單一地點的詳細資訊。
  • 在要求中傳遞的 FieldMask 會指定 Place 物件中傳回的欄位清單。

完整的 JSON 物件格式如下：

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

必要參數

  • FieldMask

    建立回應欄位遮罩，指定要在回應中傳回的欄位清單。使用網址參數 $fields 或 fields，或使用 HTTP 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至方法。回應中沒有傳回欄位的預設清單。如果省略欄位遮罩，方法會傳回錯誤。

    欄位遮罩是良好的設計做法，可確保您不會要求不必要的資料，有助於避免不必要的處理時間和帳單費用。

    指定要傳回的地點資料類型清單 (以半形逗號分隔)。例如擷取地點的顯示名稱和地址。

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

    使用 * 擷取所有欄位。

    X-Goog-FieldMask: *

    指定下列一或多個欄位：

    • 以下欄位會觸發 Nearby Search (Basic) SKU：

      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

      *places.googleMapsLinks 欄位處於 GA 前測試階段，因此在測試期間使用時不會產生任何費用，也就是帳單金額為 $0 美元。

      ** places.name 欄位包含地點資源名稱，格式為：places/PLACE_ID。使用 places.displayName 存取地點的文字名稱。

    • 下列欄位會觸發 Nearby Search (Advanced) SKU：

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

    • 以下欄位會觸發 Nearby Search (Preferred) SKU：

      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

      *僅限文字搜尋和附近搜尋

  • locationRestriction

    要搜尋的區域以圓形表示，並以中心點和半徑 (以公尺為單位) 定義。半徑必須介於 0.0 和 50000.0 之間 (含首尾)。預設半徑為 0.0。您必須在要求中將其設為大於 0.0 的值。

    例如： 

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

選用參數

  • includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

    讓您從 Table A 的類型指定清單，用於篩選搜尋結果。每個類型限制類別最多可指定 50 個類型。

    地點只能有 單一主要類型，且該類型必須與 表格 A 中的類型相關聯。例如，主要類型可能是 "mexican_restaurant" 或 "steak_house"。使用 includedPrimaryTypes 和 excludedPrimaryTypes 篩選地點的主要類型結果。

    地點也可以有多個類型值，這些值來自與其相關聯的 表 A 類型。舉例來說，餐廳可能有以下類型："seafood_restaurant"、"restaurant"、"food"、"point_of_interest"、"establishment"。使用 includedTypes 和 excludedTypes 篩選與地點相關聯的類型清單結果。

    指定一般主要類型 (例如 "restaurant" 或 "hotel") 時，回應可能包含比指定類型更具體的類型。例如，您可以指定要納入主要類型 "restaurant"。回應可包含主要類型為 "restaurant" 的地點，但也可能包含主要類型更具體 (例如 "chinese_restaurant" 或 "seafood_restaurant") 的地點。

    如果搜尋指定多個類型限制，系統只會傳回符合所有限制的場所。舉例來說，如果您指定 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}，則傳回的位置會提供 "restaurant" 相關服務，但主要並非以 "steak_house" 的形式運作。

    includedTypes

    以半形逗號分隔的清單，列出要搜尋的 表 A 中地點類型。 如果省略這項參數，系統會傳回所有類型的地點。

    excludedTypes

    表 A 中以半形逗號分隔的地點類型清單，用於排除搜尋結果。

    如果您在要求中同時指定 includedTypes ( 例如 "school") 和 excludedTypes (例如 "primary_school")，回應就會包含歸類為 "school" 但非 "primary_school" 的場所。回應會包含與 includedTypes 的至少一個和 excludedTypes 的沒有一個相符的地點。

    如果有任何相衝突的類型，例如同時出現在 includedTypes 和 excludedTypes 中的類型，系統會傳回 INVALID_REQUEST 錯誤。

    includedPrimaryTypes

    以半形逗號分隔的清單，列出要納入搜尋的 表 A 中主要地點類型。

    excludedPrimaryTypes

    以半形逗號分隔的清單，列出表 A中要從搜尋結果中排除的主要地點類型。

    如果有任何衝突的主要類型，例如 includedPrimaryTypes 和 excludedPrimaryTypes 都出現同一個類型，系統會傳回 INVALID_ARGUMENT 錯誤。

  • languageCode

    傳回結果時使用的語言。

    • 請參閱支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
    • 如果未提供 languageCode，API 會預設為 en。如果指定無效的語言代碼，API 會傳回 INVALID_ARGUMENT 錯誤。
    • API 會盡力提供使用者和當地人都看得懂的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要將其轉寫為使用者可讀的文字，並遵循慣用語言。系統會以偏好語言傳回所有其他地址。地址元件會以相同的語言傳回，該語言會從第一個元件中選取。
    • 如果名稱無法以偏好語言顯示，API 會使用最接近的值。
    • 偏好語言對 API 選擇要傳回的結果集合，以及傳回的順序影響不大。地理編碼器會根據語言解讀縮寫，例如街道類型的縮寫，或是在某種語言中有效，但在其他語言中無效的同義字。

  • maxResultCount

    指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設值) 之間。

  • rankPreference

    要使用的排名類型。如果省略這個參數，系統會依熱門程度排序結果。可能是下列其中一個值：

    • POPULARITY (預設) 依據結果的熱門程度排序。
    • DISTANCE 依遞增順序排序結果，依據的是地點與指定位置之間的距離。

  • regionCode

    用於格式化回應的區碼，指定為 兩個字元的 CLDR 代碼值。沒有預設值。

    如果回應中 formattedAddress 欄位的國家/地區名稱與 regionCode 相符，formattedAddress 就會省略國家/地區代碼。這個參數不會影響 adrFormatAddress (一律包含國家/地區名稱) 或 shortFormattedAddress (一律不包含國家/地區名稱)。

    大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是「大不列顛與北愛爾蘭聯合王國」實體)。這個參數可能會影響根據適用法律產生的結果。

Nearby Search (新版) 範例

尋找某一類型的地點

以下範例顯示 Nearby Search (新版) 要求，要求顯示半徑 500 公尺內所有餐廳的顯示名稱，此半徑由 circle 定義：

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

請注意，X-Goog-FieldMask 標頭會指定回應包含以下資料欄位：places.displayName。回應的格式如下：

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

將更多資料類型新增至欄位遮罩，以便傳回其他資訊。舉例來說，您可以新增 places.formattedAddress,places.types,places.websiteUri，在回應中加入餐廳地址、類型和網址：

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

回應現在的格式如下：

{
  "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"
      }
    },
...
}

尋找多種類型的地點

以下範例顯示附近搜尋 (新版) 要求，要求系統傳回指定 circle 方圓 1000 公尺內所有便利商店和酒類商店的顯示名稱：

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
本例會將 places.primaryType 和 places.types 新增至欄位遮罩，讓回應包含每個地點的類型資訊，方便您從結果中選取適當的地點。

以下範例顯示 Nearby Search (新版) 要求，針對所有 "school" 類型地點 (排除所有 "primary_school" 類型地點) 要求，並依距離排序結果：

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

搜尋某區域附近的所有地點，並依距離排序

以下範例顯示附近搜尋 (新版) 要求，針對舊金山市區某個點附近的地點進行搜尋。在這個範例中，您可以加入 rankPreference 參數，依距離排序結果：

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

試試看！

您可以使用 API Explorer 提出範例要求，熟悉 API 和 API 選項。

  1. 選取頁面右側的 API 圖示 展開 API Explorer。。
  2. 您可以選擇展開「Show standard parameters」，然後將 fields 參數設為欄位遮罩。
  3. 您可以選擇編輯要求主體。
  4. 選取「執行」按鈕。在彈出式視窗中，選擇要用來提出要求的帳戶。

  5. 在 API Explorer 面板中，選取展開圖示 展開 API Explorer。，展開 API Explorer 視窗。