Find Place (舊版)

Find Place (舊版) 要求會根據文字輸入內容傳回地點。輸入內容可以是任何類型的地點文字資料，例如名稱、地址或電話號碼。要求必須是字串。如果使用非字串資料 (例如經緯度座標或 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 Main Street」或「City Hall」)。

• 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。「Basic」欄位以基本費率計費，「Contact」和「Atmosphere」欄位則以較高的費率計費。除了觸發要求的基礎 SKU (Place 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

以下範例顯示「Mongolian Grill」的 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，表示下列任一情況：
  • 您已超過 QPS 限制。
  • 您的帳戶未啟用計費功能。
  • 超過每月 $200 美元的抵免額，或自行設定的用量上限。
  • 您提供的付款方式已失效 (例如信用卡已過期)。
  如要進一步瞭解如何解決這項錯誤，請參閱地圖常見問題。
• REQUEST_DENIED：表示您的要求遭拒，通常是因為：
  • 要求缺少 API 金鑰。
  • key 參數無效。
• UNKNOWN_ERROR：表示發生未知錯誤。

地點

Place Search 回應會傳回下列地點欄位子集。並非所有屬性都適用於所有地點類型。如要擷取 Place Search 未傳回的欄位 (例如 address_components、formatted_phone_number、reviews 或 website)，請在 Place Details (舊版) 要求中傳遞傳回的 place_id。如要瞭解各端點的欄位可用性和定價級別，請參閱「地點資料欄位 (舊版)」。