Autocomplete (new) サービスは、HTTP リクエストに応じて場所の予測とクエリの予測を返すウェブサービスです。リクエストでは、検索領域を制御するテキスト検索文字列と地理的境界を指定します。
Autocomplete（新）サービスでは、入力された完全な単語や部分文字列を照合して、場所の名前、住所、Plus Code を解決できます。そのため、アプリケーションはユーザーの入力に合わせてクエリを送信し、場所やクエリをその場で予測できます。
Autocomplete（新規）API からのレスポンスには、次の 2 種類の予測が含まれます。
- 場所の予測: 指定された入力テキスト文字列と検索領域に基づいた、お店やサービス、住所、スポットなどの場所。場所の予測はデフォルトで返されます。
- クエリの予測: 入力テキスト文字列と検索領域に一致するクエリ文字列。デフォルトでは、クエリ予測は返されません。
includeQueryPredictionsリクエスト パラメータを使用して、クエリ予測をレスポンスに追加します。
たとえば、部分的なユーザー入力「Sicilian piz」を含む文字列を入力として使用して API を呼び出します。検索領域はカリフォルニア州サンフランシスコに限定されます。レスポンスには、検索文字列と検索領域に一致する場所の予測リスト（「Sicilian Pizza Kitchen」という名前のレストランなど）のリストと、その場所の詳細が含まれます。
返される場所の予測は、ユーザーが目的の場所を選択できるように、ユーザーに提示するように設計されています。Place Details (New) リクエストを使用すると、返された場所の予測に関する詳細情報を取得できます。
レスポンスには、「Sicilian Pizza & Pasta」など、検索文字列と検索領域に一致するクエリ予測のリストを含めることもできます。レスポンスの各クエリ予測には、推奨されるテキスト検索文字列を含む text フィールドが含まれます。その文字列を Text Search (New) への入力として使用して、より詳細な検索を行います。
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
回答について
Autocomplete (New) は、レスポンスとして JSON オブジェクトを返します。レスポンスの説明:
suggestions配列には、予測される場所とクエリがすべて、関連性の高い順に並べて含まれます。各場所はplacePredictionフィールドで表され、各クエリはqueryPredictionフィールドで表されます。placePredictionフィールドには、プレイス ID やテキストによる説明など、1 つの場所の予測に関する詳細情報が含まれます。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 Code を指定します。Autocomplete (new) サービスは、この文字列と一致する候補を、関連性の高い順に並べて結果を並べ替えます。
省略可能なパラメータ
-
includedPrimaryTypes
1 つの場所に指定できるメインのタイプは、表 A または表 B にあるタイプの中から 1 つのみです。たとえば、メインのタイプは
"mexican_restaurant"や"steak_house"です。デフォルトでは、API は、場所に関連付けられているメインのタイプの値に関係なく、
inputパラメータに基づいてすべての場所を返します。includedPrimaryTypesパラメータを渡すことで、結果を特定のプライマリ型またはプライマリ型に制限します。このパラメータを使用して、Table A または Table B から最大 5 つの型値を指定します。場所は、指定されたプライマリ タイプ値のいずれかに一致すると、レスポンスに含まれます。
このパラメータには、代わりに
(regions)または(cities)のいずれかを含めることもできます。(regions)タイプのコレクションは、地区や区域（地区、郵便番号など）をフィルタします。(cities)タイプ コレクションは、Google が都市として識別する場所をフィルタします。次の場合、リクエストは
INVALID_REQUESTエラーで拒否されます。- 5 個を超えるタイプが指定されています。
(cities)または(regions)に加えて、任意の型を指定します。- 認識できないタイプが指定されています。
-
includeQueryPredictions
trueの場合、レスポンスには場所の予測とクエリの予測の両方が含まれます。デフォルト値はfalseです。つまり、レスポンスには場所の予測のみが含まれます。 -
includedRegionCodes
指定した地域のリストに含まれる結果のみを含めます。リストには、最大 15 個の ccTLD（「トップレベル ドメイン」）の 2 文字の値からなる配列を指定します。省略した場合、レスポンスに制限は適用されません。たとえば、リージョンをドイツとフランスに制限するには、次のようにします。
"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の場合、経度の範囲が反転します（ビューポートが 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（「トップレベル ドメイン」）の 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 メートルの外にある結果など、さらに多くのアイテムが含まれるようになりました。
{
"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 パラメータを使用して、Table A、Table 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 フィールドが含まれます。Text Search (New) リクエストを使用すると、返されたクエリ予測に関する詳細情報を取得できます。
オリジンを使用
この例では、リクエストに origin を緯度と経度の座標として含めます。origin を含めると、API は、origin から目的地までの直線距離を含む distanceMeters フィールドをレスポンスに含めます。次の例では、起点をサンフランシスコの中心に設定しています。
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] ウィンドウを展開します。