Text Search (舊版)

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

Text Search (舊版) 可根據字串 (例如「台南魯肉飯」、「西門町附近的鞋店」或「中正路 123 號」)，傳回一組地點的相關資訊。這項服務會傳回與文字字串及位置自訂調整設定相符的地點清單。

Text Search (舊版) 不適用於模糊查詢，包括：

查詢類型 範例
概念或限制過多，例如在單一查詢中輸入多個地點、道路或城市名稱 "Market Street San Francisco San Jose Airport"
Google 地圖未顯示郵寄地址元素 "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
商家、連鎖店或類別名稱，加上這些實體不存在的地點 「德州達拉斯附近的 Tesco」
有多種解讀方式的模糊查詢 「交寄充電器」
不再使用的歷史名稱 "Middlesex United Kingdom"
非地理空間元素或意圖 「文圖拉港有多少艘船？」
非官方或自訂名稱 「疊疊樂」
「螺旋滑梯」
經緯度座標 "37.422131,-122.084801"

搜尋回應會包含一份地點清單。您可以傳送 Place Details 要求，索取回應中任何地點的詳細資訊。

Text Search (舊版) 要求

Text Search (舊版) 要求是採用下列格式的 HTTP 網址：

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

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

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

您必須加入某些參數，才能提出搜尋要求。依照網址標準，所有參數都會以 & 字元分隔。

必要參數

  • 查詢

    要搜尋的文字字串，例如「餐廳」或「中正路 123 號」。這必須是地點名稱、地址或建築物類別。任何其他類型的輸入內容都可能會產生錯誤，不保證會傳回有效的結果。Google Places 服務會根據這個字串傳回候選相符項目，並會依據觀察到的關聯性排序結果。

  • 半徑

    定義傳回地點結果的距離 (以公尺為單位)。您可以傳送 location 和 radius 參數，針對特定圓形範圍調整結果。這樣就能指示 Places 服務「優先」顯示該圓形範圍內的結果，但系統還是有可能會顯示定義區域外的結果。

    系統會根據搜尋類型和其他參數，自動將半徑限制在最大值。

    • 自動完成：50,000 公尺
    • Nearby Search：
      • keyword 或 name：50,000 公尺
      • 不含 keyword 或 name
        • 上限為 50,000 公尺，會根據區域密度動態調整，不受 rankby 參數影響。
        • 使用 rankby=distance 時，系統不會接受半徑參數，並會產生 INVALID_REQUEST。
    • Query Autocomplete：50,000 公尺
    • Text Search：50,000 公尺

選用參數

  • language

    傳回結果時使用的語言。

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

  • 位置

    要擷取地點資訊的中心點。必須指定為 latitude,longitude。

    如果 query 包含明確位置 (例如 Market in Barcelona)，系統可能會覆寫 location 參數。在查詢前後加上引號，也可能會影響 location 和 radius 的權重。

  • maxprice

    限制系統只傳回指定範圍內的結果。有效值介於 0 (最便宜) 和 4 (最昂貴)，含首尾兩值。特定值代表的確切金額會因地區而異。

  • minprice

    限制系統只傳回指定範圍內的結果。有效值介於 0 (最便宜) 和 4 (最昂貴)，含首尾兩值。特定值代表的確切金額會因地區而異。

  • opennow

    僅傳回在查詢當下營業中的地點。如果您在查詢中加入這個參數，系統就不會傳回未於 Google 地點資料庫中指定營業時間的地點。

  • pagetoken

    傳回先前執行的搜尋結果，最多 20 筆。設定 pagetoken 參數後，系統會使用先前使用的相同參數執行搜尋，並忽略 pagetoken 以外的所有參數。

  • 區域

    區碼，指定為 ccTLD (「頂層網域」) 雙字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼則是「gb」(技術上代表「大不列顛暨北愛爾蘭聯合王國」)。

  • 類型

    讓系統在結果中只顯示符合指定類型的地點。只能指定一種。如果提供多種類型，系統會忽略第一種類型之後輸入的所有類型。

    • type=hospital|pharmacy|doctor 變成 type=hospital
    • 完全忽略 type=hospital,pharmacy,doctor

    請參閱支援類型清單。

    注意：如果同時新增 keyword 和 type，且兩者具有相同的值 (keyword=cafe&type=cafe 或 keyword=parking&type=parking)，可能會產生 ZERO_RESULTS。

Text Search (舊版) 範例

注意：在這些範例中，您需要將 key 替換成自己的 API 金鑰，要求才能在應用程式中運作。

基本範例

以下範例顯示搜尋雪梨附近的餐廳。

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/textsearch/json?query=restaurants%20in%20Sydney&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/textsearch/json
  ?query=restaurants%20in%20Sydney
  &key=YOUR_API_KEY

地址不完整的範例

以下範例顯示搜尋不完整地址 (此例中為不含城市、州/省或國家/地區的街道地址) 的結果。

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/textsearch/json?query=123%20main%20street&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/textsearch/json
  ?query=123%20main%20street
  &key=YOUR_API_KEY

JSON

{
  "html_attributions": [],
  "results":
    [
      {
        "formatted_address": "Main St, Denver, CO 80238, USA",
        "geometry":
          {
            "location": { "lat": 39.782267, "lng": -104.8919341 },
            "viewport":
              {
                "northeast":
                  { "lat": 39.78361682989273, "lng": -104.8905842701073 },
                "southwest":
                  { "lat": 39.78091717010729, "lng": -104.8932839298927 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/geocode-71.png",
        "icon_background_color": "#7B9EB0",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet",
        "name": "Main St",
        "place_id": "ChIJIS85_gd7bIcRJIGEPue1cJI",
        "reference": "ChIJIS85_gd7bIcRJIGEPue1cJI",
        "types": ["route"],
      },
    ],
  "status": "OK",
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Main St</name>
  <type>route</type>
  <formatted_address>Main St, Denver, CO 80238, USA</formatted_address>
  <geometry>
   <location>
    <lat>39.7822670</lat>
    <lng>-104.8919341</lng>
   </location>
   <viewport>
    <southwest>
     <lat>39.7809172</lat>
     <lng>-104.8932839</lng>
    </southwest>
    <northeast>
     <lat>39.7836168</lat>
     <lng>-104.8905843</lng>
    </northeast>
   </viewport>
  </geometry>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/geocode-71.png</icon>
  <reference>ChIJIS85_gd7bIcRJIGEPue1cJI</reference>
  <place_id>ChIJIS85_gd7bIcRJIGEPue1cJI</place_id>
  <icon_background_color>#7B9EB0</icon_background_color>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri>
 </result>
</PlaceSearchResponse>

位置偏誤範例

以下範例顯示搜尋前例中相同的不完整地址，並包含 location 和 radius 參數，將結果偏向感興趣的區域。

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/textsearch/json?query=123%20main%20street&location=42.3675294%2C-71.186966&radius=10000&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/textsearch/json
  ?location=42.3675294%2C-71.186966
  &query=123%20main%20street
  &radius=10000
  &key=YOUR_API_KEY

JSON

{
  "html_attributions": [],
  "results":
    [
      {
        "formatted_address": "123 Main St, Boston, MA 02110, USA",
        "geometry":
          {
            "location": { "lat": 42.3744917, "lng": -71.0634802 },
            "viewport":
              {
                "northeast":
                  { "lat": 42.37581642989272, "lng": -71.06219107010727 },
                "southwest":
                  { "lat": 42.37311677010727, "lng": -71.06489072989272 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/geocode-71.png",
        "icon_background_color": "#7B9EB0",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet",
        "name": "123 Main St",
        "place_id": "ChIJd_ueCe1w44kRD_KFuN5w5nA",
        "plus_code":
          {
            "compound_code": "9WFP+QJ Boston, Massachusetts",
            "global_code": "87JC9WFP+QJ",
          },
        "reference": "ChIJd_ueCe1w44kRD_KFuN5w5nA",
        "types": ["street_address"],
      },
    ],
  "status": "OK",
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>123 Main St</name>
  <type>street_address</type>
  <formatted_address>123 Main St, Boston, MA 02110, USA</formatted_address>
  <geometry>
   <location>
    <lat>42.3744917</lat>
    <lng>-71.0634802</lng>
   </location>
   <viewport>
    <southwest>
     <lat>42.3731168</lat>
     <lng>-71.0648907</lng>
    </southwest>
    <northeast>
     <lat>42.3758164</lat>
     <lng>-71.0621911</lng>
    </northeast>
   </viewport>
  </geometry>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/geocode-71.png</icon>
  <reference>ChIJd_ueCe1w44kRD_KFuN5w5nA</reference>
  <place_id>ChIJd_ueCe1w44kRD_KFuN5w5nA</place_id>
  <plus_code>
   <global_code>87JC9WFP+QJ</global_code>
   <compound_code>9WFP+QJ Boston, Massachusetts</compound_code>
  </plus_code>
  <icon_background_color>#7B9EB0</icon_background_color>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri>
 </result>
</PlaceSearchResponse>

Text Search (舊版) 回應

搜尋回應會以網址要求路徑中 output 旗標指定的格式傳回。

以下範例顯示 Text Search (舊版) 回應。

JSON

{
  "html_attributions": [],
  "next_page_token": "Aap_uEAHsgFErpxZrytW1mgKsefD327VCf0OgNF9vpXPwTOG6AGhEZpGgMgofSzgCahevXhneCe9M9H24SOuE4ZcaE0ZR01gVykQZ6EoDnlWEQvXBXe6z0sgF5MQo7qBb6uD4VHKDLhgR59Lb86BzTHJzTzbm61OAPvyInZoaQxK8-oEf2PShZT7XRJKoF5nISbwvU_-RomwGDVi27oj0fToIyV-Vj2ftJw8ZUPbdGGCbcDolQyAwj11Dy2aaeK4SGwg2mO5Akxa7fCze2RJ0GCAvXXp7omTFDy_47OXsFgDPfzluc7mEb5VlzlIMZ0eWQ8VeNigtv-XZZG0f3HSo81Yeq3QhXedJ5oNE1XCwyMly3YVgw_h3amOzAOuDigF1pgFnfGyzxD8vr2bfbPTNvA9l7IJ8Q",
  "results":
    [
      {
        "business_status": "OPERATIONAL",
        "formatted_address": "1 Macquarie St, Sydney NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8592041, "lng": 151.2132635 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85786707010728, "lng": 151.2147093298927 },
                "southwest":
                  { "lat": -33.86056672989272, "lng": 151.2120096701072 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/restaurant-71.png",
        "icon_background_color": "#FF9E67",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/restaurant_pinlet",
        "name": "Aria Restaurant Sydney",
        "opening_hours": { "open_now": false },
        "photos":
          [
            {
              "height": 4032,
              "html_attributions":
                [
                  'Dohyun Kim',
                ],
              "photo_reference": "Aap_uED7B83PoQ1wNgzYcFZEOw1P2DqNjlaqiXxo-r4F_NaR27uV2OiIvijkI6RYyfiiHYo9UqjnZkRtZaNTk4C6Ickh3k3stsSvBU0KfLtFow-oRujSYYChYwiYhVyP27omLzQQjafhJ2N3LJbjcMxSePKXsQzYCqmOLWg0E9mSExMJ4aM",
              "width": 3024,
            },
          ],
        "place_id": "ChIJdxxU1WeuEmsR11c4fswX-Io",
        "plus_code":
          {
            "compound_code": "46R7+88 Sydney, New South Wales, Australia",
            "global_code": "4RRH46R7+88",
          },
        "price_level": 4,
        "rating": 4.5,
        "reference": "ChIJdxxU1WeuEmsR11c4fswX-Io",
        "types": ["restaurant", "point_of_interest", "food", "establishment"],
        "user_ratings_total": 1681,
      },
      {
        "business_status": "OPERATIONAL",
        "formatted_address": "15 Bligh St, Sydney NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8651396, "lng": 151.2104533 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.86384167010728, "lng": 151.2118993298927 },
                "southwest":
                  { "lat": -33.86654132989272, "lng": 151.2091996701073 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/restaurant-71.png",
        "icon_background_color": "#FF9E67",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/restaurant_pinlet",
        "name": "Restaurant Hubert",
        "opening_hours": { "open_now": false },
        "photos":
          [
            {
              "height": 683,
              "html_attributions":
                [
                  'Ashley Hughes',
                ],
              "photo_reference": "Aap_uEB41WOb_Nl8I8py4D6uXoLHzVYtFZZcucYdYAN1FtzXBnAu59xXrxk5tekoktAbklwmHeSFfdnTCWgHRZ1C5Azp9AMCP9GRGV1f2Z1-5kjsVgnYPiq82JoueSUdCSQJFabyL0cagtcGaFKetVi7DmUIHDQknEPCh_cpCbdOMw4Bkq5q",
              "width": 1024,
            },
          ],
        "place_id": "ChIJF5-RdGquEmsR5rN_H74uSqQ",
        "plus_code":
          {
            "compound_code": "46M6+W5 Sydney, New South Wales, Australia",
            "global_code": "4RRH46M6+W5",
          },
        "price_level": 3,
        "rating": 4.6,
        "reference": "ChIJF5-RdGquEmsR5rN_H74uSqQ",
        "types": ["restaurant", "point_of_interest", "food", "establishment"],
        "user_ratings_total": 2393,
      },
      // ...
    ],
  "status": "OK",
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Aria Restaurant Sydney</name>
  <type>restaurant</type>
  <type>point_of_interest</type>
  <type>food</type>
  <type>establishment</type>
  <formatted_address>1 Macquarie St, Sydney NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8592041</lat>
    <lng>151.2132635</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8605667</lat>
     <lng>151.2120097</lng>
    </southwest>
    <northeast>
     <lat>-33.8578671</lat>
     <lng>151.2147093</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.5</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/restaurant-71.png</icon>
  <reference>ChIJdxxU1WeuEmsR11c4fswX-Io</reference>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEDOK3C-umU4a2um8NR1G_b_MNPEG1ogm0PLp49myXaj0AD2aT60YrNlbrwnvg2VBrCmE2kBsuDmwZgXL8V-vU2ToVhNgp3A8zAjtx15slWyCxm3WCvWFEPE-_eBoj0Dlh83k_oWPN65B0blYM-qXLBY1PJZbq14gOUXabf31PSo1yA</photo_reference>
   <width>3024</width>
   <height>4032</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/112033760018394328606&quot;&gt;Dohyun Kim&lt;/a&gt;</html_attribution>
  </photo>
  <price_level>4</price_level>
  <user_ratings_total>1681</user_ratings_total>
  <place_id>ChIJdxxU1WeuEmsR11c4fswX-Io</place_id>
  <plus_code>
   <global_code>4RRH46R7+88</global_code>
   <compound_code>46R7+88 Sydney, New South Wales, Australia</compound_code>
  </plus_code>
  <icon_background_color>#FF9E67</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/restaurant_pinlet</icon_mask_base_uri>
 </result>
 <result>
  <name>Restaurant Hubert</name>
  <type>restaurant</type>
  <type>point_of_interest</type>
  <type>food</type>
  <type>establishment</type>
  <formatted_address>15 Bligh St, Sydney NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8651396</lat>
    <lng>151.2104533</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8665413</lat>
     <lng>151.2091997</lng>
    </southwest>
    <northeast>
     <lat>-33.8638417</lat>
     <lng>151.2118993</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.6</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/restaurant-71.png</icon>
  <reference>ChIJF5-RdGquEmsR5rN_H74uSqQ</reference>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEDhALUBAcrBEprGmkq0_kj9kC4IEWod9h0PZBu-A1mXPN_ZfylpiDXRWxOtuONEFQIqjREf7C28LQDjzqVl4ZD0gZUk4Y0JHPDWaTlfVwijaPfw221p175Sk4po7rB2t7HgjQF2c5O12FYnvNzRiCrkOjr4xroJgzcnp1LV0y8w7gtb</photo_reference>
   <width>1024</width>
   <height>683</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/113719639442868633401&quot;&gt;Ashley Hughes&lt;/a&gt;</html_attribution>
  </photo>
  <price_level>3</price_level>
  <user_ratings_total>2393</user_ratings_total>
  <place_id>ChIJF5-RdGquEmsR5rN_H74uSqQ</place_id>
  <plus_code>
   <global_code>4RRH46M6+W5</global_code>
   <compound_code>46M6+W5 Sydney, New South Wales, Australia</compound_code>
  </plus_code>
  <icon_background_color>#FF9E67</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/restaurant_pinlet</icon_mask_base_uri>
 </result>
 <!-- ... -->
 <next_page_token>Aap_uEC8n0Fzu2WsA7IqaEJty09klsnvXEYZe0aL8dIiZx3fOOfo1xYHZR00qrq-obJbYY9YRkftL-Pv__rQ-efJHSxv19gDtol2ARoY9wpi0ENg-vUAkDVt2W0mOqDy4Kjz9rm5-tzk6fhKR6r4wbLkdgXbKLuNM7KEhsjspU0RC5jQZa4FK_cM9qeUPx5IkPdAa11b9EJwKPEy-ixe77eXeRbEzDYhC5rhylkoOGbF1mHVJVxr--u-Ihe0YaFogaWDx50BcCcMN-eDetaUBJwXDnzHxtirIRF5C_yFavCzWcFn5TOC_z9Ltc-U0L5zbv3lQ7Z6kfVuOeKp4u5_lEHwfz-LuHyETKE6QwQypJUPS3AS8BFs2pYm9r_ruao6YVYsFfDGs1-9QPsVUeSjCN3NuRvbkA</next_page_token>
</PlaceSearchResponse>

PlacesTextSearchResponse

欄位 必填 類型 說明
required Array<string>

可能包含一組關於此清單的屬性，必須向使用者顯示 (部分清單可能沒有屬性)。

required Array<Place>

包含地點陣列。

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

詳情請參閱「Place」。
required PlacesSearchStatus

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

詳情請參閱 PlacesSearchStatus。

選填 字串

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

選填 Array<string>

如果服務傳回要求規格的其他資訊，回應物件中可能會有額外的 info_messages 欄位。只有成功的要求才會傳回這個欄位。系統不一定會傳回這項資訊，且內容可能會有變動。

next_page_token

選填 字串

包含可用來傳回最多 20 筆額外結果的權杖。如果沒有其他結果可顯示，系統就不會傳回 next_page_token。可傳回的結果數量上限為 60。next_page_token 發出後，要過一小段時間才會生效。

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。如要瞭解各端點的欄位可用性和定價級別，請參閱「地點資料欄位 (舊版)」。

欄位 類型 說明
business_status string 表示地點的營業狀態 (如果地點為商家)：OPERATIONAL、CLOSED_TEMPORARILY 或 CLOSED_PERMANENTLY。如果沒有狀態資料，則會省略。
formatted_address string 這個地點的人類可讀地址。由 Text Search (舊版) 和 Find Place (舊版) 傳回。請勿以程式輔助方式剖析格式化地址，而應在 Place Details (舊版) 中要求 address_components。
geometry Geometry 包含經過地理編碼的 location (含 lat 和 lng 座標)，以及偏好的 viewport (含 northeast 和 southwest 邊界)。
icon string 建議圖示的網址，可在地圖上標示這項結果時顯示。
icon_background_color string 地點類別的預設十六進位顏色代碼。
icon_mask_base_uri string 建議圖示的基準網址，不含 SVG 或 PNG 檔案類型副檔名。
name string 傳回結果的人類可讀名稱。如果是 establishment 結果，這個值通常是標準化商家名稱。
opening_hours PlaceOpeningHours 營業時間資訊。Place Search 端點只會傳回 open_now 布林值子欄位；如要取得 periods 和 weekday_text，請在 Place Details (舊版) 中要求 opening_hours。
permanently_closed boolean 已淘汰：請使用 business_status 查看商家的營業狀態。
photos Array<PlacePhoto> PlacePhoto 物件陣列，每個物件都包含 photo_reference、height、width 和 html_attributions。如需使用詳情，請參閱「Place Photos (舊版)」。
place_id string 用來識別特定地點的文字 ID。請在 Place Details (舊版) 要求的 place_id 參數中傳遞這個 ID。請參閱地點 ID 總覽。
plus_code PlusCode 衍生自經緯度座標的編碼位置參照，包含 global_code 和選用的 compound_code。
price_level integer 地點的價格等級，範圍從 0 到 4，由最便宜到最昂貴。詳情請參閱 price_level。
rating number 地點評分 (1.0 到 5.0，根據綜合使用者評論計算)。
reference string 已淘汰：請改用 place_id。
scope string 已淘汰：表示 place_id 的範圍，一律為 GOOGLE。由 Nearby Search (舊版) 傳回。
types Array<string> 描述指定結果的特徵類型陣列。請參閱「地點類型 (舊版)」。
user_ratings_total integer 這個地點的評分總數 (無論是否包含評論文字)。
vicinity string 地點的簡化地址，包括街道名稱、門牌號碼和縣市，但不含州/省、郵遞區號或國家/地區。由 Nearby Search (舊版) 傳回。

取得其他結果

根據預設，每次查詢最多會傳回 20 筆establishment結果，但每次搜尋最多可傳回 60 筆結果，並分成三個頁面顯示。如果搜尋結果超過 20 個，搜尋回應會包含額外的值：next_page_token。將 next_page_token 的值傳遞至新要求的 pagetoken 參數，即可查看下一組結果。

  • 如果 next_page_token 為空值或未傳回，表示沒有其他結果。
  • 使用相同的 next_page_token 重試要求，即可傳回下一頁結果。
  • 設定 pagetoken 會導致系統忽略任何其他參數。
  • 在原始查詢後，最多可以要求兩次新頁面。
  • 每項要求 (包括使用 next_page_token 的要求) 都會計為用量限制中的一次要求，並單獨收費。
  • next_page_token 發出後，需要幾秒才會生效。如果在下一頁可用之前要求，系統會傳回 INVALID_REQUEST 回應。系統一律會針對含有 next_page_token 的要求收費。

舉例來說，在下方查詢中，我們搜尋澳洲雪梨達令港附近的餐廳，並依距離排序結果。您會看到回應包含 next_page_token 屬性。

{
   "html_attributions" : [],
   "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
   "results" : [...]
   "status" : "OK"
}

如要查看下一組結果，您可以提交新查詢，將 next_page_token 的結果傳遞至 pagetoken 參數。例如：

https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY