地點類別 (預先發布版)

總覽

「地點」類別提供更簡化的 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');
    }
}
index.ts

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");
  }
}

index.js

透過電話號碼尋找地點

呼叫 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');
    }
}
index.ts

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;

index.js

取得 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);
}
index.ts

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);
}

index.js

地點資料欄位

欄位會與 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