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

搜尋附近地點 (新)

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

Nearby Search (新版) 要求會採用一或多個地點類型，並傳回指定區域內的相符地點清單。必須提供指定一或多個資料類型的欄位遮罩。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.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/1} { { 2/2}、places.nameplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport
  
  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.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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 可篩選與地點相關聯的類型清單結果。

如果搜尋具有多種類型限制，系統只會傳回符合所有限制的地點。舉例來說，如果您指定 {"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 (預設) 之間 (含 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"
      }
    },
...
}

尋找多種類型的地點

以下範例顯示 Nearby Search (新版) 要求，以指定 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 新增至欄位遮罩，這樣一來，回應中就會包含每個地點的類型資訊，方便您從結果中選取適當地點。

從搜尋中排除地點類型

以下範例顯示 "school" 類型所有地點的 Nearby Search (新版) 要求，但不含 "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 圖示。
視需要展開「Show Standard parameters」，然後將 fields 參數設為欄位遮罩。
視需要編輯「要求主體」。
選取「執行」按鈕。在彈出式視窗中，選擇要用來提出請求的帳戶。
在「API Explorer」面板中選取展開圖示，展開「API Explorer」視窗。

搜尋附近地點 (新)

Nearby Search (新版) 要求

Nearby Search (新版) 的回應

必要參數

FieldMask

locationRestriction

自選參數

includeTypes/excludedTypes、includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode