總覽
「地點」類別提供更簡化的 API,方便您使用 Maps JavaScript API 的 Places Library,並支援 Promise 等新型使用模式。
開始使用
取得 API 金鑰並啟用必要的 API
您需要擁有已連結帳單帳戶的 Cloud 專案,才能使用「地點」類別預先發布版。此外,您也必須啟用 Maps JavaScript API 和 Places API。方法是按照操作說明啟用一或多個 API 或 SDK。請注意,您必須在 Cloud 控制台的同一個專案中啟用這兩個 API。
取得 API 金鑰載入 Places Library
如要使用 Places Library 中的功能,您必須先在 Maps JavaScript API 指令碼載入網址中使用 libraries
參數載入 Places Library。此外,您還必須為這個預先發布版指定 v=beta
。
<script async src="https://maps.googleapis.com/maps/api/js?v=beta&key=YOUR_API_KEY&libraries=places&callback=initMap"> </script>
透過文字查詢尋找地點
呼叫 findPlaceFromQuery
即可透過文字查詢尋找地點。您可以使用 fields
參數指定一份以半形逗號分隔的清單,其中包含一或多個採用駝峰式大小寫的地點資料欄位。使用 fields: ['*']
便可傳回特定地點的所有資料 (僅供測試,不建議在實際執行環境中使用)。
以下範例顯示如何使用 async/await 模式呼叫 findPlaceFromQuery
,並在地圖上顯示結果。
TypeScript
let map: google.maps.Map; let centerCoordinates = { lat: 37.4161493, lng: -122.0812166 }; function initMap() { map = new google.maps.Map(document.getElementById('map') as HTMLElement, { center: centerCoordinates, zoom: 14, // ... }); findPlace(); } async function findPlace() { const request = { query: 'Sports Page', fields: ['displayName', 'location'], locationBias: centerCoordinates, }; const { places } = await google.maps.places.Place.findPlaceFromQuery(request); if (places.length) { const place = places[0]; const location = place.location as google.maps.LatLng; const markerView = new google.maps.marker.AdvancedMarkerView({ map, position: place.location, title: place.displayName, }); map.setCenter(location); } else { console.log('No results'); } }
JavaScript
let map; let centerCoordinates = { lat: 37.4161493, lng: -122.0812166 }; function initMap() { map = new google.maps.Map(document.getElementById("map"), { center: centerCoordinates, zoom: 14, // ... }); findPlace(); } async function findPlace() { const request = { query: "Sports Page", fields: ["displayName", "location"], locationBias: centerCoordinates, }; const { places } = await google.maps.places.Place.findPlaceFromQuery(request); if (places.length) { const place = places[0]; const location = place.location; const markerView = new google.maps.marker.AdvancedMarkerView({ map, position: place.location, title: place.displayName, }); map.setCenter(location); } else { console.log("No results"); } }
透過電話號碼尋找地點
呼叫 findPlaceFromPhoneNumber
即可透過電話號碼尋找地點。電話號碼必須採用國際電話號碼格式 (開頭加上加號 (「+」),後面接著國家/地區代碼,然後是電話號碼本身)。詳情請參閱 E.164 ITU 建議書。您可以使用 fields
參數指定一份以半形逗號分隔的清單,其中包含一或多個採用駝峰式大小寫的地點資料欄位。使用 fields: ['*']
便可傳回特定地點的所有資料 (僅供測試,不建議在實際執行環境中使用)。
以下範例顯示如何使用 async/await 模式呼叫 findPlaceFromPhoneNumber
,並在地圖上顯示結果。
TypeScript
async function findPlaceByPhone() { const request = { phoneNumber: '+1(206)787-5388', fields: ['displayName', 'location'], } const { places } = await google.maps.places.Place.findPlaceFromPhoneNumber(request); if (places.length) { const place = places[0]; const markerView = new google.maps.marker.AdvancedMarkerView({ map, position: place.location, title: place.displayName, }); console.log(place.displayName); } else { console.log('No results'); } }
JavaScript
async function findPlaceByPhone() { const request = { phoneNumber: "+1(206)787-5388", fields: ["displayName", "location"], }; const { places } = await google.maps.places.Place.findPlaceFromPhoneNumber( request ); if (places.length) { const place = places[0]; const markerView = new google.maps.marker.AdvancedMarkerView({ map, position: place.location, title: place.displayName, }); console.log(place.displayName); } else { console.log("No results"); } } window.initMap = initMap;
取得 Place Details
如果您已經有 Place
物件或地點 ID,可以呼叫 Place.fetchFields
取得該地點的詳細資料。您可以使用 fields
參數指定一份以半形逗號分隔的清單,其中包含一或多個採用駝峰式大小寫的地點資料欄位。使用 fields: ['*']
便可傳回所有資料欄位 (僅供測試,不建議在實際執行環境中使用)。
TypeScript
async function getPlaceDetails() { // Use place ID to create a new Place instance. const place = new google.maps.places.Place({ id: 'ChIJN1t_tDeuEmsRUsoyG83frY4', requestedLanguage: 'en', // optional }); // Call fetchFields, passing the desired data fields. await place.fetchFields({ fields: ['displayName', 'formattedAddress'] }); // Show the result console.log(place.displayName); console.log(place.formattedAddress); }
JavaScript
async function getPlaceDetails() { // Use place ID to create a new Place instance. const place = new google.maps.places.Place({ id: "ChIJN1t_tDeuEmsRUsoyG83frY4", requestedLanguage: "en", // optional }); // Call fetchFields, passing the desired data fields. await place.fetchFields({ fields: ["displayName", "formattedAddress"] }); // Show the result console.log(place.displayName); console.log(place.formattedAddress); }
地點資料欄位
欄位會與 Place Details 結果相對應,並分為三種計費類別:「Basic」、「Contact」和「Atmosphere」。「Basic」欄位以基本費率計費,不會產生額外費用。「Contact」和「Atmosphere」欄位會以較高的費率計費。詳情請參閱價目表。無論是否要求作者資訊欄位,每次呼叫一律都會傳回作者資訊 (html_attributions
)。
「地點」類別支援下列欄位:
Basic Data
欄位 | 地點類別 (僅限 v=beta 版) |
---|---|
地址元件 | addressComponents |
商家狀態 | businessStatus |
格式化地址 | adrFormatAddress |
位置 | location |
圖示 | icon |
圖示遮罩基準 URI | svgIconMaskUri |
圖示背景顏色 | iconBackgroundColor |
名稱 | displayName |
相片 | photos |
地點 ID | id |
Plus Code | plusCode |
類型 | types |
網址 | websiteURI |
世界標準時間時差 | utcOffsetMinutes |
可視區域 | viewport |
無障礙入口 | hasWheelchairAccessibleEntrance |
Contact Data 欄位
欄位 | 地點類別 (僅限 v=beta 版) |
---|---|
電話號碼 | nationalPhoneNumber |
國際電話號碼 | internationalPhoneNumber |
營業時間 | openingHours |
網站 | websiteURI |
Atmosphere Data 欄位
欄位 | 地點類別 (僅限 v=beta 版) |
---|---|
店外取貨 | hasCurbsidePickup |
外送 | hasDelivery |
內用 | hasDineIn |
價格等級 | priceLevel |
評分 | rating |
可預訂 | isReservable |
評論 | reviews |
供應啤酒 | servesBeer |
供應早餐 | servesBreakfast |
供應早午餐 | servesBrunch |
供應晚餐 | servesDinner |
供應午餐 | servesLunch |
供應素食料理 | servesVegetarianFood |
供應葡萄酒 | servesWine |
外帶 | hasTakeout |
使用者評分總計 | userRatingsCount |