在您擁有來自「地點搜尋」的 place_id 或 reference 之後,便可起始「地點詳細資料」要求,來要求有關特定機構或搜尋點的更多詳細資料。「地點詳細資料」要求會傳回有關所指示之地點的更詳盡資訊,例如其完整地址、電話號碼、使用者評分和評論。
地點詳細資料要求
「地點詳細資料」要求是具有下列格式的 HTTP URL:
https://maps.googleapis.com/maps/api/place/details/output?parameters
其中 output 可以是下列任何一個值:
json(建議)指出以 JavaScript 物件標記法 (JSON) 格式輸出xml指出以 XML 格式輸出
某些參數是起始搜尋要求的必要參數。根據 URL 標準,所有參數都使用 & 字元來分隔。以下是參數清單及其可能的值。
key(必要) - 您應用程式的 API 金鑰。此金鑰可識別您的應用程式來進行配額管理,並且讓您的應用程式能夠立即使用從您的應用程式新增的地點。如需詳細資訊,請參閱取得金鑰。-
placeid或reference(您必須提供其中一個,但不得同時提供兩者):
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 旗標所指示的格式傳回。
{
"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 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_idAAA。稍後,此地點通過仲裁程序而收到 Google 範圍的place_idBBB。從此以後,此地點的資訊將會包含:"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- 所評分之觀點的名稱。支援下列類型:appeal、atmosphere、decor、facilities、food、overall、quality和service。rating- 使用者對此特定觀點的評分,從 0 到 3。
author_name- 提交評論的使用者名稱。匿名評論會視為由「Google 使用者」提出。author_url- 使用者 Google+ 個人資料(如果有的話)的 URL。language- 指出使用者評論中所使用之語言的 IETF 語言代碼。此欄位只包含主要語言標籤,而不包含指出國家或地區的次要標籤。例如,所有英文評論皆標記為 'en',而不是 'en-AU' 或 'en-UK' 等等。rating- 使用者對此地點的整體評分。這是一個整數,範圍從 1 到 5。text- 使用者的評論。使用「Google 地方資訊」來評論某個位置時,文字評論為選擇性。因此,此欄位可能空白。請注意,此欄位可能包括簡單 HTML 標記。例如,&這個實體參照可能代表 & 字元。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 標籤識別因其一貫高品質而著稱,或具有特殊或獨特特色的地點。
下列範例顯示 aspects 和 review_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 參數,以指出您的應用程式是否使用感應器來判斷使用者的位置。現在已不再需要此參數。