Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Place Autocomplete（従来版）

欧州経済領域（EEA）のデベロッパー

注: サーバーサイドライブラリ

このページでは、Maps JavaScript API で使用可能なクライアントサイドライブラリについて説明します。サーバーで Places API ウェブサービスを使用する場合は、Google マップサービス向け Node.js クライアントをご覧ください。このページでは、Google マップサービス用の Java Client、Python Client、Go Client も紹介しています。

はじめに

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

スタートガイド

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

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

Google Cloud コンソールに移動します。
[プロジェクトを選択] ボタンをクリックし、Maps JavaScript API を設定した同じプロジェクトを選択して、[開く] をクリックします。
[ダッシュボード] の API のリストから、Places API を探します。
リストに API が表示されていれば、準備は完了です。ただし、このプロジェクトはレガシーステータスです。レガシーステージと、レガシーから新しいサービスに移行する方法については、レガシープロダクトと機能をご覧ください。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 は、ウェブページにテキスト入力フィールドを追加し、そのフィールドへの文字入力を監視します。ユーザーがテキストを入力すると、予測入力によりプルダウンリストの形式で候補となる場所が返されます。ユーザーがリストから場所を選択すると、その場所の情報が予測入力オブジェクトに返され、アプリケーションによる取得が可能になります。詳しくは下記をご覧ください。

図 1: 予測入力のテキストフィールドと選択リスト

図 2: 入力が完了した住所フォーム
SearchBox は、Autocomplete と同様にウェブページにテキスト入力フィールドを追加しますが、次の点で異なります。
- 主な違いは、選択リストに表示される結果です。SearchBox は、予測リストを拡張して提供します。つまり Places API で定義される場所に加えて、検索キーワードの候補も表示します。たとえば、ユーザーが「東京のピ」まで入力すると、選択リストには「東京のピザ屋」という語句が含まれ、さらにさまざまなピザ販売店の名前が含まれます。
- 検索を制限する場合、SearchBox で指定できるオプションは Autocomplete ほど多くありません。前者では、指定した LatLngBounds に対して検索に優先度を持たせることができます。後者では、検索を特定の国や特定のタイプの場所に絞り込むことができ、境界を設定することも可能です。詳しくは、以下をご覧ください。
図 3: SearchBox に検索語句と候補となる場所が表示されています。

詳しくは下記をご覧ください。
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 値です。有効にした場合、指定領域外の場所は、たとえユーザーの入力内容と一致していても返されません。
  注: 位置情報の制限はルート全体にのみ適用されます。ルートの 1 つが位置情報の制限と重なる場合、位置情報の制限外にある合成結果が返されることがあります。
- componentRestrictions: 表示する候補を、特定のグループ内に含まれる場所に限定します。componentRestrictions を使用して最大 5 つの国に結果を絞り込むことができます。国は、ISO 3166-1 Alpha-2 に準拠した 2 文字の国コードで指定してください。複数の国は、国コードのリストとして渡す必要があります。
  注: 国コードを使用して予期しない結果が返される場合は、対象の国や属領、地理的に重要な特別な地域を含むコードを使用しているか確認してください。コードの情報については、Wikipedia の ISO 3166 国コードのリストか、ISO オンライン参照プラットフォームをご覧ください。
- placeIdOnly: プレイス ID だけを取得するよう、Autocomplete ウィジェットに指示します。有効にした場合、Autocomplete オブジェクトで getPlace() を呼び出した際、place id、types、name の各プロパティだけを設定された PlaceResult が提供されます。返されたプレイス ID は、プレイス、ジオコーディング、ルート、距離行列といったサービスの呼び出しに使用できます。
  注: name プロパティには、Place Autocomplete の予測入力候補に基づく description が含まれます。description の詳細については、AutocompleteService に関するドキュメントをご覧ください。
  
  注: placeIdOnly は 2019 年 1 月 15 日をもって非推奨となり、2020 年 1 月 15 日に提供が終了します。代わりに AutocompleteOptions インターフェースの fields 配列を使用します（fields: ['place_id', 'name', 'types']）。

予測入力候補を制限する

デフォルトでは、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,
};

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

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

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

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

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

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

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

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

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

注: 境界または地図のビューポートを指定しない場合、API は IP アドレスからユーザーの位置を検出し、その位置を優先して結果を返します。境界は可能な限り指定しましょう。設定しないと、ユーザーごとに異なる予測を受け取る可能性があります。また、一般的に予測精度を高めるためには、地図のパンまたはズームによって設定したような実用的なビューポート、またはデバイスの位置と半径に基づいたデベロッパーによるビューポートを提供することが重要です。半径を指定できない場合は、5 km が Place Autocomplete の有効なデフォルト値とみなされます。半径が 0 のビューポート（単一ポイント）、100 m 未満のビューポート、地球にまたがるビューポートは設定しないでください。

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

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

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

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

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

TypeScript

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

JavaScript

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

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

TypeScript

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

JavaScript

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

サンプルを表示

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

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

autocomplete.setOptions({ strictBounds: true });

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

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

TypeScript

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

JavaScript

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 を取得する手順は次のとおりです。

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

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

重要: 予測入力を使用してプレイス ID を更新することはおすすめしません。セッションごとに料金が発生するためです。代わりに、getDetails() を呼び出して、place_id フィールドのみを指定します。

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

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

サンプルを表示

一部の予測入力候補では、プレイス ID の Place Details レスポンスに street_number 住所コンポーネントが存在しない場合があります。多くの場合は、住所を補間できない場所でそのようなことが起こります。その場合は、予測の types 配列に「route」が含まれます。description に数字が含まれる予測入力候補（入力語句が一致）で、プレイス ID の Place Details レスポンスに番地が含まれるのは、その予測の types 配列に次の 1 つ以上が含まれている場合のみです。

street_address（住所）
premise（建物名）
establishment（施設）

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

デフォルトでは、予測入力サービスにより作成されるテキストフィールドには、標準のプレースホルダテキストが含まれています。テキストを変更するには、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 の HTML input 要素。これは、SearchBox サービスが監視し、結果を付加する入力フィールドです。
bounds プロパティを含めることができる options 引数。bounds は、場所を検索する領域を指定する google.maps.LatLngBounds オブジェクトです。この領域内に含まれる場所が優先されますが、これに限定されません。

次のコードは、bounds パラメータを使用して、緯度 / 経度座標で指定された特定の地理範囲に含まれる場所を優先する形で、結果を返します。

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 オブジェクトで 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);
});index.ts

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);
});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」という検索語句の予測リクエストを実行し、結果をリストに表示します。

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

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

CSS

style.css

HTML

<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 リクエストとして課金されます。予測入力リクエストは無料です。リクエストでセッショントークンを使用しない場合、予測入力リクエストと 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 ウィジェットの両方に適用されます。

Autocomplete と SearchBox のウィジェット用の CSS クラスの図 — Autocomplete と SearchBox のウィジェット用の CSS クラス

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

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

基本的な費用の最適化

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

高度な費用の最適化

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

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

アプリケーションの費用を最小限に抑える Place Autocomplete（従来版）の実装を選択するには、次の表でアプリケーションのニーズに一致する行を見つけます。

アプリケーションに必要なもの	ユーザーが予測を選択するまでに実行される Place Autocomplete（従来版）リクエストの平均数	おすすめの実装方法
住所と位置以外の Place Details（場所の名前、ビジネスのステータス、営業時間など）	その他の数字	セッションベースの Place Autocomplete（従来版）と Place Details（従来版）
選択された予測結果の住所と緯度 / 経度のみ	4 以下	Geocoding API を使用したリクエストごとの Place Autocomplete（従来版）
選択された予測結果の住所と緯度 / 経度のみ	4 回以上	住所のみのアプリケーション向けのセッションベースの Place Autocomplete（従来版）

Place Autocomplete（従来版）使用時のパフォーマンスによっては、アプリケーションで Places Details（従来版）を使用するよりも、Geocoding API を使用した方が費用対効果が高くなる場合があります。アプリケーションの Place Autocomplete（従来版）の効率は、ユーザーの入力内容や、アプリケーションが使用される場所、パフォーマンス最適化のベストプラクティスが導入されているかどうかによって変わります。

表のリクエスト数の平均を求めるには、ユーザーがアプリケーション内で Place Autocomplete（従来版）の予測を選択するまでに、平均でどのくらいの文字数を入力するのかを分析します。

セッションベースの Place Autocomplete（従来版）と Place Details（従来版）

セッションベースの Place Autocomplete（従来版）と Place Details（従来版）を併用します。
アプリケーションで Place Details（従来版）（場所の名前、営業状況、営業時間など）が必要な場合、Place Autocomplete（従来版）の実装では、セッションごとにセッショントークン（プログラムまたは JavaScript、Android、iOS ウィジェットに組み込まれたもの）を使用し、リクエストする場所データフィールドに応じて、該当する Places Data SKU を使用する必要があります。¹

ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete（従来版）リクエストと Place Details（従来版）リクエストの両方が含まれます。必要な Place Autocomplete（従来版）のデータフィールドのみをリクエストするように、必ず fields パラメータを指定してください。

プログラマティック実装
Place Autocomplete（従来版）リクエストでセッショントークンを使用します。選択された予測結果に関する Place Details（従来版）をリクエストする際は、次のパラメータを含めます。

Place Autocomplete（従来版）レスポンスのプレイス ID
Place Autocomplete（従来版）リクエストで使用されるセッショントークン
必要な Place Autocomplete（従来版）のデータフィールドを指定する fields パラメータ

リクエストごとの Place Autocomplete（従来版）と Geocoding API

セッショントークンを使用せずにプログラムによって Place Autocomplete（従来版）を実装し、選択された場所の予測で Geocoding API を呼び出します。
Geocoding API は、住所と緯度 / 経度の座標を提供します。 Autocomplete - Per Request のリクエスト 4 件と、選択された場所予測に関する Geocoding API の呼び出しを合わせた料金は、Place Autocomplete（従来版）のセッション 1 回あたりの料金よりも少ないコストです。¹

パフォーマンスに関するベストプラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める候補を提供できるようすることをおすすめします。

住所のみのアプリケーション向けのセッションベースの Place Autocomplete（従来版）

セッションベースの Place Autocomplete（従来版）と Place Details（従来版）を併用します。
ユーザーが Place Autocomplete（従来版）の予測を選択するまでに行うと予想されるリクエストの平均数が、セッションあたりの料金を上回るため、Place Autocomplete（従来版）の実装では、Place Autocomplete（従来版）リクエストと関連する Place Details（従来版）リクエストの両方で、セッションごとにセッショントークンを使用する必要があります。 ¹

ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete（従来版）リクエストと Place Details（従来版）リクエストの両方が含まれます。必要なフィールドのみをリクエストするように、必ず fields パラメータを指定してください。

Place Autocomplete（従来版）レスポンスのプレイス ID
Place Autocomplete（従来版）リクエストで使用されるセッショントークン
住所やジオメトリなどの基本データフィールドを指定する fields パラメータ

Place Autocomplete（従来版）リクエストを遅らせることを検討する
ユーザーが最初の 3 ～ 4 文字を入力するまで Place Autocomplete（従来版）リクエストを遅らせて、アプリケーションでのリクエスト数を減らすこともできます。たとえば、ユーザーが 3 文字目を入力した後に、1 文字入力されるごとに Place Autocomplete（従来版）リクエストを行う場合、ユーザーが 7 文字を入力してから予測を選択し、Geocoding API リクエストを 1 回行うと、合計費用は Place Autocomplete（従来版）Per Request 4 回分 + Geocoding 1 回分となります。¹

リクエストを遅らせることで、プログラマティックリクエストの回数を平均 4 回以下に抑えられる場合は、高パフォーマンスで Place Autocomplete（従来版）と Geocoding API を併用する実装に関するガイダンスをご覧ください。なお、リクエストを遅らせると、1 文字入力するたびに予測が表示されはずと考えているユーザーには、遅延と受けとられる場合もあります。

費用については、Google Maps Platform の料金表をご覧ください。

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

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

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

位置情報のバイアス

location パラメータと radius パラメータを渡すことで、バイアスを設定し、指定した範囲内の結果を優先します。これにより、Place Autocomplete（従来版）は、定義されたエリア内の結果を優先的に表示します。指定した範囲外の結果が返されることもあります。includedRegionCodes パラメータを使用すると、指定した国内の場所のみを表示するように結果をフィルタできます。

警告: radius が指定されていない場合、location パラメータは無視されます。

検索エリアが広い場合、通常、施設の結果は検索結果に表示されるほど上位にランク付けされません。施設とジオコードが混在する結果に施設を表示する場合は、より小さい半径を指定できます。または、types=establishment を使用して、結果を施設のみに制限します。

ロケーションの制限

locationRestriction パラメータを渡して、結果を特定のエリアに制限します。

strictbounds パラメータを追加することで、location パラメータと radius パラメータで定義された地域に結果を制限することもできます。これにより、Place Autocomplete（従来版）は、その地域内の結果のみを返すようになります。

使用量上限

割り当て

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

Place Autocomplete（従来版） コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

はじめに

スタートガイド

ライブラリを読み込む

クラスの概要

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

予測入力候補を制限する

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

TypeScript

JavaScript

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

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

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

TypeScript

JavaScript

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

TypeScript

JavaScript

TypeScript

JavaScript

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

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

TypeScript

JavaScript

場所のタイプを制限する

場所の情報を取得する

TypeScript

JavaScript

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

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

SearchBox の検索領域を変更する

場所の情報を取得する

TypeScript

JavaScript

プログラムによって Place Autocomplete サービスの予測を取得する

TypeScript

JavaScript

CSS

HTML

セッション トークン

Autocomplete と SearchBox ウィジェットのスタイルを設定する

Place Autocomplete（従来版）の最適化

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

基本的な費用の最適化

高度な費用の最適化

セッション ベースの Place Autocomplete（従来版）と Place Details（従来版）

リクエストごとの Place Autocomplete（従来版）と Geocoding API

住所のみのアプリケーション向けのセッション ベースの Place Autocomplete（従来版）

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

位置情報のバイアス

ロケーションの制限

使用量上限

割り当て

Place Autocomplete（従来版）

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

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

セッショントークン

セッションベースの Place Autocomplete（従来版）と Place Details（従来版）

住所のみのアプリケーション向けのセッションベースの Place Autocomplete（従来版）

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