はじめに
Autocomplete (New) は、HTTP リクエストに応じて場所の候補とクエリ予測を返すウェブサービスです。リクエストでは、テキスト検索文字列に加え、検索対象地域を限定する地理的境界を指定します。
Autocomplete（新機能）は、入力の完全な単語や部分文字列を照合して、場所の名前や住所、Plus Codes を解決できます。これにより、アプリケーションはユーザーの入力に合わせて随時クエリを送信し、場所とクエリの候補をリアルタイムで表示することができます。
Autocomplete（新版）からのレスポンスには、次の 2 種類の予測が含まれることがあります。
- プレイスの予測: 指定された入力テキスト文字列と検索エリアに基づいて、お店やサービス、住所、スポットなどのプレイス。場所の予測はデフォルトで返されます。
- クエリの予測: 入力テキスト文字列と検索エリアに一致するクエリ文字列。クエリ予測はデフォルトでは返されません。
includeQueryPredictionsリクエスト パラメータを使用して、レスポンスにクエリ予測を追加します。
たとえば、ユーザー入力の一部である「Sicilian piz」を含む文字列を入力として Autocomplete（新版）を呼び出し、検索エリアをカリフォルニア州サンフランシスコに限定します。レスポンスには、検索文字列と検索エリアに一致する場所の予測のリスト（「Sicilian Pizza Kitchen」という名前のレストランなど）と、その場所の詳細が含まれます。
返される場所の予測は、ユーザーが目的の場所を選択する際に役立つように設計されています。Place Details (New) リクエストを作成して、返された場所の予測に関する詳細情報を取得できます。
レスポンスには、検索文字列と検索エリアに一致するクエリ予測のリスト（「シチリア風ピザとパスタ」など）を含めることもできます。レスポンスの各クエリ予測には、推奨されるテキスト検索文字列を含む text フィールドが含まれています。この文字列を テキスト検索（新版）の入力として使用して、より詳細な検索を実行します。
API Explorer を使用すると、ライブ リクエストを行って、API と API オプションを理解できます。
Autocomplete（新規）リクエスト
Autocomplete（新機能）リクエストは、次の形式の 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
サポートされるパラメータ
パラメータ |
説明 |
|---|---|
検索するテキスト文字列（完全な単語、部分文字列、場所の名前、住所、Plus Codes）。 |
|
|
レスポンスで返すフィールドを指定するカンマ区切りのリスト。 |
結果を、指定された最大 5 つのプライマリ タイプのうちの 1 つに一致する場所に制限します。 |
|
true の場合、実店舗を持たないビジネス（非店舗型ビジネス）が含まれます。デフォルトは false です。 |
|
true の場合、レスポンスに場所とクエリの両方の予測が含まれます。デフォルトは false です。 |
|
結果を制限する 2 文字の国コードの配列（最大 15 個）。 |
|
入力文字列内のカーソル位置の 0 から始まる Unicode 文字オフセット。予測に影響します。デフォルトは入力長です。 |
|
結果の優先言語（IETF BCP-47 コード）。デフォルトは Accept-Language ヘッダーまたは「en」です。 |
|
検索結果のバイアスをかける領域（円または長方形）を指定します。この領域外の結果も許可されます。locationRestriction と一緒に使用することはできません。 |
|
検索結果を制限する領域（円または長方形）を指定します。この範囲外の結果は除外されます。locationBias と併用することはできません。 |
|
予測された目的地までの直線距離（distanceMeters）の計算に使用される出発地点（緯度、経度）。 |
|
レスポンスのフォーマットと候補のバイアスに使用される地域コード（例: 'uk', 'fr'）。 |
|
請求処理のためにオートコンプリート呼び出しをセッションにグループ化するユーザー生成文字列。 |
回答について
Autocomplete（新版）は、レスポンスとして 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.text.textとsuggestions.queryPrediction.text.textを取得します。X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
すべてのフィールドを取得するには、
*を使用します。X-Goog-FieldMask: *
-
includedPrimaryTypes
場所には、表 A または 表 B に記載されているタイプの 1 つのプライマリ タイプのみを設定できます。たとえば、プライマリ タイプは
"mexican_restaurant"または"steak_house"になります。デフォルトでは、API は場所に関連付けられたプライマリ タイプ値に関係なく、
inputパラメータに基づいてすべての場所を返します。includedPrimaryTypesパラメータを渡すことで、結果を特定のプライマリ タイプまたはプライマリ タイプに制限できます。このパラメータを使用して、表 A または 表 B から最大 5 つのタイプ値を指定します。レスポンスに含めるには、場所が指定されたプライマリ タイプ値のいずれかと一致する必要があります。
このパラメータには、代わりに
(regions)または(cities)のいずれかを含めることもできます。(regions)型のコレクションは、地域や区分（近隣地域や郵便番号など）でフィルタします。(cities)タイプのコレクションは、Google が都市として識別した場所をフィルタします。次の場合、リクエストは
INVALID_REQUESTエラーで拒否されます。- 指定したタイプの数が 5 個より多い。
(cities)または(regions)に加えて、任意の型が指定されている。- 認識できないタイプが指定されている。
-
includePureServiceAreaBusinesses
trueに設定されている場合、レスポンスには、顧客を直接訪問または配送するが、実店舗の所在地がないビジネスが含まれます。falseに設定すると、API は実店舗を持つビジネスのみを返します。 -
includeQueryPredictions
trueの場合、レスポンスには場所とクエリの両方の予測が含まれます。デフォルト値はfalseです。これは、レスポンスに場所の予測のみが含まれることを意味します。 -
includedRegionCodes
指定された地域リストの結果のみを含めます。地域リストは、最大 15 個の ccTLD（「トップレベル ドメイン」）の 2 文字の値の配列として指定します。省略した場合、レスポンスに制限は適用されません。たとえば、リージョンをドイツとフランスに制限するには:
"includedRegionCodes": ["de", "fr"]
locationRestrictionとincludedRegionCodesの両方を指定すると、結果は 2 つの設定の共通部分に配置されます。 -
inputOffset
input内のカーソル位置を示す 0 から始まる 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リージョンを長方形のビューポートまたは円として指定します。円は、中心点と半径（メートル単位）で定義されます。半径は 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 } } }
-
origin
目的地までの直線距離を計算する起点（
distanceMetersとして返されます）。この値を省略すると、直線距離は返されません。緯度と経度の座標として指定する必要があります。"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
レスポンスのフォーマットに使用される地域コード。ccTLD（「トップレベル ドメイン」）の 2 文字の値として指定します。ほとんどの ccTLD コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、ISO 3166-1 コードは「gb」（厳密には「グレートブリテンおよび北アイルランド連合王国」のエンティティ用）です。
候補は地域コードに基づいてバイアスがかかることもあります。Google では、ユーザーの地域設定に応じて
regionCodeを設定することをおすすめします。無効なリージョン コードを指定すると、API は
INVALID_ARGUMENTエラーを返します。このパラメータは、適用される法律に基づいて結果に影響を与える可能性があります。 -
sessionToken
セッション トークンは、Autocomplete（新版）の呼び出しを「セッション」として追跡するユーザー生成の文字列です。Autocomplete（新規）は、セッション トークンを使用して、予測入力検索でのユーザーのクエリと選択フェーズを、請求処理のために個別のセッションにグループ化します。詳細については、セッション トークンをご覧ください。
結果をバイアスするパラメータを選択する
オートコンプリート（新規）パラメータは、検索結果に異なる影響を与える可能性があります。次の表に、目的の結果に基づいてパラメータを使用する際の推奨事項を示します。| パラメータ | 使用状況の推奨事項 |
|---|---|
regionCode |
ユーザーの地域設定に応じて設定します。 |
includedRegionCodes |
結果を指定したリージョンのリストに制限するように設定します。 |
locationBias |
結果がリージョン内またはその周辺で優先される場合に使用します。該当する場合は、ユーザーが閲覧している地図のビューポートとしてリージョンを定義します。 |
locationRestriction |
リージョン外の結果を返してはならない場合は、only を使用します。 |
origin |
各予測までの直線距離を計算する場合に使用します。 |
Autocomplete（新機能）の例
locationRestriction を使用して検索を特定のエリアに制限する
locationRestriction は、検索する領域を指定します。指定した範囲外の結果は返されません。次の例では、locationRestriction を使用して、サンフランシスコを中心とする半径 5, 000 メートルの円にリクエストを制限します。
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
結果には、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" ] } }, ... ] }
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" ] } }, /.../ ] }
includedPrimaryTypes を使用する
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 を含めると、Autocomplete（新版）は、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 } } ] }
レスポンスに距離が含まれていない
リクエストに origin が含まれていても、レスポンス本文に distanceMeters が含まれていない場合があります。これは、次のような場合に発生する可能性があります。
distanceMetersはroute予測には含まれません。distanceMetersの値が0の場合、つまり、指定されたoriginの位置から 1 メートル未満の予測の場合、distanceMetersは含まれません。
解析されたオブジェクトから distanceMeters フィールドを読み取ろうとするクライアント ライブラリは、値 0 のフィールドを返します。ユーザーを誤解させないように、ユーザーに距離がゼロと表示されないようにしてください。
Autocomplete（新機能）の最適化
このセクションでは、Autocomplete（新版）サービスを最大限に活用するためのヒントを紹介します。
概要は次のとおりです。
- 機能的なユーザー インターフェースを最も手早く作成するには、Maps JavaScript API Autocomplete（新版）ウィジェット、Places SDK for Android Autocomplete（新版）ウィジェット、または Places SDK for iOS Autocomplete（新版）ウィジェットを使用します。
- Autocomplete（新規）のデータ フィールドの基本を理解します。
- 位置情報のバイアスと位置情報の制限のフィールドは省略可能ですが、予測入力のパフォーマンスに大きく影響する場合があります。
- エラー処理を使用して、API がエラーを返した場合に、アプリでグレースフル デグラデーションが行われるようにします。
- アプリでは、選択肢がない場合でもユーザーが操作を続行できるようにします。
費用の最適化に関するヒント
基本的な費用の最適化
Autocomplete（新版）サービスの費用を最適化するには、Place Details（新版）と Autocomplete（新版）ウィジェットのフィールド マスクを使用して、必要な Autocomplete（新版）のデータ フィールドのみを返すように設定します。
高度な費用の最適化
SKU: Autocomplete Request の料金設定を利用し、Place Details（新）の代わりに選択された場所に関する Geocoding API の結果をリクエストするためには、Autocomplete（新）のプログラマティック実装を行うことをおすすめします。次の両方に該当する場合は、リクエストあたりの料金設定と Geocoding API を組み合わせた方が、セッションあたり（セッション ベース）の料金設定よりも費用対効果が高くなります。
- ユーザーが選択した場所の緯度/経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details（新版）の呼び出しよりも少ないコストでこの情報を提供できます。
- ユーザーが予測結果を選択するまでの予測入力候補（新）リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。
アプリケーションで、選択された予測結果の住所と緯度 / 経度以外の情報が必要ですか？
はい。その他の情報も必要です
セッション ベースの Autocomplete（新版）と Place Details（新版）を併用します。
アプリケーションで場所の名前、ビジネス ステータス、営業時間などの Place Details（新版）が必要なため、Autocomplete（新版）の実装では、セッション トークン（プログラムによる、または JavaScript、Android、iOS ウィジェットに組み込み）をセッションごとに使用する必要があります。また、リクエストする場所のデータ フィールドに応じて、該当する Places SKU も使用する必要があります。1
ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Autocomplete（新版）リクエストと Place Details（新版）リクエストの両方が含まれます。必要な Autocomplete（新版）のデータ フィールドのみをリクエストするように、必ず fields パラメータを指定してください。
プログラマティック実装
Autocomplete（新版）リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details（新版）をリクエストする際は、次のパラメータを含めます。
- Autocomplete（新版）レスポンスのプレイス ID
- Autocomplete（新版）リクエストで使用されるセッション トークン
- 必要な Autocomplete（新版）データ フィールドを指定する
fieldsパラメータ
いいえ。住所と場所のみが必要です
Autocomplete（新版）の使用時のパフォーマンスによっては、アプリケーションで Place Details（新版）を使用するよりも、Geocoding API を使用した方が費用対効果が高くなる場合があります。アプリケーションの予測入力（新機能）の効率は、ユーザーの入力内容や、アプリケーションが使用される場所、パフォーマンス最適化のベスト プラクティスが導入されているかどうかによって変わります。
次の質問に答えるためには、ユーザーがアプリケーション内で Autocomplete（新版）の予測を選択するまでに、平均でどのくらいの文字数を入力するのかを分析する必要があります。
ユーザーが Autocomplete（新版）の予測を選択するまでに実行されるリクエスト数は、平均で 4 回以下ですか？
○
セッション トークンを使用せずにプログラムによって Autocomplete（新機能）を実装し、選択された場所の予測で Geocoding API を呼び出します。
Geocoding API は、住所と緯度/経度の座標を提供します。Autocomplete リクエスト 4 件と、選択された場所予測に関する Geocoding API の呼び出しを合わせた料金は、Per Session Autocomplete（新規）のセッション 1 回あたりの料金よりも少ないコストです。1
パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める情報を提供できるようすることをおすすめします。
いいえ
セッション ベースの Autocomplete（新版）と Place Details（新版）を併用します。
ユーザーが Autocomplete（新版）の予測を選択するまでに実行されるリクエスト数の平均が、セッションあたりの料金設定の費用を超えるため、Autocomplete（新版）の実装では、Autocomplete（新版）リクエストと関連する Place Details（新版）リクエストの両方で、セッションあたりのセッション トークンを使用する必要があります。1
ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Autocomplete（新版）リクエストと Place Details（新版）リクエストの両方が含まれます。必要なフィールドのみをリクエストするように、必ず fields パラメータを指定してください。
プログラマティック実装
Autocomplete（新版）リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details（新版）をリクエストする際は、次のパラメータを含めます。
- Autocomplete（新版）レスポンスのプレイス ID
- Autocomplete（新版）リクエストで使用されるセッション トークン
- 住所やジオメトリなどのフィールドを指定する
fieldsパラメータ
Autocomplete (New) リクエストを遅らせることを検討する
ユーザーが最初の 3 ～ 4 文字を入力するまで Autocomplete (New) リクエストを遅らせて、アプリケーションでのリクエスト数を減らすこともできます。たとえば、ユーザーが 3 文字を入力した後に、各文字に対して Autocomplete（New）リクエストを行う場合、ユーザーが 7 文字を入力して、1 件の Geocoding API リクエストを行う予測を選択すると、合計料金は 4 件の Autocomplete（New）Per Request + Geocoding の料金になります。1
リクエストを遅らせることで、プログラマティック リクエストの回数を平均 4 回以下に抑えられる場合は、高パフォーマンスで Autocomplete（新版）と Geocoding API を併用する実装に関するガイダンスをご覧ください。なお、リクエストを遅らせると、1 文字入力するたびに予測が表示されはずと考えているユーザーには、遅延と受けとられる場合もあります。
パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める情報を提供できるようすることをおすすめします。
-
費用については、Google Maps Platform の料金リストをご覧ください。
パフォーマンスに関するベスト プラクティス
Autocomplete（新機能）のパフォーマンスを最適化するためのガイドラインは次のとおりです。
- Autocomplete（新版）実装に、国別のポリシー、場所のバイアス、言語設定（プログラマティック実装の場合）を追加します。ウィジェットはユーザーのブラウザやモバイル デバイスから言語設定を選択するため、ウィジェットでは言語設定は不要です。
- Autocomplete（新版）が地図に関連付けられている場合は、地図のビューポートを基準に場所にバイアスをかけることができます。
- ユーザーが予測入力候補（新版）のいずれも選択しなかった場合（通常は目的の住所が候補に挙がらなかったことが原因）、ユーザーの元の入力内容を再利用して、より関連性の高い結果を取得できます。
- ユーザーが住所情報のみを入力することが予想される場合は、Geocoding API の呼び出しで、ユーザーの元の入力内容を再利用します。
- ユーザーが特定の場所に関する検索語句（名前や住所）を入力することが予想される場合は、Place Details (New) リクエストを使用します。特定の地域の結果のみが求められる場合は、場所のバイアスを使用します。
- 建物内の特定のユニットやアパートの住所など、サブプレミス住所を入力するユーザー。たとえば、チェコ語の住所「Stroupežnického 3191/17, Praha」では、Autocomplete（新版）で部分的な予測が生成されます。
- ユーザーがニューヨークの「23-30 29th St, Queens」や、ハワイのカウアイ島の「47-380 Kamehameha Hwy, Kaneohe」など、道路区間のプレフィックスを入力する場合。
位置情報のバイアス
location パラメータと radius パラメータを渡すことで、バイアスを設定し、指定した範囲内の結果を優先します。これにより、定義されたエリア内の結果を優先的に表示するよう Autocomplete（新版）に指示します。指定した範囲外の結果が返されることもあります。components パラメータを使用すると、指定した国内の場所のみを表示するように結果をフィルタできます。
ロケーションの制限
locationRestriction パラメータを渡すことで、結果を指定したエリアに制限します。
locationRestriction パラメータを追加して、location パラメータと radius パラメータで定義された地域に結果を制限することもできます。これにより、その地域内の結果のみを返すように Autocomplete（新版）に指示します。
試してみよう:
API Explorer を使用すると、サンプル リクエストを作成して、API と API オプションを理解できます。
ページの右側にある API アイコン api を選択します。
必要に応じてリクエスト パラメータを編集します。
[実行] ボタンを選択します。ダイアログで、リクエストに使用するアカウントを選択します。
API Explorer パネルで、全画面アイコン fullscreen を選択して API Explorer ウィンドウを拡大します。