Find Place (舊版)

「透過查詢尋找地點 (舊版)」會根據文字輸入內容傳回地點。輸入內容可以是任何種類的 Places 文字資料，例如名稱、地址或電話號碼。要求必須是字串。使用非字串資料 (例如經緯度座標或 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 號」。這必須是地點名稱、位址或建築物類別。任何其他類型的輸入內容都可能會產生錯誤，不保證會傳回有效的結果。Places API 會根據這個字串傳回候選相符項目，並會依據觀察到的關聯性排序結果。

• inputtype

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

選用參數

• 欄位

  注意：Place Search 要求和 Place Details 要求不會傳回相同的欄位。Place Search 要求會傳回 Place Details 要求傳回的部分欄位。如果 Place Search 沒有傳回所需的欄位，您可以使用 Place Search 取得 place_id，然後使用該地點 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_components、adr_address、 business_status、formatted_address、 geometry、icon、icon_mask_base_uri、 icon_background_color、name、 permanently_closed (已淘汰)、photo、place_id、plus_code、 type、url、utc_offset、 vicinity、wheelchair_accessible_entrance。

  聯絡人

  「Contact」類別包含下列欄位： current_opening_hours、formatted_phone_number international_phone_number、opening_hours secondary_opening_hours、website

  Atmosphere

  「Atmosphere」類別包含下列欄位： curbside_pickup、delivery、dine_in、 editorial_summary、price_level、 rating、reservable、reviews、 serves_beer、serves_breakfast、 serves_brunch、serves_dinner、 serves_lunch、serves_vegetarian_food、 serves_wine、takeout、 user_ratings_total。

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

• language

  傳回結果時使用的語言。

  • 查看支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
  • 如果未提供 language，API 會嘗試使用 Accept-Language 標頭中指定的偏好語言。
  • API 會盡量提供使用者和當地人都能辨識的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要根據偏好語言，將地址音譯為使用者可讀取的文字。所有其他地址都會以偏好語言顯示。地址元件一律會以同一種語言傳回，而該語言是從第一個元件中選擇。
  • 如果偏好語言沒有名稱，API 會使用最接近的名稱。
  • 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言解讀縮寫，例如街道類型縮寫，或在某種語言中有效但在另一種語言中無效的同義字。舉例來說，utca 和 té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 (舊版)」要求，指定的欄位包括 photos、formatted_address、name、rating、opening_hours 和 geometry：

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'

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 -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'

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

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

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'

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 (舊版) 回應

「Find Place (舊版)」回應只會包含使用 fields 參數指定的資料類型，以及 html_attributions。以下範例顯示「澳洲當代藝術博物館」的「Find Place (舊版)」要求的回應，包括 formatted_address、geometry、name、opening_hours、photos 和 rating 欄位。

{
  "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 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

PlacesSearchStatus

服務傳回的狀態碼。

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

地點

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

PlaceEditorialSummary

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

PlaceOpeningHours

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

PlaceOpeningHoursPeriod

PlaceSpecialDay

PlaceOpeningHoursPeriodDetail

PlacePhoto

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

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

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

PlaceReview

使用者提交的地點評論。