Autocomplete（新版）サービスは、HTTP リクエストに応じて場所の予測とクエリの予測を返すウェブサービスです。リクエストでは、テキスト検索文字列と、検索領域を制御する地理的境界を指定します。
予測入力（新版）サービスは、入力に含まれる完全な単語や部分文字列を照合して、場所の名前や住所、Plus Codes を解決できます。これにより、アプリケーションはユーザーの入力に応じてクエリを送信し、場所やクエリの候補をその場で提供できます。
Autocomplete (新) API からのレスポンスには、次の 2 種類の予測が含まれます。
- 場所の候補: 指定された入力テキスト文字列と検索領域に基づく、店舗、住所、スポットなどの場所。場所の予測はデフォルトで返されます。
- クエリ予測: 入力テキスト文字列と検索領域に一致するクエリ文字列。デフォルトでは、クエリ予測は返されません。
includeQueryPredictionsリクエスト パラメータを使用して、レスポンスにクエリ予測を追加します。
たとえば、ユーザー入力の一部を含む文字列「Sicilian piz」を入力として使用し、検索領域をカリフォルニア州サンフランシスコに限定して API を呼び出します。レスポンスには、検索文字列と検索エリアに一致する場所の候補のリストが含まれます（「Sicilian Pizza Kitchen」など）。場所の詳細が含まれます。
返される「場所の候補」は、ユーザーが目的の場所を選択しやすいように、ユーザーに表示されるように設計されています。Place Details（新）リクエストを行うと、返された場所予測に関する詳細情報を取得できます。
レスポンスには、検索文字列と検索領域に一致するクエリ予測のリスト（「Sicilian Pizza & Pasta」など）を含めることもできます。レスポンスの各クエリ予測には、推奨されるテキスト検索文字列を含む text フィールドが含まれます。この文字列をテキスト検索（新版）への入力として使用し、より詳細な検索を実行します。
API Explorer を使用すると、ライブ リクエストを発行できるため、API と API オプションについて理解を深めることができます。
お試しください予測入力（新）リクエスト
予測入力（新）リクエストは、次の形式の URL に対する 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
回答について
予測入力（新）は、レスポンスとして JSON オブジェクトを返します。レスポンスの説明:
suggestions配列には、予測されるすべての場所とクエリが、関連性の程度に基づいて順番に格納されます。各場所はplacePredictionフィールドで表され、各クエリはqueryPredictionフィールドで表されます。placePredictionフィールドには、プレイス ID や説明文など、1 つの場所の予測に関する詳細情報が含まれます。queryPredictionフィールドには、1 つのクエリ予測に関する詳細情報が含まれます。
完全な 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 を指定します。予測入力（新）サービスは、この文字列に基づいて一致する候補を返し、認識された関連性に基づいて結果を並べ替えます。
省略可能なパラメータ
-
includedPrimaryTypes
場所には、Table A または Table B に記載されているタイプのうち、1 つのプライマリ タイプのみを指定できます。たとえば、プライマリ タイプは
"mexican_restaurant"や"steak_house"です。デフォルトでは、API は場所に関連付けられているメインのタイプの値に関係なく、
inputパラメータに基づいてすべての場所を返します。includedPrimaryTypesパラメータを渡すことで、結果を特定のプライマリ型またはプライマリ型に制限します。このパラメータを使用して、Table A または Table B の型の値を最大 5 つ指定します。場所がレスポンスに含まれるためには、指定されたプライマリ タイプの値のいずれかと一致する必要があります。
このパラメータには、代わりに
(regions)または(cities)のいずれかを含めることもできます。(regions)タイプ コレクションは、区域や郵便番号などのエリアや区分をフィルタします。(cities)タイプ コレクションは、Google が都市として識別した場所をフィルタします。次の場合、リクエストは
INVALID_REQUESTエラーで拒否されます。- 6 つ以上のタイプが指定されている。
(cities)または(regions)に加えて、任意の型を指定します。- 認識されないタイプが指定されています。
-
includeQueryPredictions
trueの場合、レスポンスには場所予測とクエリ予測の両方が含まれます。デフォルト値はfalseです。つまり、レスポンスには場所の候補のみが含まれます。 -
includedRegionCodes
指定した地域のリストから、検索結果のみを含めます。ccTLD（「トップレベル ドメイン」）という 2 文字の値（最大 15 個）の配列として指定します。省略すると、レスポンスに制限は適用されません。たとえば、リージョンをドイツとフランスに制限するには、次のようにします。
"includedRegionCodes": ["de", "fr"]locationRestrictionとincludedRegionCodesの両方を指定すると、結果は 2 つの設定の交差する領域に配置されます。 -
inputOffset
input内のカーソル位置を示す、ゼロベースの Unicode 文字オフセット。カーソルの位置は、返される予測の種類に影響します。空の場合、デフォルトで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の領域を長方形のビューポートまたは円として指定します。円は、中心点と半径（メートル単位）で定義します。radius は 0.0 ～ 50000.0 の範囲内（両端を含む）にする必要があります。デフォルト値は 0.0 です。
locationRestrictionの場合、半径は 0.0 より大きい値に設定する必要があります。それ以外の場合、リクエストは結果を返しません。次に例を示します。
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }長方形は緯度と経度のビューポートであり、対角線上に 2 つの
lowと高いポイントとして表されます。ビューポートは閉じた領域とみなされ、その境界が含まれます。緯度境界は -90 ～ 90 度の範囲、経度境界は -180 ～ 180 度の範囲にする必要があります。low=highの場合、ビューポートはその単一点で構成されます。low.longitude>high.longitudeの場合、経度の範囲は逆になります（ビューポートは経度線と交差します）。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（「トップレベル ドメイン」）の 2 文字の値として指定します。ほとんどの 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 を使用して、サンフランシスコを中心とする半径 5, 000 m の円にリクエストを制限します。
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
結果には、半径 5, 000 m を超える結果など、さらに多くのアイテムが含まれるようになりました。
{
"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"
]
}
},
...
]
}
含まれている PrimaryTypes を使用する
includedPrimaryTypes パラメータを使用して、テーブル A、テーブル B、(regions) のみ、または (cities) のみから最大 5 つの型の値を指定します。場所がレスポンスに含まれるには、指定されたメインのタイプの値のいずれかと一致する必要があります。
次の例では、input という文字列に「Soccer」を指定し、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 フィールドが含まれます。テキスト検索（新版）リクエストを行うと、返されたクエリ予測に関する詳細情報を取得できます。
オリジンを使用
この例では、緯度と経度の座標としてリクエストに 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パラメータをフィールド マスクに設定します。 - 必要に応じて、[Request body] を編集します。
- [Execute] ボタンを選択します。ポップアップで、リクエストに使用するアカウントを選択します。
[API Explorer] パネルで展開アイコン
を選択して、[API Explorer] ウィンドウを展開します。