Place Autocomplete

はじめに

予測入力は、Maps JavaScript API のプレイス ライブラリの機能です。予測入力を使用すると、Google マップの検索フィールドの逐次検索機能をアプリケーションに組み込むことができます。予測入力サービスは、完全な単語や部分文字列を照合して、場所の名前や住所、Plus Codes を解決できます。これにより、アプリケーションはユーザーが入力を始めるとクエリを送信し、候補となる場所を即座に返すことができます。Places API で定義されているように、「場所」とは、施設、地理的位置、有名なスポットなどを指します。

スタートガイド

Maps JavaScript API でプレイス ライブラリを使用する前に、Maps JavaScript API を設定した同じプロジェクトで、Places API が Google Cloud コンソールで有効になっていることを確認します。

有効な API のリストを表示するには:

1. Google Cloud コンソールに移動します。
2. [プロジェクトを選択] ボタンをクリックし、Maps JavaScript API を設定した同じプロジェクトを選択して、[開く] をクリックします。
3. [ダッシュボード] の API のリストから、Places API を探します。
4. リストに API が表示されていれば、準備は完了です。ただし、このプロジェクトは Legacy ステータスです。レガシー ステージとレガシーから新しいサービスへの移行方法については、レガシー プロダクトと機能をご覧ください。Autocomplete ウィジェットと SearchBox ウィジェットは例外で、Places API（新版）の GA プロダクトとしてはまだ利用できません。

ライブラリを読み込む

プレイス サービスは、メインの Maps JavaScript API コードとは別の自己完結型のライブラリです。このライブラリにある機能を利用するには、最初に Maps API ブートストラップ URL の libraries パラメータを使用してライブラリを読み込む必要があります。

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&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 の HTML input 要素。これは、予測入力サービスが監視し、結果を付加する入力フィールドです。
• 省略可能な AutocompleteOptions 引数。次のプロパティを含めることができます。
  • fields: ユーザーが選択した PlaceResult の Place Details レスポンスに含めるべきデータ フィールドの配列。プロパティが設定されていない場合、または ['ALL'] が渡された場合は、使用可能なフィールドがすべて返され、課金されます（本番環境のデプロイでは推奨されません）。フィールドの一覧は、PlaceResult で確認できます。
  • types: 明示的なタイプまたはタイプ コレクションを指定する配列（サポートされるタイプも参照）。タイプを指定しない場合は、すべてのタイプが返されます。
  • bounds: 候補として表示する場所の検索対象領域を指定する google.maps.LatLngBounds オブジェクト。表示する候補のバイアス（優先扱い）の指定であり、指定領域外の場所が除外されるわけではありません。
  • strictBounds: API が返す候補を、bounds で指定した領域に厳密に含まれる場所のみに限定するかどうかを指定する boolean 値です。有効にした場合、指定領域外の場所は、たとえユーザーの入力内容と一致していても返されません。
  • componentRestrictions: 表示する候補を、特定のグループ内に含まれる場所に限定します。componentRestrictions を使用して、最大 5 つの国に結果を絞り込むことができます。国は、ISO 3166-1 Alpha-2 に準拠した 2 文字の国コードで指定してください。複数の国は、国コードのリストとして渡す必要があります。

    注: 国コードを使用して予期しない結果が返される場合は、対象の国や属領、地理的に重要な特別な地域を含むコードを使用しているか確認してください。コードの情報については、Wikipedia の ISO 3166 国コードのリストか、ISO オンライン参照プラットフォームをご覧ください。

  • placeIdOnly: プレイス ID だけを取得するよう、Autocomplete ウィジェットに指示します。有効にした場合、Autocomplete オブジェクトで getPlace() を呼び出した際、place id、types、name の各プロパティだけを設定された PlaceResult が提供されます。返されたプレイス ID は、プレイス、ジオコーディング、ルート、距離行列といったサービスの呼び出しに使用できます。

予測入力候補を制限する

デフォルトでは、Place Autocomplete はすべてのタイプの場所を表示します。ユーザーの現在地に近い予測を優先し、ユーザーが選択した場所について利用可能なすべてのデータ フィールドを取得します。ユースケースに合わせ、より関連性の高い候補を提示するように Place Autocomplete オプションを設定しましょう。

作成時にオプションを設定する

Autocomplete コンストラクタは、ウィジェット作成時に AutocompleteOptions パラメータを受け取って制約を設定します。次の例では、bounds、componentRestrictions、types オプションで、establishment タイプの場所をリクエストし、指定された地理的領域内の場所を優先して、予測を米国内の場所のみに制限するよう設定しています。fields オプションを設定して、ユーザーの選択した場所について返す情報を指定できます。

既存のウィジェットのオプションの値を変更するには、setOptions() を呼び出します。

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,
};

const autocomplete = new google.maps.places.Autocomplete(input, options);
index.ts

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,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
index.js

データ フィールドを指定する

不要なプレイスデータの SKU で料金が発生しないように、データ フィールドを指定します。上記の例のように、ウィジェットのコンストラクタに渡される AutocompleteOptions に fields プロパティを含めるか、既存の Autocomplete オブジェクトで setFields() を呼び出します。

autocomplete.setFields(["place_id", "geometry", "name"]);

予測入力のバイアスと検索範囲の境界を設定する

次の方法で予測入力の結果にバイアスをかけて、特定の場所の周辺や範囲を優先させることができます。

• Autocomplete オブジェクトの作成時に境界を設定します。
• 既存の Autocomplete の境界を変更します。
• 地図のビューポートに境界を設定します。
• 検索対象を境界内に制限します。
• 検索対象を特定の国に制限します。

上記の例では、作成時に境界を設定しています。次の例では、その他のバイアスの設定方法を説明します。

既存の予測入力の境界を変更する

setBounds() を呼び出して、既存の Autocomplete の検索領域を矩形の境界に変更します。

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);
index.ts

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);
index.js

地図のビューポートに境界を設定する

bindTo() を使用して、地図のビューポート内の結果を優先します。ビューポートが変更されても同様です。

autocomplete.bindTo("bounds", map);
index.ts

autocomplete.bindTo("bounds", map);
index.js

unbind() を使用すると、予測入力候補を地図のビューポートに制限しないよう設定できます。

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.ts

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.js

サンプルを表示

検索対象を現在の境界内に制限する

strictBounds オプションを設定すると、地図のビューポートまたは矩形の境界に基づいて、現在の境界内に結果を制限できます。

autocomplete.setOptions({ strictBounds: true });

予測を特定の国に制限する

componentRestrictions オプションを使用するか setComponentRestrictions() を呼び出すと、予測入力の検索対象を最大 5 か国に制限できます。

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.ts

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.js

サンプルを表示

場所のタイプを制限する

types オプションを使用するか setTypes() を呼び出すと、予測を特定のタイプの場所に制限できます。この制限は、プレイスタイプに記載されているタイプまたはタイプのコレクションを指定するものです。制限を指定しない場合は、すべてのタイプが返されます。

types オプションの値や setTypes() に渡す値には、次のいずれかを指定できます。

• プレイスタイプの表 1 または表 2 の値を最大 5 つ含む配列。たとえば次のようになります。

  types: ['hospital', 'pharmacy', 'bakery', 'country']

  または次のようになります。

  autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);

• プレイスタイプの表 3 のフィルタのいずれか 1 つ。表 3 の値は 1 つしか指定できません。

次の場合はリクエストが拒否されます。

• 指定したタイプの数が 5 個より多い。
• 認識できないタイプを指定している。
• 表 1 または表 2 のタイプと、表 3 のフィルタが混在している。

Places Autocomplete のデモでは、場所のタイプによって予測がどのように異なるのかを説明しています。

デモを見る

場所の情報を取得する

予測入力のテキスト フィールドに表示される候補からユーザーが場所を 1 つ選択すると、サービスにより place_changed イベントが発生します。Place Details を取得する手順は次のとおりです。

1. place_changed イベントのイベント ハンドラを作成し、Autocomplete オブジェクトで addListener() を呼び出してそのハンドラを追加します。
2. Autocomplete オブジェクトで Autocomplete.getPlace() を呼び出し、PlaceResult オブジェクトを取得します。このオブジェクトを使用して、選択された場所に関する詳細な情報を取得できます。

デフォルトでは、ユーザーが場所を選択すると、選択した場所で利用可能なすべてのデータ フィールドが予測入力によって返され、それに応じた料金が発生します。 場所に関するどのデータ フィールドを返すかは、Autocomplete.setFields() を使用して指定します。リクエスト可能な場所のデータ フィールドの一覧など、PlaceResult オブジェクトの詳細をご確認ください。不要なデータで料金が発生しないように、Autocomplete.setFields() を呼び出して、使用する場所データのみを指定してください。

name プロパティには、Place Autocomplete の予測に基づく description が含まれます。description の詳細については、Places Autocomplete のドキュメントをご覧ください。

住所フォームでは、住所を体系化された形式で取得すると便利です。選択した場所の体系化された住所を返すには、Autocomplete.setFields() を呼び出して、address_components フィールドを指定します。

次の例では、予測入力を使用して住所フォームのフィールドに情報を入力しています。

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();
}
index.ts

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;
index.js

サンプルを表示

プレースホルダ テキストをカスタマイズする

デフォルトでは、予測入力サービスにより作成されるテキスト フィールドには、標準のプレースホルダ テキストが含まれています。テキストを変更するには、input 要素の placeholder 属性を設定します。

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

注: デフォルトのプレースホルダ テキストは、自動的にローカライズされます。独自のプレースホルダ値を指定した場合は、アプリケーションでその値のローカライズを処理する必要があります。Google Maps JavaScript API が使用言語をどのように選択するかについては、 ローカライズに関するドキュメントをご覧ください。

ウィジェットの外観をカスタマイズする方法については、Autocomplete および SearchBox ウィジェットのスタイルを設定するをご覧ください。

SearchBox ウィジェットを追加する

SearchBox では、ユーザーは「カフェ 横浜」、「四条付近の靴屋」のようなテキストによる地理的検索を実行できます。この SearchBox をテキスト フィールドに追加できます。テキストの入力中に、サービスによって、プルダウンの選択リストとして予測が返されます。

SearchBox では、予測の拡張リストを提供します。これには Places API で定義される場所に加えて、検索キーワードの候補が含まれます。たとえば、ユーザーが「東京のピ」まで入力すると、ピックリストには「東京のピザ屋」という語句が含まれ、さらにさまざまなピザ販売店の名前が含まれます。ユーザーがリストから場所を選択すると、その場所の情報が SearchBox オブジェクトに返され、アプリケーションによる取得が可能になります。

SearchBox コンストラクタは次の 2 つの引数を取得します。

• タイプが text の HTML input 要素。これは、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 の結果に関するドキュメントをご覧ください。

// 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);
});
index.ts

// 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);
});
index.js

サンプルを表示

ウィジェットの外観をカスタマイズする方法については、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」という検索語句の予測リクエストを実行し、結果をリストに表示します。

// 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;
index.ts

// 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;
index.js

style.css

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <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 script 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. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.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 ウィジェットの両方に適用されます。

Place Autocomplete（従来版）の最適化

このセクションでは、Place Autocomplete（以前のバージョン）サービスを最大限に活用するためのヒントを紹介します。

概要は次のとおりです。

• 機能的なユーザー インターフェースを最も手早く作成するには、Maps JavaScript API Place Autocomplete（以前のバージョン）ウィジェット、Places SDK for Android Place Autocomplete（以前のバージョン）ウィジェット、または Places SDK for iOS Place Autocomplete（以前のバージョン）UI コントロールを使用します。
• Place Autocomplete（従来版）のデータ フィールドの基本を理解します。
• 位置情報のバイアスと位置情報の制限のフィールドは省略可能ですが、予測入力のパフォーマンスに大きく影響する場合があります。
• エラー処理を使用して、API がエラーを返した場合に、アプリでグレースフル デグラデーションが行われるようにします。
• アプリでは、選択肢がない場合でもユーザーが操作を続行できるようにします。

費用の最適化に関するヒント

基本的な費用の最適化

Place Autocomplete（Legacy）サービスの費用を最適化するには、Place Details（Legacy）と Place Autocomplete（Legacy）ウィジェットのフィールド マスクを使用して、必要な場所のデータ フィールドのみを返すよう設定します。

高度な費用の最適化

リクエストあたりの料金設定を利用し、Place Details（Legacy）の代わりに選択された場所に関する Geocoding API の結果をリクエストするためには、Place Autocomplete（Legacy）のプログラマティック実装を行うことをおすすめします。次の両方に該当する場合は、リクエストあたりの料金設定と Geocoding API を組み合わせた方が、セッションあたり（セッション ベース）の料金設定よりも費用対効果が高くなります。

• ユーザーが選択した場所の緯度/経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details（レガシー）の呼び出しよりも少ないコストでこの情報を提供できます。
• ユーザーが予測結果を選択するまでの Place Autocomplete（レガシー）予測入力候補リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。

アプリケーションで、選択された予測結果の住所と緯度 / 経度以外の情報が必要ですか？

パフォーマンスに関するベスト プラクティス

Place Autocomplete（レガシー）のパフォーマンスを最適化するためのガイドラインは次のとおりです。

• Place Autocomplete（従来版）実装に、国別のポリシー、場所のバイアス、言語設定（プログラマティック実装の場合）を追加します。ウィジェットはユーザーのブラウザやモバイル デバイスから言語設定を選択するため、ウィジェットでは言語設定は不要です。
• Place Autocomplete（従来版）が地図に関連付けられている場合は、地図のビューポートを基準に場所にバイアスをかけることができます。
• ユーザーが Place Autocomplete（従来版）の予測入力候補を選択しなかった場合は（通常は目的の住所が候補に挙がらなかったことが原因）、ユーザーの元の入力内容を再利用して、より関連性の高い結果を取得できます。
  • ユーザーが住所情報のみを入力することが予想される場合は、Geocoding API の呼び出しで、ユーザーの元の入力内容を再利用します。
  • ユーザーが特定の場所に関する検索語句（名前や住所）を入力することが予想される場合は、Find Place（レガシー）リクエストを使用します。特定の地域の結果のみが求められる場合は、場所のバイアスを使用します。
  Geocoding API へのフォールバックが最適となるその他のシナリオは次のとおりです。
  • 建物内の特定のユニットやアパートの住所など、サブプレミス住所を入力するユーザー。たとえば、チェコ語の住所「Stroupežnického 3191/17, Praha」では、Place Autocomplete（従来版）で部分的な予測が生成されます。
  • ユーザーがニューヨークの「23-30 29th St, Queens」や、ハワイのカウアイ島の「47-380 Kamehameha Hwy, Kaneohe」など、道路区間のプレフィックスを入力する場合。

使用量上限

割り当て

割り当てと料金については、Places API の使用量と料金に関するドキュメントをご覧ください。