本文是舊文章的更新版本，舊文章使用舊版 GMP API。這項內容已更新，採用 2023 年至 2024 年推出的新版 Places API，以及 2023 年推出的 Routes API。
一般來說，使用者開車前往搜尋點時，實際上需要導航到附近的停車場或出入口等位置。假設有位司機需要前往機場或購物中心。前往機場時，司機嘗試抵達的是航廈或下車地點，而非機場園區中心。同樣地，購物中心旁的停車場可能更適合開車的使用者。在這種情況下，開發應用程式或服務來引導駕駛人時，請先找出駕駛人要去的地點，然後提供該地點附近的選填目的地。這種做法可讓您運用 Google 地圖平台提供的位置資料，以少量但智慧的開發工作，為顧客提供更優質的服務，並展現您對顧客時間的重視。
我們會說明如何依序或合併使用新版 Places API 和 Routes API，找出目的地附近的合適停車地點。這項解決方案旨在消除不確定性，並減少在接近最終目的地時尋找停車位所需的多次互動。請參閱兩個範例，瞭解如何詳細實作這些案例。
示例 1：沒有停車場的觀光景點
請選擇與路邊沒有直接連線的地點，這樣就必須另外擷取路線，目的地是巴黎的聖母院，起點則是巴黎東站 (48.87697775149635, 2.3592247806755564)。
司機從巴黎聖母院以北約 16 分鐘車程的車站出發，聖母院是島上著名的觀光景點，可透過橋樑抵達，但附近有幾條單行道，且沒有大型停車場，因此應該會是很有趣的挑戰。
1. Places API 要求
這個 Places API 要求範例使用文字搜尋功能尋找巴黎聖母院。詳情請參閱開發人員說明文件。這些範例中的「$APIKEY」是您在 Google Cloud 控制台中啟用 Google 地圖平台 Places 和 Routes API 時取得的 API 金鑰。如需更詳細的說明，請參閱「開始使用 Google 地圖平台」一文。
新版 Places API 要求採用新格式。回應欄位不再是固定的，開發人員必須在標頭中定義欄位遮罩。欄位遮罩的使用方式請參閱說明文件。
curl -X POST --data @notre_dame.json \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress,places.location' \
'https://places.googleapis.com/v1/places:searchText'
使用「notre_date.json」內容做為搜尋參數：
{
"textQuery": "Notre Dame, Paris",
"languageCode": "en"
}
上述要求的相關回應會提供下列經緯度座標：
{
"places": [
{
"id": "ChIJATr1n-Fx5kcRjQb6q6cdQDY",
"formattedAddress": "6 Parvis Notre-Dame - Pl. Jean-Paul II, 75004 Paris, France",
"location": {
"latitude": 48.852968200000007,
"longitude": 2.3499021
},
"displayName": {
"text": "Cathédrale Notre-Dame de Paris",
"languageCode": "en"
}
}
]
}
如您所見，座標確實指向巴黎聖母院。
|
|
身為開發人員或服務供應商，建議自動提示駕駛人「尋找巴黎聖母院附近的停車位嗎？」或在駕駛人使用電動車時，搜尋充電站。使用者體驗會因裝置和螢幕而異，但如果對話方塊文字會在短時間後消失，或許值得考慮。如要在巴黎聖母院附近尋找停車位，請使用 Places API 執行附近搜尋，並將類型設為「parking」和「electric_vehicle_charging_station」，半徑設為 500 公尺。以下範例會將結果調整為巴黎聖母院 500 公尺內的停車區。
curl -X POST -d '{
"includedTypes": ["parking", "electric_vehicle_charging_station"],
"maxResultCount": 10,
"rankPreference": "DISTANCE",
"locationRestriction": {
"circle": {
"center": {
"latitude": 48.852968200000007,
"longitude": 2.3499021},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H "X-Goog-FieldMask: places.displayName,places.location" \
https://places.googleapis.com/v1/places:searchNearby
第一個結果是位於 48.854981、2.350629 的充電站，但您執行這個範例時，結果可能會有所不同。在下一節中，我們會提出 Routes API 要求，屆時請使用這個位置。
2. Routes API 要求
如要尋找從車站到巴黎聖母院附近充電站的路徑，您需要提出 Routes API 要求。只要設定來源和目的地 參數即可。如要瞭解其他做法，請參閱開發人員說明文件。
curl -X POST -d '{
"origin":{
"location":{
"latLng":{
"latitude": 48.87697775149635,
"longitude": 2.3592247806755564
}
}
},
"destination":{
"location":{
"latLng":{
"latitude": 48.854981,
"longitude": 2.350629
}
}
},
"travelMode": "DRIVE",
"routingPreference": "TRAFFIC_AWARE",
"departureTime": "2024-05-16T15:01:23.045123456Z",
"computeAlternativeRoutes": false,
"routeModifiers": {
"avoidTolls": false,
"avoidHighways": false,
"avoidFerries": false
},
"languageCode": "en-US",
"units": "METRIC"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs,routes.polyline.encodedPolyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'
Routes API 回應通常會包含多個路線建議。如要在回應中加入路線資料，請在 fieldmask 中定義「routes.legs」。每條路線都包含多個「路段」，而每個路段又包含多個「步驟」，顯示旅行距離和座標。如要找出可開車抵達的最終座標，請使用所選路線中最後一段路程的最後一個步驟的「endLocation」欄位。"latitude": 48.854937299999996, "longitude": 2.3505841999999997
這個地點可能不是首選，但查看地圖或 Google 街景服務後，你會發現這個地點距離巴黎聖母院很近，步行約 6 到 7 分鐘即可抵達。
從充電站停車位到巴黎聖母院的步行路線
範例 1 的摘要
如您所見，為車輛尋找停車區只需要幾次 API 呼叫，並向駕駛人顯示建議。這樣一來，使用者就不必在單行道上繞路，或是在擁擠的觀光景點尋找停車位，可節省許多時間。總結來說，我們發出了下列 API 要求：
- Places API 文字搜尋要求，用於尋找巴黎聖母院的座標
- 使用 Places API 附近搜尋功能，在這些座標的 500 公尺內尋找設有電動車充電站的停車區
- 傳送 Routes API 要求，尋找前往充電站的路線
示例 2 - 在大型機場引導前往航廈
再舉一個例子，假設駕駛人要前往的區域很大，有多個地點、興趣點或潛在下車地點。司機從英國溫布利球場 (51.557263604707224, -0.2794575145680608) 出發，目的地是倫敦希斯洛機場第 5 航廈。
新版 Places API 自動完成功能的一大優點，就是能夠定義主要類型做為搜尋條件，並結合 API 預測的子場所做為潛在搜尋結果。也就是說，搜尋機場和停車位時，也會顯示航廈或停車場。如需納入或排除的完整類型清單，請參閱文件。
curl -X POST -d '{
"input": "Heathrow",
"includedPrimaryTypes": ["airport", "parking"]
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
https://places.googleapis.com/v1/places:autocomplete
上述查詢會提供航廈清單，以及這些航廈的個別下車地點。在結果清單中，我們可以找到「London Heathrow Airport Terminal 5」及其地點 ID：
"place_id" : "ChIJo21hnPxxdkgRksRL0KQRWII",
使用「placeId」參數，我們可以告訴 Routes API，我們要抵達的是某個地點，而不是任意座標。
curl -X POST -d '{
"origin":{
"location":{
"latLng":{
"latitude": 51.557263604707224,
"longitude": -0.2794575145680608
}
}
},
"destination":{
"placeId": "ChIJo21hnPxxdkgRksRL0KQRWII"
},
"travelMode": "DRIVE",
"routingPreference": "TRAFFIC_AWARE",
"departureTime": "2024-05-16T15:01:23.045123456Z",
"computeAlternativeRoutes": false,
"languageCode": "en-US",
"units": "METRIC"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs,routes.polyline.encodedPolyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'
同樣地，如上一個範例所示，只要讀取 JSON 回應中的所有步驟，即可找到行程的最後一段，以及終點的經緯度座標 (51.4714348, "longitude": -0.48967890000000003)。
範例 2 摘要
如同上一個範例，為駕駛人提供更完善的指引，開發工作量非常小，但駕駛人節省的時間卻可觀。我們發出了下列要求：
- Places API 自動完成 (新版) 要求，用於尋找希斯洛機場第 5 航廈
- 從 Wembley 到第 5 航廈的路線，透過 Routes API 提出要求
這個範例僅觸及新版 Places API 功能的冰山一角。看看一些新地點類型，例如跑道和國際機場。
結論
如您所見，為開車出遊的顧客提供優質服務所需的開發工作相當少，而且您可以展現自己如何考量顧客需求。
在開發方面，您可以使用許多程式庫和工具，協助為客戶建構服務。請參閱 Google 地圖平台公開提供的 GitHub 存放區。
後續動作
開始使用 GMP：https://developers.google.com/maps/get-started
建議延伸閱讀
Places API 地點自動完成 (新版) 說明文件： https://developers.google.com/maps/documentation/places/web-service/place-autocomplete
Routes API 說明文件： https://developers.google.com/maps/documentation/routes
貢獻者
主要作者：Mikko Toivanen | Google 地圖平台解決方案工程師