自動完成 (新推出)

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

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

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

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

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

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

系統會將傳回的地點預測結果呈現給使用者，協助他們選取所需地點。您可以提出 Place Details (新版) 要求，進一步瞭解任何傳回的地點預測資訊。

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

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

試試看吧！

Autocomplete (New) 要求

Autocomplete (New) 要求是對下列格式網址發出的 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 (New) 會傳回 JSON 物件做為回應。在回應中：

  • suggestions 陣列會根據預測到的關聯性，依序列出所有預測地點和查詢。每個地點都以 placePrediction 欄位表示，每項查詢都以 queryPrediction 欄位表示。
  • placePrediction 欄位含有單一地點預測的相關詳細資訊，包括地點 ID 和文字說明。
  • queryPrediction 欄位包含單一查詢預測的詳細資訊。

完整的 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.place 和 suggestions.placePrediction.text。

      X-Goog-FieldMask: places.displayName,places.formattedAddress

    使用 * 擷取所有欄位。

      X-Goog-FieldMask: *

  • includedPrimaryTypes

    一個地點只能從表 A 或表 B 所列的類型中擁有單一主要類型。例如，主要類型可能是 "mexican_restaurant" 或 "steak_house"。

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

    您可以使用這個參數，指定 表 A 或 表 B 中的值 (最多五個)。地點必須符合指定的主要類型值，才能納入回應中。

    這個參數也可以改為包含 (regions) 或 (cities) 其中一個。區域或部門 (例如社區和郵遞區號) 的 (regions) 類型集合篩選器。(cities) 類型集合篩選器可用於篩選出 Google 識別為城市的地點。

    如有下列情況，要求就會遭到拒絕，並傳回 INVALID_REQUEST 錯誤：

    • 指定的類型超過五個。
    • 除了 (cities) 或 (regions) 之外，任何類型皆可指定。
    • 指定了任何無法辨識的類型。

  • includePureServiceAreaBusinesses

    如果設為 true，回應就會包含直接造訪或送貨給客戶，但沒有實體商家地址的商家。如果設為 false，API 只會傳回有實體營業場所的商家。

  • includeQueryPredictions

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

  • includedRegionCodes

    僅包含指定區域清單的結果，且指定為最多 15 個 ccTLD (「頂層網域」) 雙字元值的陣列。如果省略，系統不會對回應套用任何限制。例如，如要將地區限制為德國和法國：

        "includedRegionCodes": ["de", "fr"]

    如果同時指定 locationRestriction 和 includedRegionCodes，結果會位於這兩個設定的交集區域。

  • inputOffset

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

  • 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

      指定要搜尋的區域。系統不會傳回指定區域以外的結果。

    將 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 (New) 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。詳情請參閱工作階段符記。

自動完成 (新版) 範例

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

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

使用 includePrimaryTypes

使用 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) 要求，進一步瞭解任何傳回的查詢預測結果。

使用來源

在這個範例中，請在要求中加入 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 選項。

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

  5. 在 API Explorer 面板中，選取展開圖示 展開 API Explorer。，展開 API Explorer 視窗。