Nearby Search (新版) 要求會採用一或多個地點類型,傳回指定區域內相符地點的清單。您必須指定一或多個資料類型的欄位遮罩。Nearby Search (新版) 僅支援 POST 要求。
您可以透過 API 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: *
指定下列一或多個欄位:
以下欄位會觸發 Nearby Search (Basic) SKU:
places.accessibilityOptions
、places.addressComponents
、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.primaryType
、places.primaryTypeDisplayName
、places.pureServiceAreaBusiness
、places.shortFormattedAddress
、places.subDestinations
、places.types
、places.utcOffsetMinutes
、places.viewport
*places.googleMapsLinks
欄位處於 GA 前測試階段,因此在測試期間使用時不會產生任何費用,也就是帳單金額為 $0 美元。
**places.name
欄位包含以下地點資源名稱:places/PLACE_ID
。使用places.displayName
即可存取地點的文字名稱。下列欄位會觸發 Nearby Search (Advanced) 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 (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.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 種類型。
一個地點只能有相關聯表 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
以半形逗號分隔的清單,列出要搜尋的 表 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 (預設) 之間 (含 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
試試看!
您可以使用 API Explorer 提出範例要求,熟悉 API 和 API 選項。
- 選取頁面右側的 API 圖示 。
- 您可以選擇展開「Show standard parameters」,然後將
fields
參數設為欄位遮罩。 - 您可以選擇編輯要求主體。
- 選取「執行」按鈕。在彈出式視窗中,選擇要用來提出請求的帳戶。
在 API Explorer 面板中,選取展開圖示 ,展開 API Explorer 視窗。