Nearby Search (New) 要求會接受一或多個地點類型,並傳回指定區域內相符地點的清單。必須提供指定一或多個資料類型的欄位遮罩。Nearby Search (新推出) 僅支援 POST 要求。
您可以透過 API Explorer 發出即時要求,熟悉 API 和 API 選項:
試試看!嘗試使用互動式示範,在地圖上查看「搜尋附近」(新) 結果。
Nearby Search (新) 要求
「搜尋附近」(New) 要求是對網址採用 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 (New) 會傳回 以 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.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.primaryTypeDisplayName
。places.name
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
使用places.displayName
存取地點的文字名稱。下列欄位會觸發 Nearby Search (Advanced) 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.servesDesserts
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 } }
自選參數
-
includeType/excludedTypes、includePrimaryTypes/excludedPrimaryType
可讓您從表 A 類型中指定類型清單,用來篩選搜尋結果。每個類型限制類別中最多可指定 50 種類型。
地點只能擁有相關聯表 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
從表 A 搜尋的地點類型清單 (以半形逗號分隔)。如果省略這個參數,系統會傳回所有類型的地點。
excludedTypes
從表 A 中排除的地點類型清單 (以半形逗號分隔)。
如果您在要求中同時指定
includedTypes
( 例如"school"
) 和excludedTypes
(例如"primary_school"
),則回應會包含分類為"school"
,但不歸為"primary_school"
的地點。回應會包含至少與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 (新) 範例
尋找同類型的地點
以下範例顯示針對 500 公尺半徑範圍內所有餐廳的 Nearby Search (New) 要求 (由 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 公尺範圍內的所有便利商店和酒類商店顯示名稱的 Nearby Search (New) 要求:
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 (New) 要求。在此範例中,您可以加入 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 視窗。