地點資料庫

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

Places Library 和 Maps JavaScript API 中的函式可讓應用程式搜尋指定區域 (例如地圖邊界或定點) 內包含的地點 (在這個 API 中定義為建築物、地理位置或顯眼的搜尋點)。

Places API 提供自動完成功能,方便您為應用程式提供 Google 地圖搜尋欄位的預先輸入搜尋功能。自動完成功能便會開始輸入地址。詳情請參閱自動完成說明文件

開始

如果您不熟悉 Maps JavaScript API 或 JavaScript,建議您先閱讀 JavaScript 並取得 API 金鑰,再開始操作。

啟用 API

使用 Maps JavaScript API 中的 Places Library 前,請先確認 Google Cloud Console 已啟用的 Places API,請務必為您為 Maps JavaScript API 設定的專案啟用。

查看已啟用的 API 清單:

  1. 前往 Google Cloud Console
  2. 按一下「選取專案」按鈕,然後選取您為 Maps JavaScript API 設定的專案,然後按一下「開啟」
  3. 資訊主頁的 API 清單中,尋找 Places API
  4. 如果清單顯示 Places API,表示該 API 已啟用。如果 API 列於清單中,請啟用該 API:
    1. 選取頁面頂端的「啟用 API 和服務」,即可顯示「媒體庫」分頁標籤。或者,從左側選單中選取 [程式庫]
    2. 搜尋「Places API」,然後從結果清單中選取 API。
    3. 選取「啟用」。程序完成後,資訊主頁的 API 清單會顯示「Places API」

正在載入程式庫

「地點」服務是獨立的程式庫,與主要的 Maps JavaScript API 程式碼不同。如要使用這個程式庫提供的功能,您必須先使用 Maps API 啟動網址的 libraries 參數載入:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

詳情請參閱程式庫總覽

將 Places API 新增至 API 金鑰和 API 限制清單

將 API 限制套用至金鑰可將 API 金鑰的使用限制在一或多個 API 或 SDK。系統會處理與 API 金鑰相關聯的 API 或 SDK 要求。對未與 API 金鑰建立關聯的 API 或 SDK 發出的要求將會失敗。如何限制 API 金鑰搭配 Places Library 和 Maps JavaScript API 使用:
  1. 前往 Google Cloud Console
  2. 按一下專案下拉式選單,然後選取您要保護的 API 金鑰所屬的專案。
  3. 按一下選單按鈕 ,然後選取 [Google 地圖平台> 憑證]
  4. 在「憑證」頁面上,按一下您要保護的 API 金鑰名稱。
  5. 在「限制並重新命名 API 金鑰」頁面上設定限制:
    • API 限制
      • 選取 [限制金鑰]
      • 按一下「選取 API」,然後選取「Maps JavaScript API」和「Places API」
        如果清單中未列出任一 API,請啟用該 API。
  6. 按一下 [儲存]。

使用限制和政策

配額

Places Library、JavaScript API 與 Places API 共用用量配額,如 Places API 的「使用限制」說明文件所述。無論有多少專案共用相同的專案,系統都會套用每個使用者工作階段的每秒查詢頻率上限。*

注意:首次載入 API 時,您必須分配初始要求的配額。這個配額用盡後,API 會每秒對額外的要求強制執行頻率限制。如果在特定時間範圍內發出太多要求,API 會傳回 OVER_QUERY_LIMIT 回應代碼。按工作階段頻率限制可避免將用戶端服務用於批次要求。如為批次要求,請使用我們的網路服務 API。

政策

使用 Places Library、Maps JavaScript API 時,必須遵守 Places API 所製定的政策

地方資訊搜尋

你可以透過 Places 服務進行以下類型的搜尋:

傳回的資訊包括建築物 (例如餐廳、商店、辦公室) 和 'Geocoding' 結果,這些結果指出地址、城鎮和城市等政治區域和其他搜尋點。

尋找地點要求

「尋找地點」要求可讓您透過文字查詢或電話號碼搜尋地點。尋找地點要求分為兩種類型:

從查詢尋找地點

「查詢中的 Find Place」功能會接收文字輸入並傳回地點。輸入內容可以是任何類型的地點資料,例如商家名稱或地址。如要透過查詢要求發出「尋找地點」,請呼叫 PlaceService's findPlaceFromQuery() 方法,該方法會用到下列幾項參數:

  • query (必填) 用於搜尋的文字字串,例如:「&resttrant"」或「123 Main Street」。必須是地點的名稱、地址或類別。任何其他類型的輸入都可以產生錯誤,並不保證會傳回有效的結果。Places API 會根據這個字串傳回候選相符項目,並依據其感知的關聯性排序結果。
  • fields (必要) 一或多個欄位,用於指定要傳回的「地點」資料類型。
  • locationBias (選用) 定義要搜尋區域的座標。可能的值如下:

您也必須傳遞回呼方法至 findPlaceFromQuery(),以處理結果物件和 google.maps.places.PlacesServiceStatus 回應。

以下範例顯示呼叫 findPlaceFromQuery()、搜尋「Museum of Contemporary Art Australia」(澳洲當代藝術博物館) 以及 namegeometry 欄位的內容。

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
查看範例

從電話號碼尋找地點

「從電話號碼尋找地點」會尋找電話號碼並傳回地點。如要從電話號碼發出 Find Place 要求,請呼叫 PlaceService' 的 findPlaceFromPhoneNumber() 方法,該方法會用到下列幾項參數:

  • phoneNumber (必填) 電話號碼,採 E.164 格式。
  • fields (必要) 一或多個欄位,用於指定要傳回的「地點」資料類型。
  • locationBias (選用) 用來定義搜尋區域的座標。可能的值如下:

您也必須傳遞回呼方法至 findPlaceFromPhoneNumber(),以處理結果物件和 google.maps.places.PlacesServiceStatus 回應。

欄位 (Find Place 方法)

使用 fields 參數指定要傳回的地點資料類型陣列。 例如:fields: ['formatted_address', 'opening_hours', 'geometry']。指定複合值時,請使用半形句號。例如:opening_hours.weekday_text

欄位會對應至 Place Search,並分為三種計費類別:「Basic」、「Contact」和「Atmosphere」。基本欄位的費用將以基本費率計費,不會產生額外費用。聯絡和氣氛資料欄位會以較高的費率計費;詳情請參閱價目表。無論欄位是否被要求,系統每次呼叫都會傳回歸因 (html_attributions)。

基本版

「基本」類別包含下列欄位:
business_statusformatted_addressgeometryiconicon_mask_base_uriicon_background_colornamepermanently_closed (已淘汰)、 photosplace_idplus_codetypes

聯絡人

「聯絡人」類別包含以下欄位: opening_hours
(已淘汰,Maps JavaScript API 的地點資料庫)。使用 Place Details 要求取得 opening_hours 結果)。

氣氛

「氣氛」類別包含下列欄位:price_levelratinguser_ratings_total

findPlaceFromQuery()findPlaceFromPhoneNumber() 方法均提供同一組欄位,且可在各自的回應中傳回相同的欄位。

設定位置偏誤 (Find Place 方法)

使用 locationBias 參數即可針對特定區域搜尋 Find Place 結果。您可以按照以下方式設定 locationBias

偏誤看到特定區域的結果:

locationBias: {lat: 37.402105, lng: -122.081974}

定義要搜尋的矩形區域:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

您也可以使用LatLngBounds

定義要搜尋的半徑 (以公尺為單位),以特定區域為中心:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

地方資訊搜尋要求

「搜尋附近地點」功能可讓您按關鍵字或類型來搜尋指定區域內的地點。搜尋附近地點必須一律包含位置,並以下列其中一種方式指定位置:

  • LatLngBounds
  • location 屬性組合表示的圓形區域 (將圓形中心指定為 LatLng 物件),以及半徑,以公尺為單位。

系統會透過呼叫 PlacesServicenearbySearch() 方法啟動 Places Nearby 搜尋,藉此傳回 PlaceResult 物件的陣列。請注意,自 3.9 版起,nearbySearch() 方法會取代 search() 方法。

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

這個方法會處理下列欄位的要求:

  • 包括:
    • bounds,必須是定義矩形搜尋區域的 google.maps.LatLngBounds 物件;或
    • locationradius;前者採用 google.maps.LatLng 物件,後者會使用簡單的整數,以圓形表示的半徑 (單位為公尺)。允許的半徑上限為 50 000 公尺。請注意,當 rankBy 設為 Distance 時,您必須指定 location,但不能指定 radiusbounds
  • keyword (選用):用來與所有可用欄位進行比對的字詞,包括但不限於名稱、類型和地址,以及客戶評論和其他第三方內容。
  • minPriceLevelmaxPriceLevel (選用):將結果限制為指定範圍內的地點。有效值介於 0 (最低價格) 到 4 (最高價格) 之間,含首尾值。
  • name 已淘汰。等同於 keyword。這個欄位中的值會與 keyword 欄位中的值合併,並做為同一個搜尋字串的一部分傳送。
  • openNow (選用) — 布林值,表示 Places 服務只應傳回傳送查詢時營業中的商家。如果在查詢中加入此參數,則不會傳回在 Google 地方資訊資料庫中未指定營業時間的地點。將 openNow 設為 false 不會有任何作用。
  • rankBy (選用) — 列出結果的順序。可能的值包括:
    • google.maps.places.RankBy.PROMINENCE (預設)。這個選項會依據重要性的重要性排序。排名優於指定半徑範圍內名列鄰近地區,但鄰近的地點會較不顯眼。名氣可能會受到 Google 索引排名、全球熱門度等因素上的排名影響。指定 google.maps.places.RankBy.PROMINENCE 時,您必須使用 radius 參數。
    • google.maps.places.RankBy.DISTANCE。這個選項會按照指定 location 的距離,以遞增方式排序結果 (必要)。請注意,如果您指定 RankBy.DISTANCE,則無法指定自訂 bounds 和/或 radius。如果指定 RankBy.DISTANCE,則必須指定 keywordnametype 中的一或多個。
  • type — 將結果限制為符合指定類型的地點。只能指定一個類型 (如果提供多個類型,系統會忽略第一個項目之後的所有類型)。請參閱支援的類型清單

您也必須傳遞回呼方法至 nearbySearch(),以處理結果物件和 google.maps.places.PlacesServiceStatus 回應。

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    type: ['restaurant']
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

查看範例

文字搜尋要求

Google Places Text Search 服務是一項網路服務,可根據字串傳回一組地點的相關資訊,例如「臺北的披薩」或「渥太華附近的鞋店」。這項服務會回應包含與文字字串相符的地點,以及任何已設定的位置偏誤。搜尋回應會包含地點清單,您可以傳送 Place Details 要求,進一步瞭解回應中的任何地點。

如要啟動文字搜尋,您必須呼叫 PlacesService' 的 textSearch() 方法。

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

這個方法會處理下列欄位的要求:

  • query (必要) 用於搜尋的文字字串,例如 "restaurant&quot 或 "123 Main Street"。必須是地點的名稱、地址或類別。任何其他類型的輸入都可以產生錯誤,並不保證會傳回有效的結果。「地點」服務會根據這個字串傳回候選相符項目,並依據其感知的關聯性排序結果。如果搜尋要求中也使用 type 參數,這個參數會成為選用項目。
  • 選用:
    • openNow:這個布林值,表示地點服務應只在傳送查詢時營業中的商家。如果在查詢中加入此參數,則不會傳回在 Google 地方資訊資料庫中未指定營業時間的地點。將 openNow 設為 false 不會有任何作用。
    • minPriceLevelmaxPriceLevel — 將結果限制為指定價格範圍內的地點。有效值的範圍介於 0 (最實惠) 到 4 (最貴) 之間。
    • 包括:
      • boundsgoogle.maps.LatLngBounds 定義要搜尋的矩形;或
      • locationradius — 您可以藉由傳遞 locationradius 參數,將結果偏誤到指定圓形。這麼做會指示「地點」服務優先顯示該圓圈中的搜尋結果。系統仍可能顯示超出定義區域的結果。位置使用 google.maps.LatLng 物件,半徑則使用一個簡單的整數,代表圓形的範圍 (#39;)。允許的最大半徑為 50,000 公尺。
    • type — 將結果限制為符合指定類型的地點。只能指定一個類型 (如果提供了多種類型,系統會忽略第一個項目之後的所有類型)。請參閱支援的類型清單

您也必須傳遞回呼方法至 textSearch(),以處理結果物件和 google.maps.places.PlacesServiceStatus 回應。

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

搜尋回應

狀態碼

PlacesServiceStatus 回應物件包含要求的狀態,且可能包含偵錯資訊,以協助您追蹤地點要求失敗的原因。可能的狀態值如下:

  • INVALID_REQUEST:這個要求無效。
  • OK:回應包含有效的結果。
  • OVER_QUERY_LIMIT:網頁已超出要求配額。
  • REQUEST_DENIED:網頁不得使用 PlacesService。
  • UNKNOWN_ERROR:伺服器發生錯誤,無法處理 PlacesService 要求。如果重試,要求可能會成功。
  • ZERO_RESULTS:找不到這項要求的結果。

地方資訊搜尋結果

findPlace()nearbySearch()textSearch() 函式會傳回 PlaceResult 物件的陣列。

每個 PlaceResult 物件均可能包含下列屬性:

  • business_status 代表地點的營運狀態 (如果地點是商家)。可包含下列其中一個值:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    如果沒有資料,則不會傳回 business_status
  • formatted_address 是包含這個地點的人類可讀地址字串。系統只會針對文字搜尋傳回 formatted_address 屬性。

    這個地址通常相當於郵寄地址。請注意,受到授權限制,部分國家/地區 (例如英國) 不允許發布真實的郵寄地址。

    格式化的地址在邏輯上是由一或多個位址元件組成。舉例來說,地址為「111 8th Avenue, New York, NY」是由以下元件組成:「com111」(街道號碼)、「8th Avenue」(路線)、「New York」(紐約) 和「NY」(美國州) 等地址。)

    請勿以程式輔助方式剖析格式化的地址。請改用個別地址元件,API 回應除了格式化的地址欄位之外,也會包含此 API 回應。

  • geometry:地點的相關資訊。其中包括:
    • location 會提供地點的經緯度。
    • viewport 會在查看這個地點時,在地圖上定義偏好的可視區域。
  • permanently_closed (已淘汰) 是布林值標記,表示地點是永久關閉或暫時關閉 (值 true)。請勿使用 permanently_closed。請改用 business_status 取得商家營運狀態。
  • plus_code (請參閱開啟位置代碼加號代碼) 是編碼的位置參照,取自經緯度座標,代表區域:1/8000 度 x 1/8000 度 (赤道約 14m x 14m)。如果地點不存在或沒有命名街道,可以使用 Plus Code 取代街道地址。

    Plus Code 格式為全域代碼和複合程式碼:

    • global_code 是 4 個字元的區碼,加上 6 個字元以上的地區代碼 (849VCWC8+R9)。
    • compound_code 是 6 個字元以上的地區代碼,加上明確的位置 (例如 CWC8+R9、Mountain View, CA, USA)。請勿以程式輔助方式剖析這項內容。
    系統通常會傳回全域代碼和複合程式碼。不過,如果結果是位於遠端位置 (例如海洋或沙漠),則只能傳回全域代碼。
  • html_attributions:顯示搜尋結果時要顯示的歸因陣列。陣列中的每個項目都含有單一歸因的 HTML 文字。注意:這是整個搜尋回應的所有歸因資訊。因此,回應中的所有 PlaceResult 物件都使用相同的歸因清單。
  • icon 會傳回彩色 71px x 71px PNG 圖示的網址。
  • icon_mask_base_uri 會傳回非彩色圖示的基準網址,減去 .svg 或 .png 副檔名。
  • icon_background_color 會傳回地點類別的預設 HEX 顏色代碼。
  • name:地點名稱。
  • opening_hours 可能包含下列資訊:
    • open_now 是一個布林值,表示地點目前是否營業 (在 Places Library、Maps JavaScript API 中已淘汰,請改用 utc_offset_minutes)。
  • place_id 是用來識別地點的文字 ID。如要擷取地點相關資訊,請在地點詳細資料要求中傳遞這個 ID。進一步瞭解如何使用地點 ID 參照地點
  • rating 包含地點評分 (0.0 分至 5.0 分),以匯總的使用者評論為依據。
  • types 此地點的陣列類型 (例如["political", "locality"]["restaurant", "lodging"])。這個陣列可以包含多個值,也可以留空。不需事先通知,即可導入新的值。請參閱支援的類型清單。
  • vicinity:該地點的簡化地址,包括街道名稱、門牌號碼和縣市名稱,但不包括省/州、郵遞區號或國家/地區。舉例來說,Google # 澳洲辦公室的 vicinity 值為 5/48 Pirrama Road, Pyrmont

取得其他結果

根據預設,每個地點搜尋每次查詢最多傳回 20 筆結果。不過,每次搜尋最多可以傳回 60 筆結果,分為三頁。可透過 PlaceSearchPagination 物件存取其他頁面。如要存取其他頁面,您必須透過回呼函式擷取 PlaceSearchPagination 物件。PlaceSearchPagination 物件的定義為:

  • hasNextPage 布林值屬性,表示是否有進一步的結果。true
  • nextPage() 這個函式會傳回下一組結果。執行搜尋後,您必須等待兩秒,才能使用下一頁的搜尋結果。

如要查看下一組結果,請呼叫 nextPage。每頁結果都必須顯示,才會顯示下一頁。請注意,每次搜尋都會計入用量限制。

以下範例說明如何修改回呼函式來擷取 PlaceSearchPagination 物件,以便發出多個搜尋要求。

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
查看範例

查看範例

Place Details

除了提供區域內的地點清單外,Places 服務也可以傳回特定地點的詳細資訊。透過地點搜尋回應傳回地點後,即可利用其地點 ID 取得該地點的其他詳細資料,例如完整地址、電話號碼、使用者評分和評論等。

地點詳細資訊要求

透過呼叫服務的 getDetails() 方法要求 Place Details。

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

這個方法需要一項要求,其中包含所需地點的 placeId,以及指出要傳回哪種類型的 Places 資料類型欄位。進一步瞭解如何使用地點 ID 參照地點

該函式也會使用回呼方法,須處理 google.maps.places.PlacesServiceStatus 回應中傳遞的狀態碼和 google.maps.places.PlaceResult 物件。

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

查看範例

欄位 (地點詳細資料)

fields 參數採用字串陣列 (欄位名稱)。

使用 fields 參數指定要傳回的地點資料類型陣列。 例如:fields: ['address_component', 'opening_hours', 'geometry']。指定複合值時,請使用半形句號。例如:opening_hours.weekday_text

欄位會對應至 Place Details 結果,並分為三種計費類別:「Basic」、「Contact」和「Atmosphere」。基本欄位是按基本費率計費,不會產生額外費用。聯絡和氣氛資料欄位會以較高的費率計費;詳情請參閱價目表。無論是否已要求,每次呼叫都會傳回歸因 (html_attributions)。

基本版

「基本」類別包含下列欄位:
address_componentadr_addressbusiness_statusformatted_addressgeometryiconicon_mask_base_uriicon_background_colornamepermanently_closed (已淘汰))、 photoplace_idplus_codetypeurlutc_offset} utc_offset

聯絡人

「Contact」類別包含下列欄位:
formatted_phone_numberinternational_phone_numberopening_hourswebsite

氣氛

「氣氛」類別包含下列欄位:price_levelratingreviewuser_ratings_total

進一步瞭解地點欄位。如要進一步瞭解地點資料要求的計費方式,請參閱用量與帳單

地方資訊詳細資料回應

狀態碼

PlacesServiceStatus 回應物件包含要求的狀態,且可能包含偵錯資訊,以協助您追蹤 Place Details 要求失敗的原因。可能的狀態值如下:

  • INVALID_REQUEST:這個要求無效。
  • OK:回應包含有效的結果。
  • OVER_QUERY_LIMIT:網頁已超出要求配額。
  • NOT_FOUND 地點資料庫中找不到該參照位置。
  • REQUEST_DENIED:網頁不得使用 PlacesService。
  • UNKNOWN_ERROR:伺服器發生錯誤,無法處理 PlacesService 要求。如果重試,要求可能會成功。
  • ZERO_RESULTS:找不到這項要求的結果。

地點詳細資料結果

成功的 getDetails() 呼叫會傳回具有下列屬性的 PlaceResult 物件:

  • address_components:這個陣列包含此位址適用的獨立元件。

    每個地址元件通常包含下列欄位:

    • types[] 是一個陣列,指出地址元件的「類型」。請參閱支援的類型清單。
    • long_name 是 Geocoding 傳回的地址元件的完整文字說明或名稱。
    • short_name 是地址元件的縮寫文字名稱 (如果有的話)。舉例來說,阿拉斯加州的地址元件可能會包含「阿拉斯加」的 long_name,以及「AK」的 short_name;請使用 2 個字母的郵遞區號縮寫。

    請注意,以下有關 address_components[] 陣列的事實:

    • 地址元件的陣列可包含比 formatted_address 更多的元件。
    • 除了 formatted_address 中的實體以外,這個陣列不一定會包含含有地址的所有政治實體。如要擷取包含特定地址的所有政治實體,您應使用反向地理編碼,將地址的經緯度做為參數傳遞至要求。
    • 但不保證會讓要求的格式保持不變。具體來說,address_components 的數量會因要求的位址而異,且同一個地址可能會隨時間改變。元件可以變更陣列中的位置。元件類型可以變更。後續回覆中可能會缺少特定元件。
  • business_status 代表地點的營運狀態 (如果地點是商家)。可包含下列其中一個值:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    如果沒有資料,則不會傳回 business_status
  • formatted_address:使用者可理解的地點地址。

    這個地址通常相當於郵寄地址。請注意,受到授權限制,部分國家/地區 (例如英國) 不允許發布真實的郵寄地址。

    格式化的地址在邏輯上是由一或多個位址元件組成。舉例來說,地址為「111 8th Avenue, New York, NY」是由以下元件組成:「com111」(街道號碼)、「8th Avenue」(路線)、「New York」(紐約) 和「NY」(美國州) 等地址。)

    請勿以程式輔助方式剖析格式化的地址。請改用個別地址元件,API 回應除了格式化的地址欄位之外,也會包含此 API 回應。

  • formatted_phone_number:地點的電話號碼,格式取決於電話號碼慣例
  • geometry:地點的相關資訊。其中包括:
    • location 會提供地點的經緯度。
    • viewport 會在查看這個地點時,在地圖上定義偏好的可視區域。
  • permanently_closed (已淘汰) 是布林值標記,表示地點是永久關閉或暫時關閉 (值 true)。請勿使用 permanently_closed。請改用 business_status 取得商家運作狀態。
  • plus_code (請參閱開啟位置代碼加號代碼) 是編碼的位置參照,取自經緯度座標,代表區域:1/8000 度 x 1/8000 度 (赤道約 14m x 14m)。如果地點不存在或沒有命名街道,可以使用 Plus Code 取代街道地址。

    Plus Code 格式為全域代碼和複合程式碼:

    • global_code 是 4 個字元的區碼,加上 6 個字元以上的地區代碼 (849VCWC8+R9)。
    • compound_code 是 6 個字元以上的地區代碼,加上明確的位置 (例如 CWC8+R9、Mountain View, CA, USA)。請勿以程式輔助方式剖析這項內容。
    系統通常會傳回全域代碼和複合程式碼。不過,如果結果是位於遠端位置 (例如海洋或沙漠),則只能傳回全域代碼。
  • html_attributions:此地點搜尋結果顯示的歸因文字。
  • icon:用來代表此地點類型的圖片資源網址。
  • international_phone_number 包含國際電話號碼格式的電話號碼。國際電話號碼格式包含國家/地區代碼,前面加上加號 (+)。舉例來說,Google 位在澳洲雪梨的 international_phone_number 辦公室是 +61 2 9374 4000
  • name:地點名稱。
  • utc_offset在 Places Library、Maps JavaScript API 中的 已淘汰 屬性,請改用 utc_offset_minutes
  • utc_offset_minutes 包含這個地點目前時區 (世界標準時間) 的分鐘數。舉例來說,在澳洲雪梨日間使用日光節約地點時,儲存時間會是 660 (世界標準時間加上 11 小時),而加州以外的日光節約時間則為 -480 (世界標準時間為 -8 小時)。
  • opening_hours 包含下列資訊:
    • open_now (Places Library、Maps JavaScript API 中的 淘汰;請改用 opening_hours.isOpen()。請觀看這部影片,瞭解如何搭配 Place Details 使用 isOpen)。是布林值,表示地點目前是否營業。
    • periods[] 是一系列開放期間,從星期日開始以七天為單位。每個週期都包含:
      • open 包含一組日期和時間物件,用於說明地點開啟時間:
        • day 代表從星期日開始的一個 0 到 6 之間的數字。舉例來說,2 代表星期二。
        • time 可能包含 24 小時 hhmm 格式的時間 (值的範圍介於 0000 到 2359 之間)。系統將依據地點的時區回報 time
      • close 可能包含一組用來描述地點關閉時的日期和時間物件。注意:如果地點一律開啟,回應中會缺少 close 區段。應用程式可以一律開啟,也就是以包含 day 且值為 0,000 的 time 表示,且不含 closeopen 期間。
    • weekday_text 是七個字串陣列,代表每週每一天的格式化營業時間。如果「地點詳細資料」要求中指定了 language 參數,則「地點服務」會設定該語言適用的營業時間。這個陣列中的元素順序取決於 language 參數。有些語言會在週一開始,一週則從星期日開始。
  • permanently_closed (已淘汰) 是布林值標記,表示地點是永久關閉或暫時關閉 (值 true)。請勿使用 permanently_closed。請改用 business_status 取得商家營運狀態。
  • photos[]PlacePhoto 物件的陣列。PlacePhoto 可以使用 getUrl() 方法取得相片,或是檢查物件是否有下列值:
    • height:圖片的高度上限 (以像素為單位)。
    • width:圖片的寬度上限 (以像素為單位)。
    • html_attributions:此地點相片中顯示的歸因文字。
  • place_id:這是可識別地點的專屬文字 ID,可用於透過地點詳細資料要求擷取地點相關資訊。進一步瞭解如何使用地點 ID 參照地點
  • rating:地點評分 (0.0 分至 5.0 分),以匯總的使用者評論為依據。
  • reviews 包含最多五則評論的陣列。每則評論包含以下幾個元件:
    • aspects[] 包含 PlaceAspectRating 物件的陣列,每個物件都為地點的單一屬性評分。系統會將陣列中的第一個物件視為主要面向。每個 PlaceAspectRating 的定義為:
      • type 接受評分的層面名稱。支援下列類型:appealatmospheredecorfacilitiesfoodoverallqualityservice
      • rating 使用者對這個特定評分的評分,範圍從 0 到 3。
    • author_name提交評論的使用者名稱。匿名評論會歸類為「Google 使用者」。如果已設定語言參數,則「Google 使用者」詞組會傳回本地化字串。
    • author_url 使用者 Google+ 個人資料的網址 (如果有的話)。
    • language IETF 語言代碼,表示使用者評論所使用的語言。這個欄位只包含主要語言標記,而非代表國家或地區的次要標記。例如,所有英文評論都會標示為 'en',而非 'en-AU' 或 'en-UK',依此類推。
    • rating使用者為這個地點的整體評分。此為介於 1 至 5 之間的整數。
    • text使用者的評論。透過 Google 地方資訊評論地點時,文字評論會視為選填資訊,因此這個欄位可能會留空。
  • types 此地點的陣列類型 (例如["political", "locality"]["restaurant", "lodging"])。這個陣列可以包含多個值,也可以留空。不需事先通知,即可導入新的值。請參閱支援的類型清單。
  • url:這個地點的 Google 官方頁面網址。這是 Google 擁有的網頁,其中包含該地點的最佳資訊。應用程式必須在螢幕上顯示或嵌入這個網頁,讓使用者查看有關地點的詳細資訊。
  • vicinity:該地點的簡化地址,包括街道名稱、門牌號碼和縣市名稱,但不包括省/州、郵遞區號或國家/地區。舉例來說,Google # 澳洲辦公室的 vicinity 值為 5/48 Pirrama Road, Pyrmont。只有 Nearby Search 才會傳回 vicinity 屬性。
  • website 會列出這個地點的權威網站,例如商家和首頁。

注意:只有部分地點提供多維度評分功能。如果評論數量過少,詳細資料回應中會包含 0.0 至 5.0 分的舊版評分 (如果有的話),或是完全沒有評分。

以地點 ID 參照地點

地點 ID 是 Google 地圖上個別地點的專屬參照,大多數地點 (包括商家、地標、公園和十字路口) 都能使用地點 ID,

如要在應用程式中使用地點 ID,您必須先查詢 ID,可在 Place Search 或 Details 要求的 PlaceResult 中找到。接著,您可以使用這個地點 ID 來查詢地點詳細資料

地點 ID 不必符合《Google 地圖平台服務條款》第 3.2.3(a) 節所述的快取限制。方便您儲存地點 ID 值以供日後使用。如需瞭解儲存地點 ID 的最佳做法,請參閱地點 ID 總覽

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

地點相片

「地點相片」功能可讓您在網站中加入高品質的相片內容。「相片」服務可讓您存取地點和 Google+ 本機資料庫中數百萬張相片。使用 Place Details 要求取得地點資訊時,系統會傳回相關相片內容的相片參考。Nearby Search 和 Text Search 要求也會在適當情況下,傳回每個相片的單一相片參照。然後使用相片服務存取參照的相片,並根據應用程式尺寸將圖片大小調整至最佳大小。

針對針對 PlacesService 發出的任何 getDetails()textSearch()nearbySearch() 要求,系統會傳回 PlacePhoto 物件陣列,做為 PlaceResult 物件的一部分。

注意:系統傳回的相片數量會因要求而異。

  • 搜尋附近地點或文字搜尋最多會傳回一個 PlacePhoto 物件。
  • Details 要求最多會傳回十個 PlacePhoto 物件。

您可以呼叫 PlacePhoto.getUrl() 方法並傳遞有效的 PhotoOptions 物件,來要求相關圖片的網址。PhotoOptions 物件可讓您指定圖片的高度和寬度上限。如果您同時指定 maxHeightmaxWidth 的值,相片服務會將圖片大小調整為兩個大小中的較小,同時保持原始長寬比。

下列程式碼片段接受地點物件,如果相片有標記,則會在地圖中加入標記。預設標記圖片會替換成小型相片,

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

相片服務傳回的相片取自各種地點,包括業主和使用者提供的相片。在多數情況下,這類相片可在沒有歸因的情況下使用,或在圖片中納入必要的作者資訊。不過,如果傳回的 photo 元素在 html_attributions 欄位中包含值,請務必在應用程式顯示圖片時,在應用程式中加入額外的出處。