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) への入力として使用して、より詳細な検索を行います。
オートコンプリート(新規)リクエスト
オートコンプリート(新規)リクエストは、次の形式の 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
オートコンプリート(新機能)を使用してリクエストする
Places API は、既存の Autocomplete API と Query Autocomplete API をサポートしています。これらの API を使い慣れている方を対象に、オートコンプリート(新)のプレビュー版に次の変更が加えられています。- 新しいオートコンプリートは HTTP POST リクエストを使用します。HTTP POST リクエストの一部として、リクエスト本文またはヘッダーでパラメータを渡します。これに対して、既存の API では、HTTP GET リクエストを使用して URL パラメータを渡します。
- 新しいオートコンプリートは、認証メカニズムとして API キーと OAuth トークンの両方をサポートしています。
- 新しいオートコンプリートでは、レスポンス形式として JSON のみがサポートされています。
次の表は、既存の Autocomplete API と Query Autocomplete API のパラメータのうち、新しい Autocomplete に合わせて名前が変更されたり、変更されたパラメータと、サポートされなくなったパラメータを示しています。
現在のパラメータ | 新しいパラメータ | メモ |
---|---|---|
components |
includedRegionCodes |
|
language |
languageCode |
|
location |
locationBias |
|
ipbias |
locationBias と locationRestriction の両方を省略した場合、API はデフォルトで IP バイアスを使用します。 |
|
offset |
inputOffset |
|
radius |
locationBias または locationRestriction |
|
region |
regionCode |
|
stricbounds |
locationRestriction |
|
sessiontoken |
sessionToken |
|
types |
includedPrimaryTypes |
使用量上限
プレビュー リリースでは、プロジェクトごとに 1 分あたり最大 600 件のクエリに制限されます。
プレビュー リリースのサポート オプション
Google は本サービスのプレビュー版、機能、機能に関してサポートを提供する義務を負いませんが、これらの開発段階でのリクエストは状況に応じて個別に検討します。
- プレリリース版は Google Maps Platform SLA の対象外です。
- 特に本番環境でプレリリース版を使用している場合は、フォールバック メカニズムを使用することをおすすめします。フォールバックの状況の例としては、割り当て超過、予期しないレスポンス コードとレイテンシ、既存のオートコンプリートと比較した場合の予期しないレスポンスなどがあります。
Issue Tracker を使用して、新機能のリクエストや既存の機能の変更の提案を行うことができます。追加を希望する機能と、その機能を重視する理由を記載してください。可能であれば、具体的なユースケースと、この機能によって実現できる新たな可能性についても記載してください。
機能に関するその他のご質問については、newplacesapi@google.com までメールをお送りください。
回答について
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 つの場所に設定できるメインタイプは Table A または Table B の1 つのみです。たとえば、メインのタイプは
"mexican_restaurant"
や"steak_house"
です。デフォルトでは、API は、場所に関連付けられているメインのタイプの値に関係なく、
input
パラメータに基づいてすべての場所を返します。includedPrimaryTypes
パラメータを渡すことで、結果を特定のプライマリ型またはプライマリ型に制限します。このパラメータを使用して、Table A または Table B から最大 5 つの型値を指定します。場所は、指定されたプライマリ タイプ値のいずれかに一致すると、レスポンスに含まれます。
次の場合、リクエストは
INVALID_REQUEST
エラーで拒否されます。- 5 個を超えるタイプが指定されています。
- 認識できないタイプが指定されています。
-
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
パラメータを使用して、リクエストの結果を表 A と表 B にある特定のタイプに制限します。最大 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 } } ] }