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

自動完成 (新推出)

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

Autocomplete (新版) 服務是一種網路服務，可依據 HTTP 要求傳回地點預測和查詢預測結果。在要求中，指定用來控制搜尋區域的文字搜尋字串和地理邊界。

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

Autocomplete (New) API 的回應可包含兩種預測結果：

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

舉例來說，您可以使用做為輸入字串來呼叫 API，該字串內含部分的使用者輸入內容「Sicilian piz」，且搜尋區域僅限於加州舊金山。回應隨後會包含一份與搜尋字串和搜尋區域相符的地點預測結果清單 (例如名為「西西里披薩廚房」的餐廳)，以及該地點的詳細資料。

傳回的地點預測結果旨在協助使用者選取所需地點。您可以提出 Place Details (新版) 要求，取得任何傳回地點預測結果的詳細資訊。

回應也可以包含與搜尋字串和搜尋區域相符的查詢預測清單，例如「Sicilian Pizza & Pasta」。回應中的每項查詢預測結果都會包含 text 欄位，其中包含建議的文字搜尋字串。使用該字串做為 Text Search (New) 的輸入內容，執行更詳細的搜尋作業。

API Explorer 可讓您發出即時要求，以便熟悉這個 API 和 API 選項：

試試看！

自動完成 (新版) 要求

Autocomplete (新版) 要求是對網址的 HTTP POST 要求，格式如下：

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

將 JSON 要求主體或標頭中的所有參數做為 POST 要求的一部分傳遞。例如：

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

關於回覆

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 (新版) 服務會根據這個字串傳回候選相符項目，並會依據觀察到的關聯性排序結果。

自選參數

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 中列出的類型。
includeQueryPredictions

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

僅包含指定區域清單的結果，且指定為最多 15 個 ccTLD (「頂層網域」) 雙字元值的陣列。如果省略，則系統不會對回應套用任何限制。舉例來說，如要將區域範圍限制在德國和法國，請按照下列步驟操作：
```
    "includedRegionCodes": ["de", "fr"]
```
如果您同時指定 locationRestriction 和 includedRegionCodes，結果會在這兩個設定的交集區域內。
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，API 預設會使用 IP 自訂調整。透過 IP 自訂調整功能，API 會使用裝置的 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
    }
  }
}
```
發跡地

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

用於設定回應格式的區碼，以 ccTLD (「頂層網域」) 的兩位字元值指定。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，只有少數例外。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而其 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。

如果指定的區碼無效，API 會傳回 INVALID_ARGUMENT 錯誤。這個參數會根據適用法律影響結果。
sessionToken

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

自動完成 (新版) 範例

使用 locationRestriction 和 locationBias

根據預設，API 會使用 IP 自訂調整來控制搜尋區域。透過 IP 自訂調整，API 會使用裝置的 IP 位址來自訂調整結果。您可以選擇使用 locationRestriction 或 locationBias，但不能同時使用兩者，指定要搜尋的區域。

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

curl -X POST -d '{
  "input": "Amoeba",
  "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/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",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

使用 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"
        ]
      }
    },
    ...
  ]
}

使用 includePrimaryTypes

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

在以下範例中，您會指定「足球」的 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 (新版) 要求以取得任何傳回查詢預測的詳細資訊。

注意：如果已設定 includedRegionCodes 參數，則不會傳回查詢預測結果。

使用來源

在這個範例中，請將 origin 做為經緯度座標在要求中加入。加入 origin 後，API 會在回應中加入 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
      }
    }
  ]
}

試試看！

API Explorer 可讓您提出要求範例，以便熟悉 API 和 API 選項。

選取頁面右側的 API 圖示。
視需要展開「Show Standard parameters」，然後將 fields 參數設為欄位遮罩。
視需要編輯「要求主體」。
選取「執行」按鈕。在彈出式視窗中，選擇要用來提出請求的帳戶。
在「API Explorer」面板中選取展開圖示，展開「API Explorer」視窗。

自動完成 (新推出)

自動完成 (新版) 要求

關於回覆

必要參數

輸入

自選參數

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 或 locationRestriction

locationBias

locationRestriction

發跡地

regionCode

sessionToken

自動完成 (新版) 範例

使用 locationRestriction 和 locationBias

使用 includePrimaryTypes

要求查詢預測

使用來源

試試看！