本頁面由 Cloud Translation API 翻譯而成。

自動完成 (新推出)

選取平台： Android iOS JavaScript 網頁服務

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

簡介

Autocomplete (新版) 是一項網路服務，可根據 HTTP 要求傳回地點預測和查詢預測結果。在要求中，指定文字搜尋字串和地理範圍，以控管搜尋區域。

「自動完成 (新版)」可比對完整字詞和輸入內容的子字串，解析地點名稱、地址和 Plus Codes。因此，應用程式可在使用者輸入內容時傳送查詢，即時提供地點和查詢預測結果。

Autocomplete (新版) 的回應可能包含兩種預測結果：

地點預測：根據指定的輸入文字字串和搜尋區域，預測地點 (例如商家、地址和搜尋點)。系統預設會傳回地點預測結果。
查詢預測：與輸入文字字串和搜尋區域相符的查詢字串。系統預設不會傳回查詢預測。使用 includeQueryPredictions 要求參數，在回應中加入查詢預測。

舉例來說，您可以使用含有部分使用者輸入內容的字串「Sicilian piz」，並將搜尋範圍限制在加州舊金山，藉此呼叫 Autocomplete (New)。接著，回應會包含符合搜尋字串和搜尋區域的地點預測清單，例如名為「Sicilian Pizza Kitchen」的餐廳，以及該地點的詳細資料。

傳回的地點預測結果會顯示給使用者，協助他們選取所需地點。您可以提出 Place Details (New) 要求，取得任何傳回地點預測結果的詳細資訊。

回應也可能包含符合搜尋字串和搜尋區域的查詢預測清單，例如「西西里披薩和義大利麵」。回應中的每個查詢預測結果都包含 text 欄位，內含建議的文字搜尋字串。將該字串做為 Text Search (新版) 的輸入內容，執行更詳細的搜尋。

您可以使用 APIs Explorer 傳送即時要求，熟悉 API 和 API 選項：

試試看！

自動完成 (新版) 要求

自動完成 (新版) 要求是傳送至以下格式網址的 HTTP POST 要求：

https://places.googleapis.com/v1/places:autocomplete

在 POST 要求中，將所有參數傳遞至 JSON 要求內文或標頭。例如：

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

支援的參數

參數	說明
`input`*	要搜尋的文字字串 (完整字詞、子字串、地點名稱、地址、Plus Codes)。
`FieldMask` (HTTP 標頭)	以逗號分隔的清單，指定要在回應中傳回的欄位。
`includedPrimaryTypes`	限制結果，只顯示符合最多五個指定主要類型的地點。
`includePureServiceAreaBusinesses`	如果為 true，則包含沒有實體店面的商家 (區域服務商家)。預設值為 false。
`includeQueryPredictions`	如果設為 true，回應中會同時包含地點和查詢預測。預設值為 false。
`includedRegionCodes`	最多 15 個雙字元國家/地區代碼的陣列，用於限制結果。
`inputOffset`	游標在輸入字串中的位置 (從零算起)，會影響預測結果。預設為輸入長度。
`languageCode`	搜尋結果的偏好語言 (IETF BCP-47 代碼)。預設值為 Accept-Language 標頭或「en」。
`locationBias`	指定要優先顯示搜尋結果的區域 (圓形或矩形)，允許顯示區域外的結果。無法與 locationRestriction 搭配使用。
`locationRestriction`	指定要限制搜尋結果的區域 (圓形或矩形)。系統會排除這個區域外的結果。無法與 locationBias 搭配使用。
`origin`	用來計算預測目的地直線距離 (distanceMeters) 的原點 (緯度、經度)。
`regionCode`	用於格式化回應和偏向建議的區域代碼 (例如「uk」、「fr」)。
`sessionToken`	使用者產生的字串，可將 Autocomplete 呼叫歸入工作階段，以用於計費。

* 代表必填欄位。

關於回覆

自動完成 (新版) 會以 JSON 物件的形式傳回回應。在回應中：

suggestions 陣列包含所有預測地點和查詢，並根據感知關聯性排序。每個地點都以 placePrediction 欄位表示，每個查詢則以 queryPrediction 欄位表示。
placePrediction 欄位包含單一地點預測的詳細資訊，包括地點 ID 和文字說明。
queryPrediction 欄位包含單一查詢預測的詳細資訊。

注意：自動完成 (新版) 會傳回五項預測結果，視要求而定，可能是 placePredictions、queryPredictions 或兩者組合。如果要求未設定 includeQueryPredictions，回應最多會包含五個 placePredictions。如果要求設定 includeQueryPredictions，回應最多會包含五項預測，組合為 placePredictions 和 queryPredictions。

完整的 JSON 物件格式如下：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

必要參數

輸入

要搜尋的文字字串。指定完整字詞和子字串、地點名稱、地址和 Plus Codes。Autocomplete (New) 服務會根據這個字串傳回候選相符項目，並會依據觀察到的關聯性排序結果。

選用參數

FieldMask

建立回應欄位遮罩，指定要在回應中傳回的欄位清單。使用 HTTP 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至方法。

指定要傳回的建議欄位清單 (以半形逗號分隔)。舉例來說，如要擷取建議的 suggestions.placePrediction.text.text 和 suggestions.queryPrediction.text.text。
```
  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
```
注意： 欄位清單中不得有任何空格。

使用 * 擷取所有欄位。
```
  X-Goog-FieldMask: *
```
includedPrimaryTypes

一個地點只能有一個主要類型，且必須是表 A 或表 B 中列出的類型。舉例來說，主要類型可能是 "mexican_restaurant" 或 "steak_house"。

根據預設，API 會根據 input 參數傳回所有地點，無論與地點相關聯的主要類型值為何。傳遞 includedPrimaryTypes 參數，將結果限制為特定主要類型或主要類型。

使用這個參數，從表 A 或表 B 指定最多五個類型值。地點必須符合其中一個指定的主要類型值，才會納入回應。

這個參數也可以改為包含 (regions) 或 (cities)。(regions) 類型集合會篩選區域或分區，例如鄰里和郵遞區號。(cities) 類型集合會篩選出 Google 判斷為城市的地點。

如有下列情況，要求就會遭拒，並傳回 INVALID_REQUEST 錯誤：
- 指定超過五個類型。
- 除了 (cities) 或 (regions) 之外，還指定了任何型別。
- 指定任何無法辨識的類型。
注意：includedPrimaryTypes 參數只適用於地點的主要類型，不適用於與地點相關聯的所有類型。雖然每個地點都有主要類型，但 Places API (新版) 並非支援所有主要類型。支援的類型包括表 A 或表 B 中列出的類型。
includePureServiceAreaBusinesses

如果設為 true，回應會包含直接為顧客提供送貨或到府服務，但沒有實體店面的商家。如果設為 false，API 只會傳回有實體營業場所的商家。
includeQueryPredictions

如果是 true，回應會同時包含地點和查詢預測。預設值為 false，表示回應只會包含地點預測。
includedRegionCodes

只納入指定區域清單中的結果，指定方式為最多 15 個國家/地區代碼頂層網域 (ccTLD) 的兩位字元值陣列。如果省略，系統不會對回覆套用任何限制。舉例來說，如要將地區限制為德國和法國，請執行下列操作：
```
    "includedRegionCodes": ["de", "fr"]
```
如果同時指定 locationRestriction 和 includedRegionCodes，結果會位於這兩項設定的交集區域。

注意：如果使用國家/地區代碼時收到非預期的結果，請確認您使用的代碼是否包含所需的國家/地區、附屬領土和特殊地理區域。如要取得代碼相關資訊，您可以查看維基百科的 ISO 3166 國家/地區代碼清單或 ISO 線上瀏覽平台。
inputOffset

以零為基準的 Unicode 字元位移值，表示 input 中的游標位置。游標位置可能會影響系統傳回的預測結果。如果為空白，預設值為 input 的長度。

注意： 在初始的受限搶先體驗版中，這項屬性稱為 predictionTermOffset。
languageCode

傳回結果時偏好的語言。如果 input 中使用的語言與 languageCode 指定的值不同，或者傳回的地點沒有從當地語言到 languageCode 的翻譯，結果可能會以混合語言顯示。
- 您必須使用 IETF BCP-47 語言代碼指定偏好的語言。
- 如未提供 languageCode，API 會使用 Accept-Language 標頭中指定的值。如未指定，則預設值為 en。如果指定無效的語言代碼，API 會傳回 INVALID_ARGUMENT 錯誤。
- 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。這也會影響 API 修正拼字錯誤的能力。
- API 會嘗試提供使用者和當地居民都能解讀的街道地址，同時反映使用者輸入內容。地點預測的格式會因每個要求中的使用者輸入內容而異。
  - 系統會先選擇 input 參數中的相符字詞，並使用與 languageCode 參數所指出語言偏好設定一致的名稱 (如有)，否則會使用最符合使用者輸入內容的名稱。
  - 如果可以，系統會以使用者可讀的文字，用當地語言格式化街道地址，但前提是必須先選取相符的字詞，與 input 參數中的字詞相符。
  - 選取與 input 參數中的字詞相符的字詞後，系統會以偏好語言傳回所有其他地址。如果偏好語言沒有名稱，API 會使用最接近的名稱。
locationBias 或 locationRestriction

您可以指定 locationBias 或 locationRestriction (但不能同時指定兩者)，定義搜尋範圍。您可以將 locationRestriction 視為指定結果必須位於的區域，而 locationBias 則是指定結果必須靠近的區域，但可以超出該區域。

注意： 如果您同時省略 locationBias 和 locationRestriction，Autocomplete (New) 預設會使用 IP 偏誤。使用 IP 偏誤時，自動完成 (新版) 會根據裝置的 IP 位址調整結果。
- locationBias
  
  指定要搜尋的區域。這個位置會做為偏誤，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。
- locationRestriction
  
  指定要搜尋的區域。系統不會傳回指定區域外的結果。
將 locationBias 或 locationRestriction 區域指定為矩形檢視區塊或圓形。
- 圓形是由中心點和半徑 (以公尺為單位) 所定義。半徑必須介於 0.0 至 50000.0 之間 (含首尾)。預設值為 0.0。如果是 locationRestriction，半徑必須設為大於 0.0 的值。否則要求不會傳回任何結果。
  
  例如：
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- 矩形是經緯度可視區域，以兩個對角線相對的 low 和高點表示。可視區域視為封閉區域，因此包含邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾)，經度範圍則必須介於 -180 到 180 度之間 (含首尾)：
  - 如果 low = high，可視區域就是該單一點。
  - 如果 low.longitude > high.longitude，經度範圍會反轉 (可視區域會跨越 180 度經度線)。
  - 如果 low.longitude = -180 度且 high.longitude = 180 度，可視區域會包含所有經度。
  - 如果 low.longitude = 180 度且 high.longitude = -180 度，經度範圍會空白。
  low 和 high 都必須填入值，且代表的方塊不得為空。如果檢視區塊為空白，就會發生錯誤。
  
  舉例來說，這個可視區域完全涵蓋紐約市：
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
origin

計算與目的地直線距離的起點 (以 distanceMeters 形式傳回)。如果省略這個值，系統就不會傳回直線距離。必須指定為經緯度座標：
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

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

建議也會因區域代碼而有所偏差。Google 建議根據使用者的區域偏好設定 regionCode。

如果指定無效的地區代碼，API 會傳回 INVALID_ARGUMENT 錯誤。視適用法律而定，這項參數可能會影響結果。
sessionToken

工作階段符記是使用者產生的字串，可將 Autocomplete (New) 呼叫追蹤為「工作階段」。自動完成 (新版) 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。詳情請參閱「工作階段符記」。

選擇要影響結果的參數

自動完成 (新版) 參數可能會以不同方式影響搜尋結果。下表根據預期結果，提供參數使用建議。

參數	使用建議
`regionCode`	根據使用者的地區偏好設定。
`includedRegionCodes`	設定為將結果限制在指定區域清單中。
`locationBias`	如果希望結果位於特定區域或附近，請使用這項功能。如適用，請將區域定義為使用者查看的地圖可視區域。
`locationRestriction`	只有在不應傳回區域外的結果時，才使用。
`origin`	如要計算每個預測結果的直線距離，請使用這個函式。注意：並非所有預測結果都會顯示距離。請參閱回應中缺少距離。�

Autocomplete (新版) 範例

使用 locationRestriction 將搜尋範圍限制在特定區域

注意：自動完成 (新版) 預設會使用 IP 調整設定來控管搜尋區域。啟用 IP 偏誤後，自動完成 (新版) 會使用裝置的 IP 位址來偏誤結果。您可以選擇使用 locationRestriction 或 locationBias (但不能同時使用)，指定要搜尋的區域。

locationRestriction 會指定要搜尋的區域。系統不會傳回指定區域外的結果。在下列範例中，您可以使用 locationRestriction 將要求限制為以舊金山為中心，半徑 5000 公尺的圓形：

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

指定區域內的所有結果都會包含在 suggestions 陣列中：

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

您也可以使用 locationRestriction，將搜尋範圍限制在矩形可視區域。以下範例會將要求限制在舊金山市區：

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

結果會包含在 suggestions 陣列中：

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

使用 locationBias 將搜尋結果自訂調整為僅限某個區域

使用 locationBias 時，位置資訊會做為自訂調整，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。在下列範例中，您會將要求偏向舊金山市區：

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

現在的結果包含更多項目，包括 5000 公尺半徑以外的結果：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

您也可以使用 locationBias，將搜尋結果偏向矩形檢視區塊。以下範例會將要求限制在舊金山市區：

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

雖然回應中會顯示矩形可視區域內的搜尋結果，但由於偏誤，部分結果會超出定義的邊界。結果也會包含在 suggestions 陣列中：

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

使用 includedPrimaryTypes

使用 includedPrimaryTypes 參數，從表 A、表 B 或僅限 (regions) 或 (cities) 指定最多五個類型值。地點必須符合其中一個指定的主要類型值，才會納入回應。

在下列範例中，您指定「Soccer」的 input 字串，並使用 includedPrimaryTypes 參數將結果限制為 "sporting_goods_store" 類型的場所：

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

如果省略 includedPrimaryTypes 參數，結果可能會包含您不想要的類型的場所，例如 "athletic_field"。

要求查詢預測

系統預設不會傳回查詢預測。使用 includeQueryPredictions 要求參數，在回應中加入查詢預測。例如：

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

如「關於回應」一節所示，suggestions 陣列現在同時包含地點預測和查詢預測。每項查詢預測都包含 text 欄位，內含建議的文字搜尋字串。您可以提出 Text Search (New) 要求，進一步瞭解傳回的任何查詢預測。

注意：設定 includedRegionCodes 參數時，系統不會傳回查詢預測。

使用來源

在本範例中，請在要求中加入 origin 做為經緯度座標。加入 origin 後，Autocomplete (New) 會在回應中加入 distanceMeters 欄位，其中包含從 origin 到目的地的直線距離。這個範例將原點設為舊金山中心：

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

回應現在包含 distanceMeters：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

回覆中缺少距離

在某些情況下，即使要求中包含 origin，回應主體中仍會缺少 distanceMeters。可能發生這種情況的情境如下：

distanceMeters不會納入route預測。
如果值為 0，系統就不會納入 distanceMeters。如果預測位置與提供的 origin 位置相距不到 1 公尺，就會發生這種情況。

用戶端程式庫嘗試從剖析的物件讀取 distanceMeters 欄位時，會傳回值為 0 的欄位。為避免誤導使用者，請不要向使用者顯示零距離。

試試看！

您可以使用 APIs Explorer 提出範例要求，熟悉 API 和 API 選項。

選取頁面右側的 API 圖示 api。
視需要編輯要求參數。
選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen 即可展開 APIs Explorer 視窗。

自動完成 (新推出) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

簡介

自動完成 (新版) 要求

支援的參數

關於回覆

必要參數

輸入

選用參數

FieldMask

includedPrimaryTypes

includePureServiceAreaBusinesses

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 或 locationRestriction

locationBias

locationRestriction

origin

regionCode

sessionToken

選擇要影響結果的參數

Autocomplete (新版) 範例

使用 locationRestriction 將搜尋範圍限制在特定區域

使用 locationBias 將搜尋結果自訂調整為僅限某個區域

使用 includedPrimaryTypes

要求查詢預測

使用來源

回覆中缺少距離

試試看！

自動完成 (新推出)