はじめに
オートコンプリートは、Maps JavaScript API のプレイス ライブラリの機能です。オートコンプリートを使用すると、Google マップの検索フィールドの逐次検索機能をアプリケーションに組み込むことができます。オートコンプリート サービスは、完全な単語や部分文字列を照合して、場所の名前や住所、Plus Codes を解決できます。これにより、アプリケーションはユーザーが入力を始めるとクエリを送信し、候補となる場所を即座に返すことができます。
始める
Maps JavaScript API でプレイス ライブラリを使用するにはまず、Maps JavaScript API 用に設定したプロジェクトで、Places API が有効になっていることを Google Cloud コンソールで確認します。
有効な API のリストを表示する手順は次のとおりです。
- Google Cloud コンソールに移動します。
- [プロジェクトを選択] ボタンをクリックし、Maps JavaScript API を設定した同じプロジェクトを選択して、[開く] をクリックします。
- [ダッシュボード] の API のリストから、Places API を探します。
- リストに API が表示されていれば、準備は完了です。API がリストに表示されていない場合は、次の手順で有効にします。
- ページの上部で、[API を有効にする] を選択して [ライブラリ] タブを表示します。または、左側のサイドメニューで [ライブラリ] を選択します。
- Places API を検索し、結果のリストから選択します。
- [有効にする] を選択します。このプロセスを完了すると、[ダッシュボード] の API のリストに Places API が表示されます。
ライブラリを読み込む
プレイス サービスは、メインの Maps JavaScript API コードとは別の自己完結型のライブラリです。このライブラリにある機能を利用するには、最初に Maps API ブートストラップ URL の libraries
パラメータを使用してライブラリを読み込む必要があります。
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>
詳細については、ライブラリの概要のページをご覧ください。
クラスの概要
API には、2 種類のオートコンプリート ウィジェットが用意されており、それぞれ Autocomplete
クラスと SearchBox
クラスで指定することができます。また、AutocompleteService
クラスを使用して、プログラムによってオートコンプリートの結果を取得することもできます(詳しくは Maps JavaScript API リファレンスの AutocompleteService クラスをご覧ください)。
利用可能なクラスの概要は次のとおりです。
Autocomplete
は、ウェブページにテキスト入力フィールドを追加し、そのフィールドへの文字入力を監視します。ユーザーがテキストを入力すると、オートコンプリートによりプルダウン リストの形式で候補となる場所が返されます。ユーザーがリストから場所を選択すると、その場所の情報がオートコンプリート オブジェクトに返され、アプリケーションによる取得が可能になります。詳しくは下記をご覧ください。SearchBox
は、Autocomplete
と同様にウェブページにテキスト入力フィールドを追加しますが、次の点で異なります。- 主な違いは、選択リストに表示される結果です。
SearchBox
は、予測リストを拡張して提供します。つまり Places API で定義される場所に加えて、検索キーワードの候補も表示します。たとえば、ユーザーが「東京のピ」まで入力すると、選択リストには「東京のピザ屋」という語句が含まれ、さらにさまざまなピザ販売店の名前が含まれます。 - 検索を制限する場合、
SearchBox
で指定できるオプションはAutocomplete
ほど多くありません。前者では、指定したLatLngBounds
に対して検索に優先度を持たせることができます。後者では、検索を特定の国や特定のタイプの場所に絞り込むことができ、境界を設定することも可能です。詳しくは、以下をご覧ください。
- 主な違いは、選択リストに表示される結果です。
AutocompleteService
オブジェクトを作成して、プログラムで予測を取得することができます。getPlacePredictions()
を呼び出して一致する場所を取得するか、getQueryPredictions()
を呼び出して、一致する場所に加えて検索キーワードの候補を取得します。注:AutocompleteService
では、UI コントロールは追加されません。代わりに、上記のメソッドで予測オブジェクトの配列が返されます。各予測オブジェクトには、予測のテキストに加え、参照情報、さらに結果がどのようにユーザー入力と一致しているのかの詳細が含まれます。詳しくは下記をご覧ください。
Autocomplete ウィジェットを追加する
Autocomplete
ウィジェットは、ウェブページにテキスト入力フィールドを作成し、ユーザー インターフェースの選択リストに候補となる場所を提示します。getPlace()
リクエストへのレスポンスには、プレイスの詳細情報を返します。選択リスト内のエントリはそれぞれ 1 つの場所(Places API で定義されます)に対応します。
Autocomplete
コンストラクタは次の 2 つの引数を取ります。
- タイプが
text
の HTMLinput
要素。これは、オートコンプリート サービスが監視し、結果を付加する入力フィールドです。 - 省略可能な
AutocompleteOptions
引数。次の 2 つのプロパティを含めることができます。- ユーザーが選択した
PlaceResult
のPlace Details
レスポンスに含まれるデータ配列fields
。プロパティが設定されていない場合、または['ALL']
が渡された場合は、使用可能なフィールドがすべて返され、課金されます(本番環境のデプロイでは推奨されません)。フィールドの一覧については、PlaceResult
をご覧ください。 types
の配列には、サポートされるタイプに記載されているタイプやタイプ コレクションを明示的に指定します。タイプを指定しない場合は、すべてのタイプが返されます。bounds
は、場所検索の対象領域を指定するgoogle.maps.LatLngBounds
オブジェクトです。この境界内に含まれる場所が優先されますが、これに限定されません。strictBounds
は、bounds
で定義された領域内の場所のみを API が返す必要があるかどうかを指定するboolean
です。この領域外の場所は、ユーザー入力と一致しても結果に含まれません。componentRestrictions
を使用すると、特定のグループに結果を制限できます。現在は、componentRestrictions
を使用して最大 5 つの国に結果を絞り込むことができます。国は、ISO 3166-1 Alpha-2 に準拠した 2 文字の国コードで指定してください。複数の国は、国コードのリストとして渡す必要があります。注: 国コードを使用して予期しない結果が返される場合は、対象の国や属領、地理的に重要な特別な地域を含むコードを使用しているか確認してください。コードの情報については、Wikipedia の ISO 3166 国コードのリストか、ISO オンライン参照プラットフォームをご覧ください。
placeIdOnly
を使って、場所 ID のみを取得するようAutocomplete
ウィジェットに指示できます。Autocomplete
オブジェクトでgetPlace()
を呼び出すと、利用可能なPlaceResult
にplace id
、types
、name
プロパティのみが設定されます。返された場所 ID を使用して、プレイス、ジオコーディング、ルート、距離行列サービスへの呼び出しを実行できます。
- ユーザーが選択した
オートコンプリート候補の制限
デフォルトでは、Place Autocomplete はすべてのタイプの場所を表示します。ユーザーの現在地に近い予測を優先し、ユーザーが選択した場所について利用可能なすべてのデータ フィールドを取得します。ユースケースに合わせ、より関連性の高い候補を提示するように Place Autocomplete オプションを設定しましょう。
作成時にオプションを設定
Autocomplete
コンストラクタは、ウィジェット作成時に AutocompleteOptions
パラメータを受け取って制約を設定します。次の例では、bounds
、componentRestrictions
、types
オプションで、establishment
タイプの場所をリクエストし、指定された地理的領域内の場所を優先して、予測を米国内の場所のみに制限するよう設定しています。fields
オプションを設定して、ユーザーの選択した場所について返す情報を指定できます。
既存のウィジェットのオプションの値を変更するには、setOptions()
を呼び出します。
TypeScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input") as HTMLInputElement; const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, types: ["establishment"], }; const autocomplete = new google.maps.places.Autocomplete(input, options);
JavaScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input"); const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, types: ["establishment"], }; const autocomplete = new google.maps.places.Autocomplete(input, options);
データ フィールドを指定する
不要なプレイスデータの SKU で料金が発生しないように、データ フィールドを指定します。上記の例のように、ウィジェットのコンストラクタに渡される AutocompleteOptions
に fields
プロパティを含めるか、既存の Autocomplete
オブジェクトで setFields()
を呼び出します。
autocomplete.setFields(["place_id", "geometry", "name"]);
オートコンプリートのバイアスと検索範囲の境界を設定する
次の方法でオートコンプリートの結果にバイアスをかけて、特定の場所の周辺や範囲を優先させることができます。
Autocomplete
オブジェクトの作成時に境界を設定します。- 既存の
Autocomplete
の境界を変更します。 - 地図のビューポートに境界を設定します。
- 検索対象を境界内に制限します。
- 検索対象を特定の国に制限します。
上記の例では、作成時に境界を設定しています。次の例では、その他のバイアスの設定方法を説明します。
既存のオートコンプリートの境界を変更する
setBounds()
を呼び出して、既存の Autocomplete
の検索領域を矩形の境界に変更します。
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
地図のビューポートに境界を設定する
bindTo()
を使用して、地図のビューポート内の結果を優先します。ビューポートが変更されても同様です。
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
unbind()
を使用すると、オートコンプリート候補を地図のビューポートに制限しないよう設定できます。
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
検索対象を現在の境界内に制限する
strictBounds
オプションを設定すると、地図のビューポートまたは矩形の境界に基づいて、現在の境界内に結果を制限できます。
autocomplete.setOptions({ strictBounds: true });
予測を特定の国に制限する
componentRestrictions
オプションを使用するか setComponentRestrictions()
を呼び出すと、オートコンプリートの検索対象を最大 5 か国に制限できます。
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
場所のタイプを制限する
types
オプションを使用するか setTypes()
を呼び出すと、予測を特定のタイプの場所に制限できます。この制限は、プレイスタイプに記載されているタイプまたはタイプのコレクションを指定するものです。制限を指定しない場合は、すべてのタイプが返されます。
types
オプションの値や setTypes()
に渡す値には、次のいずれかを指定できます。
プレイスタイプの表 1 または表 2 の値を最大 5 つ含む配列。たとえば次のようになります。
types: ['hospital', 'pharmacy', 'bakery', 'country']
または次のようになります。
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- プレイスタイプの表 3 のフィルタのいずれか 1 つ。表 3 の値は 1 つしか指定できません。
次の場合はリクエストが拒否されます。
Places Autocomplete のデモでは、場所のタイプによって予測がどのように異なるのかを説明しています。
場所の情報を取得する
オートコンプリートのテキスト フィールドに表示される候補からユーザーが場所を 1 つ選択すると、サービスにより place_changed
イベントが発生します。Place Details を取得する手順は次のとおりです。
place_changed
イベントのイベント ハンドラを作成し、Autocomplete
オブジェクトでaddListener()
を呼び出してそのハンドラを追加します。Autocomplete
オブジェクトでAutocomplete.getPlace()
を呼び出し、PlaceResult
オブジェクトを取得します。このオブジェクトを使用して、選択された場所に関する詳細な情報を取得できます。
デフォルトでは、ユーザーが場所を選択すると、選択した場所で利用可能なすべてのデータ フィールドがオートコンプリートによって返され、それに応じた料金が発生します。
場所に関するどのデータ フィールドを返すかは、Autocomplete.setFields()
を使用して指定します。リクエスト可能な場所のデータ フィールドの一覧など、PlaceResult
オブジェクトの詳細をご確認ください。不要なデータで料金が発生しないように、Autocomplete.setFields()
を呼び出して、使用する場所データのみを指定してください。
name
プロパティには、Place Autocomplete の予測に基づく description
が含まれます。description
の詳細については、Places Autocomplete のドキュメントをご覧ください。
住所フォームでは、住所を体系化された形式で取得すると便利です。選択した場所の体系化された住所を返すには、Autocomplete.setFields()
を呼び出して、address_components
フィールドを指定します。
次の例では、オートコンプリートを使用して住所フォームのフィールドに情報を入力しています。
TypeScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": (document.querySelector("#locality") as HTMLInputElement).value = component.long_name; break; case "administrative_area_level_1": { (document.querySelector("#state") as HTMLInputElement).value = component.short_name; break; } case "country": (document.querySelector("#country") as HTMLInputElement).value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); }
JavaScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": document.querySelector("#locality").value = component.long_name; break; case "administrative_area_level_1": { document.querySelector("#state").value = component.short_name; break; } case "country": document.querySelector("#country").value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); } window.initAutocomplete = initAutocomplete;
プレースホルダ テキストをカスタマイズする
デフォルトでは、オートコンプリート サービスにより作成されるテキスト フィールドには、標準のプレースホルダ テキストが含まれています。テキストを変更するには、input
要素の placeholder
属性を設定します。
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
注: デフォルトのプレースホルダ テキストは、自動的にローカライズされます。独自のプレースホルダ値を指定した場合は、アプリケーションでその値のローカライズを処理する必要があります。Google Maps JavaScript API が使用言語をどのように選択するかについては、ローカライズに関するドキュメントをご覧ください。
ウィジェットの外観をカスタマイズする方法については、Autocomplete および SearchBox ウィジェットのスタイルを設定するをご覧ください。
検索ボックス ウィジェットを追加する
SearchBox
では、ユーザーは「カフェ 横浜」、「四条付近の靴屋」のようなテキストによる地理的検索を実行できます。この SearchBox
をテキスト フィールドに追加できます。テキストの入力中に、サービスによって、プルダウンの選択リストとして予測が返されます。
SearchBox
では、予測の拡張リストを提供します。これには Places API で定義される場所に加えて、検索キーワードの候補が含まれます。たとえば、ユーザーが「東京のピ」まで入力すると、ピックリストには「東京のピザ屋」という語句が含まれ、さらにさまざまなピザ販売店の名前が含まれます。ユーザーがリストから場所を選択すると、その場所の情報が SearchBox オブジェクトに返され、アプリケーションによる取得が可能になります。
SearchBox
コンストラクタは次の 2 つの引数を取得します。
- タイプが
text
の HTMLinput
要素。これは、SearchBox
サービスが監視し、結果を付加する入力フィールドです。 bounds
プロパティを含めることができるoptions
引数。bounds
は、場所を検索する領域を指定するgoogle.maps.LatLngBounds
オブジェクトです。この領域内に含まれる場所が優先されますが、これに限定されません。
次のコードは、境界パラメータを使用して、緯度 / 経度座標で指定された特定の地理範囲に含まれる場所を優先する形で、結果を返します。
var defaultBounds = new google.maps.LatLngBounds( new google.maps.LatLng(-33.8902, 151.1759), new google.maps.LatLng(-33.8474, 151.2631)); var input = document.getElementById('searchTextField'); var searchBox = new google.maps.places.SearchBox(input, { bounds: defaultBounds });
SearchBox の検索範囲を変更する
既存の SearchBox
の検索範囲を変更するには、SearchBox
オブジェクトで setBounds()
を呼び出し、関連する LatLngBounds
オブジェクトを渡します。
場所の情報を取得する
検索ボックスに表示された予測の中からユーザーが項目を選択すると、サービスにより places_changed
イベントが発生します。SearchBox
オブジェクトで getPlaces()
を呼び出すと、複数の予測を含む配列を取得できます。この予測はそれぞれ PlaceResult
オブジェクトです。
PlaceResult
オブジェクトについて詳しくは、Place Details の結果に関するドキュメントをご覧ください。
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon as string, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }) ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
JavaScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }) ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
ウィジェットの外観をカスタマイズする方法については、Autocomplete および SearchBox ウィジェットのスタイルを設定するをご覧ください。
プログラムによって Place Autocomplete サービスの予測を取得する
プログラムによって予測を取得するには、AutocompleteService
クラスを使用します。AutocompleteService
で追加される UI コントロールはありません。その代わり、予測オブジェクトの配列が返されます。各予測オブジェクトには、予測のテキスト、参照情報、ユーザーの入力にどのように結果が一致したかについての詳細情報が含まれます。これらは、前述の Autocomplete
や SearchBox
で提供されるコントロールよりも、UI をさらに細かくコントロールしたい場合に便利です。
AutocompleteService
は、次のメソッドを公開します。
getPlacePredictions()
は、場所の予測を返します。注: 「場所」とは、Places API で定義されるように、施設、地理的位置、有名なスポットなどを指します。getQueryPredictions()
は拡張された予測リストを返します。これには Places API で定義される場所に加えて、検索語句の候補を含めることができます。たとえば、ユーザーが「東京のピ」まで入力すると、選択リストには「東京のピザ屋」という語句が含まれ、さらにさまざまなピザ販売店の名前が含まれます。
上記のメソッドではどちらも、以下の形式の予測オブジェクトの配列が返されます。
description
は一致する予測です。distance_meters
は、指定されたAutocompletionRequest.origin
からの場所までの距離(メートル単位)です。matched_substrings
には、ユーザーの入力要素と一致する、description 内の一連の部分文字列が含まれます。これは、アプリケーションでこれらの部分文字列をハイライト表示する場合に有用です。多くの場合、検索語句は description フィールドの 1 つの部分文字列として表示されます。length
は部分文字列の長さです。offset
は、一致する部分文字列が表示される description 文字列の先頭から計測された文字オフセットです。
place_id
は場所を一意に識別するテキスト表記の ID です。場所に関する情報を取得するには、この ID を Place Details リクエストのplaceId
フィールドに渡します。詳しくは、場所 ID を使って場所を参照する方法をご覧ください。terms
は検索語句の要素を含む配列です。場所の場合、通常は各要素は住所の一部分となります。offset
は、一致する部分文字列が表示される description 文字列の先頭から計測された文字オフセットです。value
は一致する語句です。
下の例は、「pizza near」という検索語句の予測リクエストを実行し、結果をリストに表示します。
TypeScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService(): void { const displaySuggestions = function ( predictions: google.maps.places.QueryAutocompletePrediction[] | null, status: google.maps.places.PlacesServiceStatus ) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); (document.getElementById("results") as HTMLUListElement).appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } declare global { interface Window { initService: () => void; } } window.initService = initService;
JavaScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService() { const displaySuggestions = function (predictions, status) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); document.getElementById("results").appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } window.initService = initService;
CSS
HTML
<html> <head> <title>Retrieving Autocomplete Predictions</title> <script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=default"></script> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <p>Query suggestions for 'pizza near Syd':</p> <ul id="results"></ul> <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements --> <img class="powered-by-google" src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png" alt="Powered by Google" /> <!-- The `defer` attribute causes the callback to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises with https://www.npmjs.com/package/@googlemaps/js-api-loader. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly" defer ></script> </body> </html>
サンプルを試す
セッション トークン
AutocompleteService.getPlacePredictions()
はセッション トークンを使用し、請求処理のためにオートコンプリート リクエストをグループ化します。セッション トークンは、オートコンプリート検索でのユーザーの検索語句と選択フェーズを、請求処理のために個別のセッションにグループ化します。セッションは、ユーザーが検索語句を入力し始めたときに開始され、ユーザーが場所を選択すると終了します。セッションによっては、複数の検索語句が入力された後に、1 つの場所が選択される場合もあります。セッションが終了すると、トークンは無効になります。アプリでは、セッションごとに新しいトークンを生成する必要があります。すべてのオートコンプリート セッションでセッション トークンを使用することをおすすめします。sessionToken
パラメータを省略する場合や、セッション トークンを再利用する場合は、セッション トークンが指定されていない場合と同様にセッションが課金されます(各リクエストが個別に課金されます)。
同じセッション トークンを使用して、AutocompleteService.getPlacePredictions()
の呼び出しによって返された場所に対して、単一の Place Details リクエストを実行できます。この場合、オートコンプリート リクエストは Place Details リクエストと統合され、呼び出しは、通常の Place Details リクエストとして課金されます。オートコンプリート リクエストは無料です。
新しいセッションごとに固有のセッション トークンを渡すようにしてください。複数の Autocomplete セッションで同じトークンを使用すると、それらの Autocomplete セッションは無効になります。無効なセッションでは、Autocomplete - Per Request SKU を基に、すべての Autocomplete リクエストが個別に課金されます。セッション トークンの詳細
次の例では、セッション トークンを作成して AutocompleteService
に渡しています(簡潔にするために displaySuggestions()
関数は省略しています)。
// Create a new session token. var sessionToken = new google.maps.places.AutocompleteSessionToken(); // Pass the token to the autocomplete service. var autocompleteService = new google.maps.places.AutocompleteService(); autocompleteService.getPlacePredictions({ input: 'pizza near Syd', sessionToken: sessionToken }, displaySuggestions);
新しいセッションごとに固有のセッション トークンを渡すようにしてください。複数のセッションで同じセッションを使用すると、リクエストごとに課金されます。
Autocomplete と SearchBox ウィジェットのスタイルを設定する
デフォルトでは、Autocomplete
と SearchBox
によって提供される UI 要素は、Google マップに含めるようにスタイルが設定されます。ご自分のサイトに合わせて、スタイルを変更することをおすすめします。以下の CSS クラスを利用できます。下記のすべてのクラスは、Autocomplete
ウィジェットと SearchBox
ウィジェットの両方に適用されます。
CSS クラス | 説明 |
---|---|
pac-container |
Place Autocomplete サービスによって返される予測のリストを含む視覚要素。このリストは、Autocomplete または SearchBox ウィジェットの下にプルダウン リストとして表示されます。 |
pac-icon |
予測リスト内の各項目の左に表示されるアイコン。 |
pac-item |
Autocomplete または SearchBox ウィジェットによって表示される予測リスト内の項目。 |
pac-item:hover |
ユーザーがマウスポインタを合わせたときの項目。 |
pac-item-selected |
ユーザーがキーボードから選択したときの項目。注: 選択した項目は、このクラスと pac-item クラスのメンバーになります。
|
pac-item-query |
pac-item 内の予測の主要部分。地理的位置の検索の場合、ここには「シドニー」などの場所の名前、または「キングストリート 10」などの市町村と番地が含まれます。「東京のピザ屋」などのテキスト検索の場合、検索語句の全テキストが含まれます。デフォルトでは、pac-item-query の色は黒です。pac-item に追加のテキストがある場合、そのテキストは pac-item-query 以外となり、pac-item のスタイルを継承します。デフォルトでは色はグレーになります。この追加のテキストは通常、住所です。 |
pac-matched |
返される予測のうち、ユーザーの入力に一致する部分。デフォルトでは、この一致テキストは太字でハイライト表示されます。一致テキストは pac-item 内の任意の場所に存在します。pac-item-query に含まれるとは限らず、一部が pac-item-query 内にある場合や、一部が pac-item 内の他のテキスト内にある場合もあります。 |
Place Autocomplete の最適化
このセクションでは、Place Autocomplete サービスを最大限に活用するためのヒントを紹介します。
概要は次のとおりです。
- 機能的なユーザー インターフェースを最も手早く作成するには、Maps JavaScript API Autocomplete ウィジェット、Places SDK for Android Autocomplete ウィジェット、または Places SDK for iOS Autocomplete UI コントロールを使用します。
- Place Autocomplete のデータ フィールドの基本を理解します。
- 位置情報のバイアスと位置情報の制限のフィールドは省略可能ですが、オートコンプリートのパフォーマンスに大きく影響する場合があります。
- エラー処理を使用して、API がエラーを返した場合に、アプリでグレースフル デグラデーションが行われるようにします。
- アプリでは、選択肢がない場合でもユーザーが操作を続行できるようにします。
費用の最適化に関するヒント
基本的な費用の最適化
Place Autocomplete サービスの費用を最適化するには、Place Details と Place Autocomplete ウィジェットのフィールド マスクを使用して、必要な場所のデータ フィールドのみを返すよう設定します。
高度な費用の最適化
リクエストあたりの料金設定を利用し、Place Details の代わりに選択された場所に関する Geocoding API の結果をリクエストするためには、Place Autocomplete のプログラマティック実装を行うことをおすすめします。次の両方に該当する場合は、リクエストあたりの料金設定と Geocoding API を組み合わせた方が、セッションあたり(セッション ベース)の料金設定よりも費用対効果が高くなります。
- ユーザーが選択した場所の緯度 / 経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details の呼び出しよりも少ないコストでこの情報を提供できます。
- ユーザーが予測結果を選択するまでのオートコンプリート候補リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。
アプリケーションで、選択された予測結果の住所と緯度 / 経度以外の情報が必要ですか?
はい。その他の情報も必要です
セッション ベースの Place Autocomplete と Place Details を併用します。
アプリケーションで、場所の名前、お店やサービスのステータス、始業時間などの Place Details が必要になるため、Place Autocomplete 実装では、セッション トークン(プログラマティック実装か、JavaScript、Android、または iOS ウィジェットへの組み込み)を使用することをおすすめします。合計では、セッションあたり 0.017 ドルに加え、リクエストするデータ フィールドに応じた対象のプレイスデータ SKU の費用がかかります。1
ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete リクエストと Place Details リクエストの両方が含まれます。必要なプレイスデータ フィールドのみをリクエストするように、必ず fields
パラメータを指定してください。
プログラマティック実装
Place Autocomplete リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details をリクエストする際は、次のパラメータを含めます。
- Place Autocomplete レスポンスの場所 ID
- Place Autocomplete リクエストで使用されるセッション トークン
- 必要な場所のデータ フィールドを指定する
fields
パラメータ
いいえ。住所と場所のみが必要です
Place Autocomplete 使用時のパフォーマンスによっては、アプリケーションで Places Details を使用するよりも、Geocoding API を使用した方が費用対効果が高くなる場合があります。アプリケーションのオートコンプリートの効率は、ユーザーの入力内容や、アプリケーションが使用される場所、パフォーマンス最適化のベスト プラクティスが導入されているかどうかによって変わります。
次の質問に答えるためには、ユーザーがアプリケーション内で Place Autocomplete の予測を選択するまでに、平均でどのくらいの文字数を入力するのかを分析する必要があります。
ユーザーが Place Autocomplete の予測を選択するまでに実行されるリクエスト数は、平均で 4 回以下ですか?
はい
セッション トークンを使用せずにプログラムによって Place Autocomplete を実装し、選択された場所の予測で Geocoding API を呼び出します。
Geocoding API は、リクエスト 1 件につき 0.005 ドルで住所と緯度 / 経度の座標が提供されます。Place Autocomplete - Per Request のリクエスト 4 件の料金は 0.01132 ドルになるため、4 件のリクエストと、選択された場所予測に関する Geocoding API の呼び出しを合わせた料金は、0.01632 ドルになります。これは、Per Session Autocomplete でのセッション 1 回あたりの料金 0.017 ドルよりも少ないコストです。1
パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める情報を提供できるようすることをおすすめします。
いいえ
セッション ベースの Place Autocomplete と Place Details を併用します。
ユーザーが Place Autocomplete の予測を選択するまでの平均リクエスト回数が、セッションあたりの料金を超えるため、Place Autocomplete 実装では、Place Autocomplete リクエストと、関連する Place Details リクエストの両方でセッション トークンを使用することをおすすめします(合計費用はセッションあたり 0.017 ドル)。1
ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete リクエストと Place Details リクエストの両方が含まれます。基本データ フィールドのみをリクエストするように、必ず fields
パラメータを指定してください。
プログラマティック実装
Place Autocomplete リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details をリクエストする際は、次のパラメータを含めます。
- Place Autocomplete レスポンスの場所 ID
- Place Autocomplete リクエストで使用されるセッション トークン
- 住所やジオメトリなどの基本データ フィールドを指定する
fields
パラメータ
Place Autocomplete リクエストを遅らせることを検討する
ユーザーが最初の 3~4 文字を入力するまで Place Autocomplete リクエストを遅らせて、アプリケーションでのリクエスト数を減らすこともできます。たとえば、ユーザーが 3 文字目を入力してから、1 文字ごとに Place Autocomplete リクエストを行うとします。あるユーザーが、7 文字目を入力してから予測を選択し、Geocoding API リクエストが 1 回実行されました。この場合の合計費用は、0.01632 ドル(4 x Autocomplete Per Request 1 回の料金 0.00283 ドル + ジオコーディング 1 回の料金 0.005 ドル)となります。1
リクエストを遅らせることで、プログラマティック リクエストの回数を平均 4 回以下に抑えられる場合は、高パフォーマンスで Place Autocomplete と Geocoding API を併用する実装に関するガイダンスをご覧ください。なお、リクエストを遅らせると、1 文字入力するたびに予測が表示されはずと考えているユーザーには、遅延と受けとられる場合もあります。
パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める情報を提供できるようすることをおすすめします。
-
ここで提示されている料金は米ドルです。料金について詳しくは、Google Maps Platform の課金のページをご覧ください。
パフォーマンスに関するベスト プラクティス
Place Autocomplete のパフォーマンスを最適化するためのガイドラインは次のとおりです。
- Place Autocomplete 実装に、国別のポリシー、場所のバイアス、言語設定(プログラマティック実装の場合)を追加します。ウィジェットはユーザーのブラウザやモバイル デバイスから言語設定を選択するため、ウィジェットでは言語設定は不要です。
- Place Autocomplete が地図に関連付けられている場合は、地図のビューポートを基準に場所にバイアスをかけることができます。
- ユーザーがいずれかのオートコンプリート候補を選択しなかった場合は(通常は目的の住所が候補に挙がらなかったことが原因)、ユーザーの元の入力内容を再利用して、より関連性の高い結果を取得できます。
- ユーザーが住所情報のみを入力することが予想される場合は、Geocoding API の呼び出しで、ユーザーの元の入力内容を再利用します。
- ユーザーが特定の場所に関する検索語句(名前や住所)を入力することが予想される場合は、Find Place リクエストを使用します。特定の地域の結果のみが求められる場合は、場所のバイアスを使用します。
- ユーザーがオーストラリア、ニュージーランド、カナダ以外の国で、建物の棟の住所を入力する場合。たとえば、米国の住所の「123 Bowdoin St #456, Boston MA, USA」はオートコンプリートではサポートされません(オートコンプリートがサポートしているのは、オーストラリア、ニュージーランド、カナダにある建物の棟の住所のみです。この 3 か国では、「9/321 Pitt Street, Sydney, New South Wales, Australia」、「14/19 Langana Avenue, Browns Bay, Auckland, New Zealand」、「145-112 Renfrew Dr, Markham, Ontario, Canada」などの形式の住所がサポートされます)。
- ユーザーがニューヨークの「23-30 29th St, Queens」や、ハワイのカウアイ島の「47-380 Kamehameha Hwy, Kaneohe」など、道路区間のプレフィックスを入力する場合。
使用制限とポリシー
割り当て
割り当てと料金については、Places API の使用量と料金に関するドキュメントをご覧ください。
ポリシー
Maps JavaScript API のプレイス ライブラリを使用する場合は、Places API に関するポリシーを遵守する必要があります。
利用規約から
必要な
ロゴと帰属を表示する
Google の著作権と帰属に配慮します。ロゴと著作権に関する通知を必ず表示してください。また、地図なしでデータを使用する場合は、「powered by Google」のロゴを表示してください。