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

自動完成 (新推出)

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

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

Autocomplete (新版) API 的回應可包含兩種預測類型：

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

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

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

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

您可以透過 API Explorer 發出即時要求，熟悉 API 和 API 選項：

試試看！

Autocomplete (新) 要求

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 欄位包含單一查詢預測的詳細資訊。

注意：Autocomplete (新版) 會根據要求，傳回總共五種預測結果，可能是 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 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 (New) 並不支援所有主要類型。支援的類型包括表 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 (新版) 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以便計費。詳情請參閱「工作階段符記」。

自動完成 (新) 範例

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

使用 includePrimaryType

使用 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，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 視窗。

自動完成 (新推出)

Autocomplete (新) 要求

關於回覆

必要參數

輸入

自選參數

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 或 locationRestriction

locationBias

locationRestriction

發跡地

regionCode

sessionToken

自動完成 (新) 範例

使用 locationRestriction 和 locationBias

使用 includePrimaryType

要求預測查詢字串

使用來源

試試看！