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

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

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

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

您可以透過 APIs 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 (新版) 回應

附近搜尋 (新版) 會傳回 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.googleMapsLinks 欄位處於 GA 正式發布前預覽階段，因此不會收費，也就是說，在預覽期間使用這項功能不會產生任何帳單費用。
  
  ^*** 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.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 個類型。

注意： 表格 B 中的值只會在回應中傳回。您無法使用 Table 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" 的 Places。回應會包含與 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

取得地址描述元

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

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

以下範例顯示附近搜尋 (新) 要求，針對聖荷西的購物中心附近的場所。在這個範例中，您會在欄位遮罩中加入 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。
視需要編輯要求參數。
選取「執行」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在「API Explorer」面板中，選取全螢幕圖示 fullscreen 即可展開「API Explorer」視窗。

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

Nearby Search (新版) 要求

Nearby Search (新版) 回應

必要參數

FieldMask

locationRestriction

選用參數

includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode