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

搜尋附近地點 (新)

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

搜尋附近 (新版) 要求會採用一或多個地點類型，然後傳回指定區域。指定一或多個資料類型的欄位遮罩必填。Nearby Search (新版) 僅支援 POST 要求。

API Explorer 可讓您發出即時要求，以便熟悉 API 以及 API 選項：

嘗試互動式示範，查看地圖上的「附近地點搜尋」(新版) 結果。

Nearby Search (新版) 要求

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: *
```
萬用字元「*」會選取所有欄位。儘管如此萬用字元可以在開發過程中使用，但 Google 不建議使用實際工作環境中的萬用字元 (*) 回應欄位遮罩能夠傳回的資料

使用 places.iconMaskBaseUri 和 places.iconBackgroundColor位於地點圖示區段。

指定下列一或多個欄位：
- 下列欄位會觸發 Nearby Search (基本) SKU：
  
  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, places.types, places.utcOffsetMinutes, places.viewport
  
  ^*「places.name」欄位包含地點的資源名稱 格式：places/PLACE_ID。使用「places.displayName」存取地點的文字名稱。
- 下列欄位會觸發 Nearby Search (進階) SKU：
  
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, 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.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
  }
}
```

選用參數

includeTypes/excludedTypes、includePrimaryTypes/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"，回應可以包含比主要類型更明確的地點以及指定的 IP 位址舉例來說，您指定納入了主要類型 "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

要排除的主要地點類型清單 (以半形逗號分隔) 特定內容

如果主要類型有相衝突的主要類型， 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"
      }
    },
...
}

尋找多種類型的地點

以下範例顯示針對所有便利商店和酒類商店的顯示名稱，半徑 1000 公尺以內指定的circle：

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

搜尋某地區附近的所有地點 (依距離排名)

以下範例顯示地點搜尋 (新版) 的 Nearby Search (新版) 要求靠近舊金山的某個點。在這個範例中，您要在當中加入 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 選項

選取 API 圖示。網頁右側。
視需要展開「顯示標準參數」並進行設定 fields 參數 欄位遮罩。
視需要編輯「要求主體」。
選取「執行」按鈕。在彈出式視窗中，選擇要用來提出請求的帳戶。
在 API Explorer 面板中，選取展開圖示，展開「API Explorer」視窗。

搜尋附近地點 (新)

Nearby Search (新版) 要求

Nearby Search (新版) 的回應

必要參數

FieldMask

locationRestriction

選用參數

includeTypes/excludedTypes、includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode