搜尋附近 (新版) 要求會採用一或多個地點類型,然後傳回 指定區域。指定一或多個資料類型的欄位遮罩 必填。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 物件。在回覆中:
完整的 JSON 物件的格式為:
{ "places": [ { object (Place) } ] }
必要參數
-
FieldMask
建立 回應欄位遮罩。 使用網址參數將回應欄位遮罩傳遞至方法
$fields
或fields
,或是使用 HTTP 標頭X-Goog-FieldMask
。回應中沒有傳回欄位的預設清單。 如果省略欄位遮罩,這個方法會傳回錯誤。欄位遮蓋是不錯的設計做法,可確保您不要要求。 不必要的資料,有助於避免不必要的處理時間,並 帳單費用。
指定要傳回的地點資料類型清單 (以半形逗號分隔)。例如: 來擷取地點的顯示名稱和地址。
X-Goog-FieldMask: places.displayName,places.formattedAddress
使用
*
擷取所有欄位。X-Goog-FieldMask: *
指定下列一或多個欄位:
下列欄位會觸發 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 種類型。
一個地點只能有單一主要類型類型 與表 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
以半形逗號分隔的地點類型清單 (從表 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」視窗。