本頁面由 Cloud Translation API 翻譯而成。

Nearby Search (新版)

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

歐洲經濟區 (EEA) 開發人員

簡介

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

您可以使用 APIs Explorer 傳送即時要求，熟悉 API 和 API 選項：

試試看！

請試用互動式示範，在地圖上查看 Nearby Search (New) 結果。

Nearby Search (新版) 要求

Nearby Search (New) 要求是向以下形式的網址發出的 HTTP POST 要求：

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

在 POST 要求中，將所有參數傳遞至 JSON 要求內文或標頭。例如：

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 (新版) 回應

「附近搜尋 (新版)」會以 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: *
```
萬用字元「*」會選取所有欄位。不過，雖然在開發期間使用該萬用字元沒問題，但 Google 不建議在正式環境中使用萬用字元 (*) 回應欄位遮罩，因為這樣可能會傳回大量資料。
如要進一步瞭解如何使用 places.iconMaskBaseUri 和 places.iconBackgroundColor，請參閱「地點圖示」一節。

指定下列一或多個欄位：
- 下列欄位會觸發 Nearby Search Pro SKU：
  
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  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.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.subDestinations
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* 地址描述符號通常適用於印度境內的消費者，其他地區則為實驗功能。
  
  ^** places.name 欄位包含地點資源名稱，格式為：places/PLACE_ID。使用 places.displayName 存取地點的文字名稱。
- 下列欄位會觸發 Nearby Search Enterprise 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 Enterprise + Atmosphere SKU：
  
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  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

可讓您指定類型清單 (來自類型表 A)，用於篩選搜尋結果。每個類型限制類別最多可指定 50 個類型。

注意： 只有在回應中，才會傳回表格 B 的值。您無法使用表 B 中的值做為篩選條件。

地點只能有一個主要類型，且該類型必須與表 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、excludedTypes、includedPrimaryTypes 和 excludedPrimaryTypes，搜尋結果會傳回位置限制範圍內所有類型的地點。

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 之間 (含 1 和 20)，預設為 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 (New) 要求，用於取得 circle 所定義 500 公尺半徑內所有餐廳的顯示名稱：

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

尋找多種地點

以下範例顯示 Nearby Search (New) 要求，用於取得指定 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 (New) 要求，用於尋找所有 "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

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

以下範例顯示對舊金山市中心某個點附近的地點提出的 Nearby Search (New) 要求。在本範例中，您會加入 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

取得地址描述元

地址描述符提供地點位置的關係資訊，包括附近地標和所屬區域。

注意：地址描述符號已在印度全面開放使用，其他地區則處於實驗階段。如果 Places API 要求在欄位遮罩中只使用 addressDescriptor，系統會以 SKU：Places API Nearby Search Pro 計費。

以下範例顯示聖荷西購物中心附近地點的 Nearby Search (新版) 要求。在本範例中，您會在欄位遮罩中加入 addressDescriptors：

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby

回應會包含要求中指定的地點、附近地標清單和與地點的距離，以及區域清單和與地點的包含關係：

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "displayName": {
                "text": "Nordstrom",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "department_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "straightLineDistanceMeters": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "areas": [
            {
              "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "displayName": {
                "text": "Westfield Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "displayName": {
                "text": "Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "displayName": {
                "text": "Central San Jose",
                "languageCode": "en"
              },
              "containment": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

試試看！

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

選取頁面右側的 API 圖示 api。
視需要編輯要求參數。
選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen 展開 APIs Explorer 視窗。

Nearby Search (新版) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

簡介

Nearby Search (新版) 要求

Nearby Search (新版) 回應

必要參數

FieldMask

locationRestriction

選用參數

includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode

Nearby Search (新版) 範例

尋找特定類型的地點

尋找多種地點

從搜尋中排除特定類型的地點

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

取得地址描述元

試試看！

Nearby Search (新版)