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

自動完成 (新推出)

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

自動完成 (新版) 服務來回應 HTTP 要求在要求中指定搜尋字串和控制搜尋區域的地理邊界。

「自動完成 (新版)」服務可比對完整字詞，所輸入的子字串，解析地點名稱、地址和 plus code。因此應用程式會傳送以便即時提供地點和查詢預測結果。

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

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

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

傳回的地點預測結果旨在協助使用者，讓他們選擇您想要的地點你可以 Place Details (新功能) 要求，取得任何傳回地點預測結果的詳細資訊。

回應中也可包含與查詢預測相符的搜尋字串和搜尋區域，例如「西里西亞披薩和義大利麵」。顯示查詢的回應中的 text 欄位含有建議的文字搜尋字串。使用做為輸入內容 Text Search (新版) 執行更詳細的搜尋

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

試試看！

自動完成 (新版) 要求

Autocomplete (新版) 請求是對表單：

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

關於回覆

自動完成 (新版) 會傳回 JSON 物件做為回應。在回覆中：

suggestions 陣列包含所有的預測地點和查詢，依序排列進行分類每個地點都會以 placePrediction 欄位，且每項查詢都代表由 queryPrediction 欄位傳回
placePrediction 欄位包含單一地點預測結果，包括地點 ID 和文字說明。
queryPrediction 欄位包含單一做為預測查詢的依據

，瞭解如何調查及移除這項存取權。

注意：自動完成 (新版) 會傳回五項預測，呈現方式為 placePredictions、 queryPredictions 或兩者並用，視要求而定。舉例來說，如果請求未設定 includeQueryPredictions，回應主體最多包含 5 個 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 code。 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 到 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 個錯誤。
- 偏好的語言對於 Google 提供的 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

工作階段符記是使用者產生的字串，可追蹤自動完成功能 (新) 呼叫做為「工作階段」。自動完成 (新版) 會使用工作階段符記將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段帳單用途若需更多資訊，請參閲工作階段符記。

自動完成 (新版) 範例

使用 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 圖示。網頁右側。
視需要展開「顯示標準參數」並進行設定 fields 參數 欄位遮罩。
視需要編輯「要求主體」。
選取「執行」按鈕。在彈出式視窗中，選擇要用來提出請求的帳戶。
在 API Explorer 面板中，選取展開圖示，展開「API Explorer」視窗。

自動完成 (新推出)

自動完成 (新版) 要求

關於回覆

必要參數

輸入

選用參數

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 或 locationRestriction

locationBias

locationRestriction

起源

regionCode

sessionToken

自動完成 (新版) 範例

使用 locationRestriction 和 locationBias

使用 includePrimaryTypes

要求查詢預測

使用來源

試試看！