您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Places API Web Service

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Places API Web Service
  3. 建立適當的金鑰
繼續

地點詳細資料

在您擁有來自「地點搜尋」的 place_idreference 之後,便可起始「地點詳細資料」要求,來要求有關特定機構或搜尋點的更多詳細資料。「地點詳細資料」要求會傳回有關所指示之地點的更詳盡資訊,例如其完整地址、電話號碼、使用者評分和評論。

地點詳細資料要求

「地點詳細資料」要求是具有下列格式的 HTTP URL:

https://maps.googleapis.com/maps/api/place/details/output?parameters

其中 output 可以是下列任何一個值:

  • json (建議)指出以 JavaScript 物件標記法 (JSON) 格式輸出
  • xml 指出以 XML 格式輸出

某些參數是起始搜尋要求的必要參數。根據 URL 標準,所有參數都使用 & 字元來分隔。以下是參數清單及其可能的值。

  • key必要) - 您應用程式的 API 金鑰。此金鑰可識別您的應用程式來進行配額管理,並且讓您的應用程式能夠立即使用從您的應用程式新增的地點。如需詳細資訊,請參閱取得金鑰
  • placeidreference (您必須提供其中一個,但不得同時提供兩者):
    • placeid - 可唯一識別地點的文字型識別碼,由地點搜尋傳回。如需有關地點 ID 的詳細資訊,請參閱地點 ID 總覽
    • reference - 可唯一識別地點的文字型識別碼,由地點搜尋傳回。注意:reference 現在已被 place_id 取代。請參閱此頁面上的過時通知
選擇性參數
  • extensions選擇性) - 指出「地點詳細資料」回應是否應該包括額外欄位。額外欄位可能包括加值資料(需要額外的授權),或包括非通常要求的值。Extensions 目前為實驗性。支援的 extensions 參數值包括:
    • review_summary 包括由 Google 的編輯人員所策劃之既豐富又簡要的評論。
  • language選擇性) - 語言代碼,指出應該以哪一種語言傳回結果(如果可能的話)。請注意,有些欄位可能無法以所要求的語言提供。請參閱支援的語言清單與其代碼。請注意,我們經常更新支援的語言,因此這份清單可能並不詳盡。

下列範例會依 placeid 來要求地點的詳細資料:

https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJN1t_tDeuEmsRUsoyG83frY4&key=YOUR_API_KEY

請注意,您將必須以您自己的 API 金鑰取代此範例中的金鑰,才能讓此要求在您的應用程式中運作。

下列範例使用已過時的 reference 參數:

https://maps.googleapis.com/maps/api/place/details/json?reference=CmRYAAAAciqGsTRX1mXRvuXSH2ErwW-jCINE1aLiwP64MCWDN5vkXvXoQGPKldMfmdGyqWSpm7BEYCgDm-iv7Kc2PF7QA7brMAwBbAcqMr5i1f4PwTpaovIZjysCEZTry8Ez30wpEhCNCXpynextCld2EBsDkRKsGhSLayuRyFsex6JA6NPh9dyupoTH3g&key=YOUR_API_KEY

地點詳細資料回應

傳回「地點詳細資料」回應時,會依照要求之 URL 路徑內 output 旗標所指示的格式傳回。


JSON
{
   "html_attributions" : [],
   "result" : {
      "address_components" : [
         {
            "long_name" : "48",
            "short_name" : "48",
            "types" : [ "street_number" ]
         },
         {
            "long_name" : "Pirrama Road",
            "short_name" : "Pirrama Road",
            "types" : [ "route" ]
         },
         {
            "long_name" : "Pyrmont",
            "short_name" : "Pyrmont",
            "types" : [ "locality", "political" ]
         },
         {
            "long_name" : "NSW",
            "short_name" : "NSW",
            "types" : [ "administrative_area_level_1", "political" ]
         },
         {
            "long_name" : "AU",
            "short_name" : "AU",
            "types" : [ "country", "political" ]
         },
         {
            "long_name" : "2009",
            "short_name" : "2009",
            "types" : [ "postal_code" ]
         }
      ],
      "formatted_address" : "48 Pirrama Road, Pyrmont NSW, Australia",
      "formatted_phone_number" : "(02) 9374 4000",
      "geometry" : {
         "location" : {
           "lat" : -33.8669710,
           "lng" : 151.1958750
         },
         "viewport" : {
            "northeast" : {
               "lat" : -33.8665053,
               "lng" : 151.1960371
            },
            "southwest" : {
               "lat" : -33.8669293,
               "lng" : 151.1952183
            }
         }
      },
      "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
      "id" : "4f89212bf76dde31f092cfc14d7506555d85b5c7",
      "international_phone_number" : "+61 2 9374 4000",
      "name" : "Google Sydney",
      "place_id" : "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "scope" : "GOOGLE",
      "alt_ids" : [
         {
            "place_id" : "D9iJyWEHuEmuEmsRm9hTkapTCrk",
            "scope" : "APP"
         }
      ],
      "rating" : 4.70,
      "reference" : "CnRsAAAA98C4wD-VFvzGq-KHVEFhlHuy1TD1W6UYZw7KjuvfVsKMRZkbCVBVDxXFOOCM108n9PuJMJxeAxix3WB6B16c1p2bY1ZQyOrcu1d9247xQhUmPgYjN37JMo5QBsWipTsnoIZA9yAzA-0pnxFM6yAcDhIQbU0z05f3xD3m9NQnhEDjvBoUw-BdcocVpXzKFcnMXUpf-nkyF1w",
      "reviews" : [
         {
            "aspects" : [
               {
                  "rating" : 3,
                  "type" : "quality"
               }
            ],
            "author_name" : "Simon Bengtsson",
            "author_url" : "https://plus.google.com/104675092887960962573",
            "language" : "en",
            "rating" : 5,
            "text" : "Just went inside to have a look at Google. Amazing.",
            "time" : 1338440552869
         },
         {
           "aspects" : [
              {
                 "rating" : 3,
                 "type" : "quality"
              }
             ],
            "author_name" : "Felix Rauch Valenti",
            "author_url" : "https://plus.google.com/103291556674373289857",
            "language" : "en",
            "rating" : 5,
            "text" : "Best place to work :-)",
            "time" : 1338411244325
         },
         {
           "aspects" : [
              {
                 "rating" : 3,
                 "type" : "quality"
              }
             ],
            "author_name" : "Chris",
            "language" : "en",
            "rating" : 5,
            "text" : "Great place to work, always lots of free food!",
            "time" : 1330467089039
         }
      ],
      "types" : [ "establishment" ],
      "url" : "http://maps.google.com/maps/place?cid=10281119596374313554",
      "vicinity" : "48 Pirrama Road, Pyrmont",
      "website" : "http://www.google.com.au/"
   },
   "status" : "OK"
}
      
XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceDetailsResponse>
 <status>OK</status>
 <result>
  <name>Google Sydney</name>
  <vicinity>48 Pirrama Road, Pyrmont</vicinity>
  <type>establishment</type>
  <formatted_phone_number>(02) 9374 4000</formatted_phone_number>
  <formatted_address>48 Pirrama Road, Pyrmont NSW, Australia</formatted_address>
  <address_component>
   <long_name>48</long_name>
   <short_name>48</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Pirrama Road</long_name>
   <short_name>Pirrama Road</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Pyrmont</long_name>
   <short_name>Pyrmont</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>NSW</long_name>
   <short_name>NSW</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>AU</long_name>
   <short_name>AU</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>2009</long_name>
   <short_name>2009</short_name>
   <type>postal_code</type>
  </address_component>
  <geometry>
   <location>
     <lat>-33.8669710</lat>
     <lng>151.1958750</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8669293</lat>
     <lng>151.1952183</lng>
    </southwest>
    <northeast>
     <lat>-33.8665053</lat>
     <lng>151.1960371</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.7</rating>
  <url>http://maps.google.com/maps/place?cid=10281119596374313554</url>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png</icon>
  <place_id>ChIJN1t_tDeuEmsRUsoyG83frY4</place_id>
  <scope>GOOGLE</scope>
  <alt_ids>
   <place_id>D9iJyWEHuEmuEmsRm9hTkapTCrk</place_id>
   <scope>APP</scope>
  </alt_ids>
  <reference>CnRsAAAAoGXc0eAcQOoO1A7sU58repRnghwM5q7UtsZFhVtjYtfKN_LFAPhdhBfUAU8m0EzeSyP0cDBi7kazZwNjlIMUqktqIanMiymuRDS8c539M6KCJNUMkjw22WXxtl3QoR25fIf-7YJnpza6bMIuFZ1CKBIQuBsbXu8xkbUNofECCkdvmxoU5k3Lpbr8XNCbofIKtsZxj8GloGA</reference>
  <id>4f89212bf76dde31f092cfc14d7506555d85b5c7</id>
  <international_phone_number>+61 2 9374 4000</international_phone_number>
  <website>http://www.google.com.au/</website>
  <review>
   <time>1338440552869</time>
   <text>Just went inside to have a look at Google. Amazing.</text>
   <author_name>Simon Bengtsson</author_name>
   <author_url>https://plus.google.com/104675092887960962573</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
  <review>
   <time>1338411244325</time>
   <text>Best place to work :-)</text>
   <author_name>Felix Rauch Valenti</author_name>
   <author_url>https://plus.google.com/103291556674373289857</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
  <review>
   <time>1330467089039</time>
   <text>Great place to work, always lots of free food!</text>
   <author_name>Chris</author_name>
   <author_url>https://maps.google.com/maps/user?uid=211457841236072500285</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
 </result>
</PlaceDetailsResponse>

JSON 回應包含三個根元素:

  • "status" 包含與要求相關的中繼資料。請參閱下方的狀態碼
  • "result" 包含所要求之地點的相關詳細資訊。請參閱地點詳細資料結果,以取得這些結果的相關資訊。
  • "html_attributions" 包含必須對使用者顯示、關於此清單的一組相關資料引用標示。

請參閱使用 Javascript 處理 JSON,以取得剖析 JSON 回應的說明。

XML 回應是由單一 <PlaceDetailsResponse> 和三個頂層元素所組成:

  • <status> 包含與要求相關的中繼資料。請參閱狀態碼
  • 包含單一機構之相關詳細資訊的單一 <result> 元素。請參閱地點詳細資料結果,以取得這些結果的相關資訊。
  • <html_attributions> 包含必須對使用者顯示的一組資料引用標示。

如需一些適用於輸出處理的建議設計模式,請參閱使用 XPath 剖析 XML

狀態碼

地點回應物件內的 "status" 欄位包含要求的狀態,並且可能包含可協助您探究地點要求失敗原因的偵錯資訊。"status" 欄位可能包含下列值:

  • OK 指出未發生任何錯誤;已順利偵測到地點並至少傳回一個結果。
  • UNKNOWN_ERROR 指出發生伺服器端錯誤;再試一次可能就會成功。
  • ZERO_RESULTS 指出參照有效,但已不再參照有效的結果。如果該機構已經沒有在營業,便可能發生這種情況。
  • OVER_QUERY_LIMIT 指出已超出您的配額。
  • REQUEST_DENIED 指出您的要求已被拒絕,通常是因為缺少無效的 key 參數。
  • INVALID_REQUEST 通常指出缺少查詢 (reference)。
  • NOT_FOUND 指出在「地方資訊」資料庫中找不到所參照的位置。

錯誤訊息

當「Google 地方資訊」服務傳回 OK 以外的狀態碼時,詳細資料回應物件內可能會有額外的 error_message 欄位。此欄位包含有關所提供之狀態碼背後原因的更多詳細資訊。

地點詳細資料結果

當「地方資訊」服務從詳細資料要求傳回結果時,會將這些結果放在單一的 results 內。每個結果可能包含下列欄位:

  • address_components[] 是用來構成指定之地址的個別地址元件陣列。例如,"111 8th Avenue, New York, NY" 包含代表 "111"(門牌號碼、"8th Avenue"(街道)、"New York"(城市)和 "NY"(美國州別)的個別地址元件。每個 address_component 通常包含:
    • types[] 是指出地址元件之「類型」的陣列。
    • long_name 是地址元件的完整文字描述或名稱。
    • short_name 是地址元件的縮寫文字型名稱(如果有的話)。例如,阿拉斯加州的地址元件可能包含 long_name "Alaska",以及使用 2 個字母郵政縮寫的 short_name "AK"。
  • formatted_address 是一個字串,包含人類看得懂的此地點地址。此地址通常等於「郵政地址」,有時會因國家/地區而異。此地址通常是由一或多個 address_component 欄位所組成。
  • formatted_phone_number 包含地點的當地格式電話號碼。例如,Google 的澳洲雪梨辦公室 formatted_phone_number(02) 9374 4000
  • geometry 包含下列資訊:
    • location 包含此地點的地理編碼「緯度,經度」值。
    • viewport 包含在地圖上將此地點顯示為 LatLngBounds 時的偏好檢視點(如果已知)。
  • icon 包含建議之圖示的網址;此圖示是在地圖上指示這個結果時,可能會對使用者顯示的圖示。
  • id 包含代表此地點的唯一固定識別碼。此識別碼無法用來擷取此地點的相關資訊,但可用來合併此地點的相關資料,以及在個別的搜尋中驗證地點的識別資訊。由於 ID 可能偶爾會變更,因此建議將儲存的地點 ID 與稍後在「詳細資料」要求中針對此相同地點傳回的 ID 做比較,並視需要加以更新。注意:id 現在已被 place_id 取代。請參閱此頁面上的過時通知
  • international_phone_number 包含地點的國際格式電話號碼。國際格式包括國碼,而且前面加上加號 (+)。例如,Google 澳洲雪梨辦公室的 international_phone_number+61 2 9374 4000
  • name 包含人類看得懂的傳回結果名稱。對於 establishment 結果,這通常是標準化的商家名稱。
  • opening_hours 包含下列資訊:
    • open_now 是一個布林值,指出地點目前是否營業中。
    • periods[] 是一個從星期天開始、為期七天的營業期間陣列,依時間先後排序。每個期間皆包含:
      • open 包含描述地點何時營業的一組日別和時間物件:
        • day 是 0 到 6 的數字,對應星期幾,從星期天開始。例如,2 代表星期二。
        • time 可包含 24 小時 hhmm 格式的一天時間。值的範圍為 0000 到 2359。time 將以地點的時區報時。
      • close 包含描述地點何時打烊的一組日別和時間物件。注意:如果地點永不打烊,回應中就不會有 close 區段。當 open 期間包含值為 0 的 day 和值為 0000 的 time,而且沒有 close 時,客戶即可確信其為永不打烊。
    • weekday_text 是一個 7 個字串的陣列,代表週一到週日每天的營業時數。如果「地點詳細資料」要求中指定了 language 參數,「地方資訊服務」將會以該語言適當地呈現出格式化與當地語系化的營業時間。此陣列中元素的順序視 language 參數而定。某些語言以週一為每週的開始,其他則以週日為開始。
  • permanently_closed 是布林旗標,用來指出地點是否永久關閉(值為 true)。如果地點不是永久關閉,則回應中不會有該旗標存在。
  • photos[]photo 物件的陣列,每個物件皆包含影像的參照。「地點詳細資料」要求最多會傳回十張相片。如需有關「地點相片」及如何在您應用程式中使用影像的詳細資訊,請參閱地點相片文件。photo 物件以下列方式描述:
    • photo_reference - 當您執行「相片」要求時,用來識別相片的字串。
    • height - 影像的高度上限。
    • width - 影像的寬度上限。
    • html_attributions[] - 包含任何必要的資料引用標示。此欄位一律會存在,但可以為空白。
  • place_id:可唯一識別地點的文字型識別碼。如果要擷取地點的相關資訊,請在 Places API 要求的 placeId 欄位中傳遞此識別碼。如需有關地點 ID 的詳細資訊,請參閱地點 ID 總覽
  • scope:指出 place_id 的範圍。可能的值包括:
    • APP:此地點 ID 僅供您的應用程式識別。這是因為您的應用程式新增了該地點,而該地點尚未通過仲裁程序。
    • GOOGLE:此地點 ID 可供其他應用程式使用,以及在「Google 地圖」上使用。
  • alt_ids - 地點之內含零個、一個或多個替代地點 ID 的陣列,含有與每個替代 ID 相關的範圍。注意:此陣列可能是空的或不存在。如果存在,則會包含下列欄位:
    • place_id - 一個地點擁有替代地點 ID 的最可能原因,就是您的應用程式新增一個地點並收到應用程式範圍的地點 ID,然後稍後再於通過仲裁程序之後收到 Google 範圍的地點 ID。
    • scope - 替代地點 ID 的範圍將一律是 APP,表示此替代地點 ID 僅供您的應用程式識別。
    例如,假設您的應用程式新增一個地點,並收到新地點的 place_id AAA。稍後,此地點通過仲裁程序而收到 Google 範圍的 place_id BBB。從此以後,此地點的資訊將會包含:
        "results" : [
          {
            "place_id" : "BBB",
            "scope" : "GOOGLE",
            "alt_ids" : [
              {
                "place_id" : "AAA",
                "scope" : "APP",
              }
            ],
          }
        ]
        
  • price_level - 此地點的價格等級,等級為 0 到 4。特定值所代表的確切金額將因地區而異。價格等級的解釋如下:
    • 0 - 免費
    • 1 - 便宜
    • 2 - 適中
    • 3 - 昂貴
    • 4 - 非常昂貴
  • rating 包含地點的評分,從 1.0 到 5.0,以加總的使用者評論為依據。
  • reference 包含可用來在未來查詢「詳細資料」服務的語彙基元。此語彙基元可能與對「詳細資料」服務發出的要求中所使用的參照不同。建議定期更新所儲存的地點參照。雖然此語彙基元可唯一識別此地點,但此地點並不僅限擁有一個語彙基元。一個地點可以有許多有效的參照語彙基元。注意:reference 現在已被 place_id 取代。請參閱此頁面上的過時通知
  • reviews[] 是最多可包含五個評論的 JSON 陣列。如果「地點詳細資料」要求中指定了 language 參數,「地方資訊服務」將會偏向使用以該語言撰寫的評論當作結果。每個評論皆由數個元件組成:
    • aspects 包含 AspectRating 物件的集合,每個物件皆提供該機構單一屬性的評分。集合中的第一個物件被視為主要觀點。每個 AspectRating 皆以下列方式描述:
      • type - 所評分之觀點的名稱。支援下列類型:appealatmospheredecorfacilitiesfoodoverallqualityservice
      • rating - 使用者對此特定觀點的評分,從 0 到 3。
    • author_name - 提交評論的使用者名稱。匿名評論會視為由「Google 使用者」提出。
    • author_url - 使用者 Google+ 個人資料(如果有的話)的 URL。
    • language - 指出使用者評論中所使用之語言的 IETF 語言代碼。此欄位只包含主要語言標籤,而不包含指出國家或地區的次要標籤。例如,所有英文評論皆標記為 'en',而不是 'en-AU' 或 'en-UK' 等等。
    • rating - 使用者對此地點的整體評分。這是一個整數,範圍從 1 到 5。
    • text - 使用者的評論。使用「Google 地方資訊」來評論某個位置時,文字評論為選擇性。因此,此欄位可能空白。請注意,此欄位可能包括簡單 HTML 標記。例如,&amp; 這個實體參照可能代表 & 字元。
    • time - 提交評論的時間,測量單位為秒,自 1970 年 1 月 1 日午夜 (UTC) 起算。
  • types[] 包含描述所提供之結果的功能類型陣列。請參閱支援的類型清單以瞭解詳細資訊。如果指派多個類型給結果,XML 回應就會包括多個 <type> 元素。
  • url 包含此地點的官方 Google 頁面 URL。這是 Google 所擁有、包含地點相關之最佳可用資訊的頁面。應用程式必須在對使用者顯示地點相關詳細結果的任何畫面上,連結到此頁面或內嵌此頁面。
  • utc_offset 包含此地點目前時區與 UTC 的時間差(單位為分鐘)。例如,如果是日光節約時間期間內的澳洲雪梨地點,這會是 660 (與 UTC 的時差為 +11 小時),如果是日光節約時間期間外的加州地點,則會是 -480 (與 UTC 的時差為 -8 小時)。
  • vicinity 會列出地點的簡化地址,包括街道名稱、門牌號碼和郵遞分區,但不包括縣/市、郵遞區號或國家/地區。例如,Google 的澳洲雪梨辦公室的 vicinity 值為 48 Pirrama Road, Pyrmont
  • website 會列出此地點的權威網站,例如商家的首頁。

並非所有位置都會有多方面的評分。如果評論數目太少,則詳細資料回應將會包括傳統 1.0 到 5.0 等級的評分(如果有的話),或沒有評分。

加值資料

除了上面所列的欄位之外,擁有 Premium Plan 授權的 Google Places API 客戶還可能收到下列欄位。這些欄位將顯示為 result 欄位的頂層子項。

  • aspects 包含 AspectRating 物件的集合,每個物件皆提供該機構單一屬性的彙總評分。集合中的第一個物件被視為主要觀點。每個 AspectRating 皆以下列方式描述:
    • type - 所評分之觀點的名稱。例如:atmosphere、service、food、overall 等等。
    • rating - 此特定觀點的彙總評分,從 0 到 30。請注意,彙總評分的範圍是從 0 到 30,而在評論內的評分範圍是從 0 到 3。
  • review_summary 包括由 Google 的編輯人員所策劃之既豐富又簡要的評論。除非您在詳細資料要求中傳遞 extensions=review_summary 參數,否則不會有此欄位。請注意,此欄位可能無法以所要求的語言提供。
  • zagat_selected 指出地點已被評選為 Zagat 優良地點。Zagat 標籤識別因其一貫高品質而著稱,或具有特殊或獨特特色的地點。
如需詳細資訊,請參閱加值資料

下列範例顯示 aspectsreview_summary 欄位在回應主體中顯示的樣子:

"aspects" : [
   {
      "rating" : 24,
      "type" : "food"
   },
   {
      "rating" : 21,
      "type" : "decor"
   },
   {
      "rating" : 24,
      "type" : "service"
   }
],

...

"review_summary" : "For a meal that's a \"leisurely celebration\",
Mountain View \"foodies\" head to this \"lovely\" old Victorian house, where
\"artful\", \"high-end\" New French tasting dinners that \"look great and taste
even better\" are enhanced by sommelier-selected wines and service that
\"anticipates your every need\"; a garden out back supplies some ingredients,
while four dining areas provide \"lovely decor and ambiance\"; P.S. an
abbreviated tasting menu is also available."

sensor 參數

Google Places API Web Service 先前要求您包括 sensor 參數,以指出您的應用程式是否使用感應器來判斷使用者的位置。現在已不再需要此參數。

傳送您對下列選項的寶貴意見...

這個網頁
location_on
Google Places API Web Service