Find Place (舊版)

歐洲經濟區 (EEA) 開發人員

「透過查詢尋找地點 (舊版)」會根據文字輸入內容傳回地點。輸入內容可以是任何種類的地點文字資料,例如名稱、地址或電話號碼。要求必須是字串。使用非字串資料 (例如經緯度座標或 plus code) 的 Find Place (舊版) 要求會產生錯誤。

Find Place (舊版) 要求

Find Place (舊版) 要求是下列形式的 HTTP 網址:

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

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

  • json (建議使用) 表示以 JavaScript 物件標記法 (JSON) 輸出
  • xml 表示輸出為 XML

您必須提供特定參數,才能發出「Find Place (舊版)」要求。依照網址標準,所有參數都會以 & 字元分隔。

必要參數

  • 輸入

    要搜尋的文字字串。這必須是地點名稱、地址或電話號碼 (例如「中正路 123 號」或「市府大樓」)。

  • inputtype

    輸入類型。可以是 textqueryphonenumber。電話號碼必須採用國際電話號碼格式 (開頭為加號 (「+」),後面接著國家/地區代碼,然後是電話號碼本身)。詳情請參閱 E.164 ITU 建議書

選用參數

  • 欄位

    注意:Place Search (Legacy) 要求和 Place Details (Legacy) 要求不會傳回相同的欄位。Place Search (舊版) 要求會傳回 Place Details (舊版) 要求傳回的部分欄位。如果 Place Search (舊版) 沒有傳回所需的欄位,您可以使用 Place Search (舊版) 取得 place_id,然後使用該 Place ID 提出 Place Details (舊版) 要求。如要進一步瞭解 Place Search (舊版) 要求中無法使用的欄位,請參閱「Places API 欄位支援」。

    使用 fields 參數指定要傳回的地點資料類型,並以逗號分隔的清單表示。例如:fields=formatted_address,name,geometry。指定複合值時,請使用斜線,例如: opening_hours/open_now

    欄位分為三種計費類別: 基本聯絡資訊氣氛。 「Basic」欄位以基本費率計費,「Contact」和「Atmosphere」欄位則以較高的費率計費。除了基本 SKU (Places Details、Find Place、Nearby Search 或 Text Search) 以外,系統也會針對觸發要求的 Basic、Contact 和 Atmosphere SKU 收費。詳情請參閱價目表

    基本版

    「Basic」類別包含下列欄位: address_componentsadr_addressbusiness_statusformatted_addressgeometryiconicon_mask_base_uriicon_background_colornamepermanently_closed (已淘汰)、photoplace_idplus_codetypeurlutc_offsetvicinitywheelchair_accessible_entrance

    聯絡人

    「Contact」類別包含下列欄位: current_opening_hoursformatted_phone_number international_phone_numberopening_hours secondary_opening_hourswebsite

    Atmosphere

    「Atmosphere」類別包含下列欄位: curbside_pickupdeliverydine_ineditorial_summaryprice_levelratingreservablereviewsserves_beerserves_breakfastserves_brunchserves_dinnerserves_lunchserves_vegetarian_foodserves_winetakeoutuser_ratings_total

    注意:無論是否要求作者資訊欄位,每次呼叫一律都會傳回作者資訊 (html_attributions)。
  • language

    傳回結果時使用的語言。

    • 查看支援語言清單。Google 會經常更新支援的語言,因此這份清單可能不完整。
    • 如果未提供 language,API 會嘗試使用 Accept-Language 標頭中指定的偏好語言。
    • API 會盡量提供使用者和當地人都能辨識的街道地址。為達成這個目標,系統會以當地語言傳回街道地址,並視需要根據偏好語言,將地址音譯為使用者可讀取的文字。所有其他地址都會以偏好語言顯示。地址元件一律會以同一種語言傳回,而該語言是從第一個元件中選擇。
    • 如果偏好語言沒有名稱,API 會使用最接近的名稱。
    • 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言解讀縮寫,例如街道類型縮寫,或在某種語言中有效但在另一種語言中無效的同義詞。舉例來說,utcatér 是匈牙利文的街道同義詞。
  • locationbias

    如要優先顯示特定區域的結果,請指定半徑和經緯度,或指定代表矩形兩點的兩組經緯度。如未指定這個參數,API 預設會使用 IP 位址偏誤。

    • IP 偏誤:指示 API 使用 IP 位址偏誤。傳送字串 ipbias (這個選項沒有其他參數)。
    • 圓形:字串,指定半徑 (以公尺為單位),以及十進制度數的經緯度。請使用下列格式:circle:radius@lat,lng
    • 矩形:字串,以十進制度數指定兩組經緯度,代表矩形的西南和東北點。請使用下列格式:rectangle:south,west|north,east。請注意,東西向值會包裝到 -180 到 180 的範圍,南北向值則會限制在 -90 到 90 的範圍內。

Find Place (舊版) 範例

以下範例顯示搜尋「澳洲當代藝術博物館」的「Find Place (舊版)」要求,指定的欄位包括 photosformatted_addressnameratingopening_hoursgeometry

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Museum%20of%20Contemporary%20Art%20Australia
    &inputtype=textquery
    &key=YOUR_API_KEY

以下範例顯示「蒙古烤肉」的 Find Place (舊版) 要求,使用 locationbias 參數偏好指定座標 2000 公尺內的結果:

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Mongolian%20Grill&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&locationbias=circle:2000@−33.866,151.216&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Mongolian%20Grill
    &inputtype=textquery
    &locationbias=circle:2000@−33.866,151.216
    &key=YOUR_API_KEY

以下範例顯示電話號碼的「尋找地點 (舊版)」要求。請注意,國際電話前置字元「+」已編碼為 %2B,因此這項要求是符合規定的網址。如果未編碼,伺服器會將 + 前置字元解碼為空格,導致電話號碼查詢無效。

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B16502530000&inputtype=phonenumber&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=%2B16502530000
    &inputtype=phonenumber
    &key=YOUR_API_KEY

Find Place (舊版) 回應

「尋找地點 (舊版)」回應只會包含使用 fields 參數指定的資料類型,以及 html_attributions。以下範例顯示「澳洲當代藝術博物館」的「Find Place (舊版)」要求回應,包括 formatted_addressgeometrynameopening_hoursphotosrating 欄位。

JSON

{
  "candidates":
    [
      {
        "formatted_address": "140 George St, The Rocks NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8599358, "lng": 151.2090295 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85824377010728, "lng": 151.2104386798927 },
                "southwest":
                  { "lat": -33.86094342989272, "lng": 151.2077390201073 },
              },
          },
        "name": "Museum of Contemporary Art Australia",
        "opening_hours": { "open_now": false },
        "rating": 4.4,
      },
    ],
  "status": "OK",
}    

XML

<?xml version="1.0" encoding="UTF-8"?>
<FindPlaceFromTextResponse>
 <candidates>
  <name>Museum of Contemporary Art Australia</name>
  <formatted_address>140 George St, The Rocks NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8599358</lat>
    <lng>151.2090295</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8609434</lat>
     <lng>151.2077390</lng>
    </southwest>
    <northeast>
     <lat>-33.8582438</lat>
     <lng>151.2104387</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.4</rating>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
 </candidates>
 <status>OK</status>
</FindPlaceFromTextResponse>

    

PlacesFindPlaceFromTextResponse

欄位 必填 類型 說明
required 陣列<Place>

包含建議地點的陣列。

Place Search (舊版) 要求會傳回 Place Details (舊版) 要求傳回的部分欄位。如果 Place Search (舊版) 沒有傳回所需的欄位,您可以使用 Place Search (舊版) 取得地點 ID,然後使用該地點 ID 提出 Place Details (舊版) 要求。

詳情請參閱「地點」。

required PlacesSearchStatus

內含要求的狀態,還可能包含偵錯資訊,方便您追查要求失敗的原因。

詳情請參閱 PlacesSearchStatus

選填 字串

如果服務傳回的狀態碼不是 OK<,回應物件中可能會有額外的 error_message 欄位。這個欄位包含有關指定狀態碼背後原因的詳細資訊。這個欄位不一定會傳回,且內容可能會變更。

選填 陣列<字串>

如果服務傳回要求規格的額外資訊,回應物件中可能會出現額外的 info_messages 欄位。只有在要求成功時,才會傳回這個欄位。這項屬性不一定會傳回,且內容可能會變更。

PlacesSearchStatus

服務傳回的狀態碼。

  • OK:表示 API 要求成功。
  • ZERO_RESULTS 表示搜尋成功,但未傳回任何結果。如果搜尋傳遞至遠端位置的 latlng,就可能發生這種情況。
  • INVALID_REQUEST:表示 API 要求格式有誤,通常是因為缺少必要查詢參數 (locationradius)。
  • OVER_QUERY_LIMIT,表示下列任一情況:
    • 您已超過每秒查詢次數限制。
    • 您的帳戶尚未啟用計費功能。
    • 超過每月 $200 美元的抵免額或自行設定的用量上限。
    • 您提供的付款方式已失效 (例如信用卡已過期)。
    請參閱 地圖常見問題 ,進一步瞭解如何解決這項錯誤。
  • REQUEST_DENIED:表示您的要求遭拒,一般是因為:
    • 要求缺少 API 金鑰。
    • key」參數無效。
  • UNKNOWN_ERROR:表示發生未知錯誤。

地點

描述地點的屬性。並非所有屬性都適用於所有地點類型。

欄位 必填 類型 說明
選填 Array<AddressComponent>

這個陣列包含這個地址適用的各種元件。

詳情請參閱 AddressComponent

選填 字串

adr 微格式表示地點的地址。

選填 字串

表示地點的營業狀態 (如果地點為商家)。 如果沒有任何資料,則不會傳回 business_status

The allowed values include: OPERATIONAL, CLOSED_TEMPORARILY, and CLOSED_PERMANENTLY
選填 布林值

指定商家是否支援路邊取餐。

選填 PlaceOpeningHours

包含接下來七天 (包括今天) 的營業時間。時間範圍從要求當天的午夜開始,並在六天後的晚上 11:59 結束。這個欄位包含所有時段的 special_days 子欄位,適用於有例外營業時間的日期。

詳情請參閱 PlaceOpeningHours

選填 布林值

指定商家是否支援外送。

選填 布林值

指定商家是否提供室內或室外雅座選項。

選填 PlaceEditorialSummary

含有地點摘要。摘要包含文字總覽,以及適用的語言代碼。摘要文字必須照實呈現,不得修改或變更。

詳情請參閱 PlaceEditorialSummary

選填 字串

字串,包含這個地點的清楚易懂地址。

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

格式化地址在邏輯上是由一或多個地址元件組成。舉例來說,「111 8th Avenue, New York, NY」這個地址包含以下元件:「111」(門牌號碼)、「8th Avenue」(路名)、「New York」(城市) 和「NY」(美國州名)。

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

選填 字串

包含地點的電話號碼 (當地格式)。

選填 Geometry

內含位置和位置的可視區域。

詳情請參閱 Geometry

選填 字串

包含建議圖示的網址,在使用者於地圖上指出這項結果時,系統可能會向使用者顯示該圖示。

選填 字串

包含地點類別的預設十六進位顏色代碼。

選填 字串

包含建議圖示的網址,刪除 .svg.png 檔案類型副檔名。

選填 字串

包含地點的電話號碼 (國際電話號碼格式)。國際電話號碼格式包含國碼,且前置字元為加號 (+)。舉例來說,Google 澳洲雪梨辦公室的 international_phone_number 為 +61 2 9374 4000

選填 字串

包含傳回結果的使用者可解讀名稱。如果是 establishment 結果,這通常是標準化的商家名稱。

選填 PlaceOpeningHours

包含一般營業時間。

詳情請參閱 PlaceOpeningHours

選填 布林值

使用 business_status 取得商家的營業狀態。

選填 陣列<PlacePhoto>

相片物件陣列,每個物件都包含圖片的參照。要求最多會傳回十張相片。如要進一步瞭解地點相片,以及如何在應用程式中使用這些圖片,請參閱「地點相片」說明文件。

詳情請參閱 PlacePhoto

選填 字串

用來識別特定地點的文字 ID,如要擷取地點資訊,請在 Places API 要求的 place_id 欄位中傳遞這個 ID。如要進一步瞭解地點 ID,請參閱地點 ID 總覽

選填 PlusCode

經過編碼的位置參照,衍生自經緯度座標,表示面積不超過 1/8000 度 x 1/8000 度 (在赤道區約 14 公尺 x 14 公尺) 的區域。對於沒有詳細地址的地點,Plus Codes 可用於取代街道地址,例如無編號的建築物或無名街道。請參閱「開放式位置代碼」和「Plus Codes」。

詳情請參閱 PlusCode

選填 數字

地點的價格等級,範圍為 0 到 4。特定值所代表的確切金額會因地區而異。價格等級的解讀方式如下:

  • 0 免費
  • 1 低價位
  • 2 中等
  • 3 Expensive
  • 4 超高價位
選填 數字

包含地點評分 (1.0 到 5.0,根據綜合使用者評論計算)。

選填 字串
選填 布林值

指出地點是否支援預訂。

選填 Array<PlaceReview>

最多包含五則評論的 JSON 陣列。評論預設會依關聯性排序。使用 reviews_sort 要求參數控制排序。

  • 如果是 most_relevant (預設),評論會依關聯性排序;服務會偏向回傳以偏好語言撰寫的評論。
  • newest 中,評論會依時間先後排序,偏好語言不會影響排序方式。

Google 建議向使用者說明結果是否依 most_relevantnewest 排序。

詳情請參閱 PlaceReview

選填 字串
選填 Array<PlaceOpeningHours>

包含未來七天的項目陣列,包括商家次要營業時間的相關資訊。次要營業時間與商家的主要營業時間不同。舉例來說,餐廳可以將得來速或外送時間指定為次要營業時間。這個欄位會填入 type 子欄位,該子欄位會根據地點類型,從預先定義的營業時間類型清單 (例如 DRIVE_THROUGHPICKUPTAKEOUT) 中提取資料。這個欄位包含所有時數的 special_days 子欄位,並為有例外營業時間的日期設定時數。

詳情請參閱 PlaceOpeningHours

選填 布林值

指定地點是否供應啤酒。

選填 布林值

指定商家是否供應早餐。

選填 布林值

指定地點是否供應早午餐。

選填 布林值

指定該場所是否供應晚餐。

選填 布林值

指定該場所是否供應午餐。

選填 布林值

指定該場所是否供應素食餐點。

選填 布林值

指定地點是否供應葡萄酒。

選填 布林值

指定商家是否支援外帶。

選填 陣列<字串>

包含描述指定結果的特徵類型陣列。請參閱支援類型清單。

選填 字串

內含這個地點的官方 Google 頁面網址。這是 Google 自有的頁面,內含該地點的實用資訊。在向使用者顯示地點詳細結果的任何畫面上,應用程式必須連結或嵌入這個頁面。

選填 數字

這個地點的評論總數 (無論是否包含文字)。

選填 數字

包含這個地點目前時區與世界標準時間的時差 (以分鐘為單位)。舉例來說,澳洲雪梨在日光節約時間的時差為 660 (+11 小時 (UTC)),加州在非日光節約時間的時差為 -480 (-8 小時 (UTC))。

選填 字串

如果是機構 (types:["establishment", ...])) 結果,vicinity 欄位會包含地點的簡化地址,包括街道名稱、門牌號碼和縣市,但不含省/州、郵遞區號或國家/地區。

對於所有其他結果,vicinity 欄位會包含結果地址中最窄的政治 (types:["political", ...]) 特徵名稱。

這類內容應按原樣讀取。請勿以程式輔助方式剖析格式化地址。

選填 字串

這個地點的官方網站,例如商家的首頁。

選填 布林值

指定該地點是否設有無障礙入口。

PlaceEditorialSummary

含有地點摘要。摘要包含文字總覽,以及這些文字的語言代碼 (如適用)。摘要文字必須照實呈現,不得修改或變更。

欄位 必填 類型 說明
選填 字串

前幾個欄位的語言。不一定會顯示。

選填 字串

地點的文字摘要,長度適中。

PlaceOpeningHours

說明地點營業時間的物件。

欄位 必填 類型 說明
選填 布林值

布林值,指出地點目前是否營業中。

選填 Array<PlaceOpeningHoursPeriod>

涵蓋 7 天的營業時段陣列,從週日開始,按時間順序排列。

詳情請參閱「PlaceOpeningHoursPeriod」。

選填 Array<PlaceSpecialDay>

最多七個項目的陣列,對應未來七天。

詳情請參閱 PlaceSpecialDay

選填 字串

用來識別次要營業時間類型的類型字串 (例如 DRIVE_THROUGHHAPPY_HOURDELIVERYTAKEOUTKITCHENBREAKFASTLUNCHDINNERBRUNCHPICKUPSENIOR_HOURS)。僅適用於 secondary_opening_hours

選填 陣列<字串>

這個地點的營業時間,以使用者容易理解的文字說明。

PlaceOpeningHoursPeriod

欄位 必填 類型 說明
required PlaceOpeningHoursPeriodDetail

包含一組日期和時間物件,用來描述地點的營業時間。

詳情請參閱 PlaceOpeningHoursPeriodDetail

選填 PlaceOpeningHoursPeriodDetail

可能包含一組日期和時間物件,用來描述地點的休息時間。如果商家全年無休,回覆中就不會顯示「關閉」部分。如果用戶端要表示「全年無休」,可以將開放時間中「星期」的值設為 0、「時間」的值設為 0000,且不含 close

詳情請參閱 PlaceOpeningHoursPeriodDetail

PlaceSpecialDay

欄位 必填 類型 說明
選填 字串

以 RFC3339 格式表示的日期,時區為地點的當地時區,例如 2010-12-31。

選填 布林值

如果當天有特殊營業時間,則為 True。如果 true,表示當天至少有一項例外狀況。例外狀況會導致 current_opening_hourssecondary_opening_hours 的子欄位出現不同值,例如 periodsweekday_textopen_now。例外狀況會套用至營業時間,而營業時間會用於產生其他欄位。

PlaceOpeningHoursPeriodDetail

欄位 必填 類型 說明
required 數字

從 0 到 6 之間的數字,分別代表星期幾 (以週日做為每週起始日)。例如,2 表示週二。

required 字串

可能包含 24 小時 hhmm 格式的時間。值必須介於 0000 到 2359 之間。系統回報的時間是以地點的時區為準。

選填 字串

以 RFC3339 格式表示的日期,時區為地點的當地時區,例如 2010-12-31。

選填 布林值

如果指定時間範圍因七天截斷而遭到截斷,且該時間範圍的開始時間早於要求日期的午夜,和/或結束時間在最後一天的午夜或之後,則為 True。這項屬性表示開放或關閉的期限可超過七天截斷時間。

PlacePhoto

地點的相片。您可以使用 Place Photo API,透過下列模式的網址存取相片:

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=photo_reference&key=YOUR_API_KEY

詳情請參閱「地點相片」。

欄位 必填 類型 說明
required 數字

相片的高度。

required 陣列<字串>

相片的 HTML 出處資訊。

required 字串

執行相片要求時,用來識別相片的字串。

required 數字

相片的寬度。

PlaceReview

使用者提交的地點評論。

欄位 必填 類型 說明
required 字串

提交評論的使用者名稱。匿名評論會歸類為「Google 使用者」。

required 數字

使用者給予這個地點的整體評分。(從 1 到 5 的整數)。

required 字串

以文字形式顯示評論提交時間,相對於目前時間。

required 數字

評論提交時間,以世界標準時間 1970 年 1 月 1 日午夜起算的秒數表示。

選填 字串

使用者 Google 地圖在地嚮導個人資料的網址 (如有)。

選填 字串

IETF 語言代碼,表示傳回評論的語言。這個欄位只包含主要語言標記,不含表示國家/地區或區域的次要標記。舉例來說,所有英文評論都會標示為「en」,而非「en-AU」或「en-UK」等等。如果只有評分而沒有評論文字,這個欄位會是空白。

選填 字串

IETF 語言代碼,指出評論的原文語言。如果評論經過翻譯,則 original_language != language。這個欄位只包含主要語言標記,不含表示國家/地區或區域的次要標記。舉例來說,所有英文評論都會標示為「en」,而非「en-AU」或「en-UK」等等。如果只有評分而沒有評論文字,這個欄位會是空白。

選填 字串

使用者個人資料相片的網址 (如有)。

選填 字串

使用者的評論。在 Google 地點介面集中評論地點時,使用者不一定要填寫文字評論,因此這個欄位可能會空白。請注意,這個欄位可能包含基本 HTML 標記。例如,實體參照 &amp; 可能代表連字號字元。

選填 布林值

布林值,指出評論是否從原始語言翻譯而來。如果評論經過翻譯 (對應的值為 true),Google 建議您向使用者說明這點。舉例來說,您可以在評論中加入「由 Google 翻譯」字串。