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: *
指定下列一或多個欄位:
下列欄位會觸發 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
、 { {2/2}places.name
places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.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.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
可篩選與地點相關聯的類型清單結果。如果搜尋具有多種類型限制,系統只會傳回符合所有限制的地點。舉例來說,如果您指定
{"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 (預設) 之間 (含 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」視窗。