プレイス ライブラリ

概要

プレイス ライブラリ（Maps JavaScript API）の関数を使用すると、アプリケーションで、定義された領域（地図の境界線内や、特定の地点の周辺など）内の場所（この API では施設、地理的位置、著名なスポットなどと定義されます）を検索できるようになります。

Places API はオートコンプリート機能を備えており、アプリケーションの Google マップ検索フィールドにオートコンプリート検索機能を実装できます。ユーザーが住所の入力を開始すると、予測入力によって残りが入力されます。詳細については、予測入力のドキュメントをご覧ください。

はじめに

Maps JavaScript API や JavaScript に慣れていない方には、始める前に JavaScript を確認し、API キーを取得しておくことをおすすめします。

API を有効にする

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

有効な API のリストを表示する手順は次のとおりです。

  1. Google Cloud コンソールに移動します。
  2. [プロジェクトを選択] ボタンをクリックし、Maps JavaScript API を設定した同じプロジェクトを選択して、[開く] をクリックします。
  3. [ダッシュボード] の API のリストから、Places API を探します。
  4. このリストに Places API が表示されている場合は、すでに有効になっています。API がリストにない場合は、次の手順で有効にします。
    1. ページ上部の [API とサービスの有効化] を選択して、[ライブラリ] タブを表示します。または、左側のサイドメニューで [ライブラリ] を選択します。
    2. Places API を検索し、結果リストから選択します。
    3. [有効にする] を選択します。このプロセスを完了すると、[ダッシュボード] の API のリストに Places API が表示されます。

ライブラリを読み込む

プレイス サービスは、メインの 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 キーの API 制限リストに Places API を追加する

API 制限をキーに適用すると、API キーの使用が 1 つ以上の API または SDK に制限されます。API キーに関連付けられた API または SDK へのリクエストは処理され、API キーに関連付けられていない API または SDK へのリクエストは失敗します。API キーとプレイス ライブラリ（Maps JavaScript API）の併用を制限する手順は次のとおりです。
  1. Google Cloud コンソールに移動します。
  2. プロジェクトのプルダウンをクリックし、保護する API キーが含まれているプロジェクトを選択します。
  3. メニューボタン をクリックし、[Google Maps Platform] > [認証情報] を選択します。
  4. [認証情報] ページで、保護する API キーの名前をクリックします。
  5. [API キーの制限と名前変更] ページで制限を設定します。
    • API の制限
      • [キーを制限] を選択します。
      • [API を選択] をクリックし、[Maps JavaScript API] と [Places API] の両方を選択します。
        （いずれかの API がリストに表示されていない場合は、有効にする必要があります）
  6. [保存] をクリックします。

使用制限とポリシー

割り当て

プレイス ライブラリは、Places API の使用制限に関するドキュメントに記載されているように、Places API と使用量割り当てを共有しています。

ポリシー

プレイス ライブラリ（Maps JavaScript API）を使用する場合は、Places API に関するポリシーを遵守する必要があります。

Place Search

プレイス サービスでは、次のような検索を行うことができます。

  • Find Place from Query: テキストクエリ（場所の名前や住所など）を基に場所を返します。
  • Find Place from Phone: 電話番号を基に場所を返します。
  • Nearby Search: ユーザーの所在地を基に、その周辺の場所のリストを返します。
  • Text Search: 検索文字列（「ピザ」など）を基に周辺の場所のリストを返します。
  • Place Details リクエスト: 特定の場所に関するより詳しい情報（ユーザーのクチコミなど）を返します。

返される情報には、施設（レストラン、お店、オフィスなど）に加え、住所、市区町村などの行政区画を含むジオコード結果、およびその他の有名スポットなどが含まれます。

Find Place リクエスト

Find Place リクエストを使用すると、テキストクエリまたは電話番号で場所を検索できます。Find Place リクエストには次の 2 つのタイプがあります。

Find Place from Query

Find Place from Query の場合は、テキスト入力を受け取り、場所を返します。お店やサービスの名前や住所など、場所に関するあらゆる入力内容を受け取ります。Find Place from Query リクエストを実行するには、PlacesService の findPlaceFromQuery() メソッドを呼び出します。このメソッドは次のパラメータを受け取ります。

  • query（必須）: 検索するテキスト文字列（「レストラン」、「123 番通り」など）です。地名、住所、施設のカテゴリのいずれかを入力する必要があります。他の種類のテキストを入力した場合、有効な結果が返されず、エラーが発生する場合があります。Places API はこの文字列と一致する候補を、関連性の高い順に並べて結果として返します。
  • fields（必須）: 返す場所データのタイプを指定する 1 つ以上のフィールド。
  • locationBias（省略可）: 検索領域を定義する座標。値は次のいずれかになります。

結果オブジェクトと google.maps.places.PlacesServiceStatus レスポンスを処理するため、findPlaceFromQuery() にコールバック メソッドを渡す必要もあります。

次の例では、findPlaceFromQuery() を呼び出し、「Museum of Contemporary Art Australia」を検索して name と geometry フィールドを含めています。

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
 サンプルを表示

Find Place from Phone Number

Find Place from Phone Number は、電話番号を受け取って場所を返します。Find Place from Phone Number リクエストを実行するには、PlacesService の findPlaceFromPhoneNumber() メソッドを呼び出します。このメソッドは次のパラメータを受け取ります。

  • phoneNumber（必須）: E.164 形式の電話番号。
  • fields（必須）: 返す場所データのタイプを指定する 1 つ以上のフィールド。
  • locationBias（省略可）: 検索領域を定義する座標。値は次のいずれかになります。
    • LatLngLiteral または LatLng オブジェクトとして指定された緯度 / 経度座標のセット
    • 矩形の境界（4 つの緯度 / 経度の地点、または LatLngBounds オブジェクト）
    • 緯度 / 経度を中心とする半径（メートル単位）

結果オブジェクトと google.maps.places.PlacesServiceStatus レスポンスを処理するため、findPlaceFromPhoneNumber() にコールバック メソッドを渡す必要もあります。

フィールド（Find Place メソッド）

fields パラメータを使用して、返す場所データのタイプの配列を指定します（例: fields: ['formatted_address', 'opening_hours', 'geometry']）。複合的な値を指定する場合はドットを使用します（例: opening_hours.weekday_text）。

フィールドは Place Search の結果に対応しており、Basic（基本）、Contact（連絡先）、Atmosphere（雰囲気）の 3 つの請求カテゴリに分けられます。Basic フィールドは基本レートで課金され、追加料金はかかりません。Contact フィールドと Atmosphere フィールドはより高いレートで課金されます。詳細については、価格表をご覧ください。アトリビューション（html_attributions）は、このフィールドがリクエストされているかどうかにかかわらず、呼び出しのたびに必ず返されます。

Basic

Basic カテゴリには次のフィールドが含まれます。
business_status、formatted_address、geometry、 icon、icon_mask_base_uri、icon_background_color、 name、permanently_closed（サポート終了）、 photos、place_id、plus_code、types

Contact

Contact カテゴリには次のフィールドが含まれます。 opening_hours
（Maps JavaScript API のプレイス ライブラリではサポート終了。opening_hours の結果を取得するには、Place Details リクエストを使用してください）

Atmosphere

Atmosphere カテゴリには次のフィールドが含まれます。 price_level、rating、user_ratings_total

findPlaceFromQuery() メソッドと findPlaceFromPhoneNumber() メソッドのフィールド セットは同一で、それぞれのレスポンスで同じフィールドを返します。

場所のバイアスを設定する（Find Place メソッド）

Find Place で特定の地域の検索結果を優先させるには、locationBias パラメータを使用します。locationBias は、次の方法で設定できます。

特定の地域を優先するよう結果にバイアスを設定します。

locationBias: {lat: 37.402105, lng: -122.081974}

検索対象の矩形領域を定義します。

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

LatLngBounds も使用できます。

特定の領域を中心とした検索範囲の半径をメートル単位で定義します。

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

Nearby Search リクエスト

Nearby Search では、指定された範囲内で、キーワードやタイプによる場所の検索が可能です。Nearby Search には、次のいずれかの方法で指定する形で場所を含める必要があります。

  • LatLngBounds。
  • 円形領域: location プロパティ（円の中心を指定する LatLng オブジェクト）と半径（メートル単位）を組み合わせて定義。

Places Nearby Search を開始するには、 PlacesService の nearbySearch() メソッドを呼び出します。これにより、 PlaceResult オブジェクトが返されます。バージョン 3.9 以降、search() メソッドは nearbySearch() メソッドに置き換えられています。

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

このメソッドは、以下のフィールドを持つリクエストを受け付けます。

  • 次のいずれかです。
    • bounds: 矩形の検索領域を定義する google.maps.LatLngBounds オブジェクトである必要があります。指定できる境界領域の最大対角距離は約 10 万メートルです。
    • location と radius: 前者は google.maps.LatLng オブジェクトで指定し、後者はメートル単位の円の半径を表す単純な整数で指定します。指定可能な最大半径は 50,000 メートルです。なお、rankBy を Distance に設定する場合は、location を指定する必要がありますが、radius または bounds は指定できません。
  • keyword（省略可能）: 利用可能なすべてのフィールドを検索対象とする語句を示します。名前やタイプ、住所をはじめとして、カスタマー レビューやサードパーティ コンテンツも対象となります。
  • minPriceLevel と maxPriceLevel（省略可）: 指定した範囲内の場所に結果を制限します。有効な値の範囲は 0（最も安い）〜4（最も高い）です。
  • name（非推奨）: keyword と同等です。このフィールドの値は、keyword フィールドの値と組み合わされて、同じ検索文字列の一部として渡されます。
  • openNow（省略可能）: クエリが送信された時点で営業している場所のみがプレイス サービスによって返されることを示すブール値です。クエリにこのパラメータを指定した場合、Google プレイスのデータベースに営業時間が登録されていない場所は返されません。openNow を false に設定しても影響はありません。
  • rankBy（省略可能）: 結果が表示される順序を指定します。有効な値は次のとおりです。
    • google.maps.places.RankBy.PROMINENCE（デフォルト）。このオプションを指定した場合は、場所の重要度で検索結果が並べられます。設定された半径内の重要度の高い場所が、一致するものの重要度が低い付近の場所より優先されます。重要度は、Google のインデックスでの場所のランキングや、グローバルな人気度などの要因によって決まります。google.maps.places.RankBy.PROMINENCE を指定する場合、radius パラメータは必須です。
    • google.maps.places.RankBy.DISTANCE。このオプションは、指定された location（必須）からの距離に応じて結果を昇順で並べ替えます。RankBy.DISTANCE を指定した場合、カスタムの bounds と radius は指定できません。RankBy.DISTANCE を指定する場合は、keyword、name、type のうち 1 つ以上が必要です。
  • type - 指定したタイプに一致する場所のみに結果を制限します。指定できるタイプは 1 つだけです（複数のタイプを指定すると、最初のエントリの後に指定したタイプはすべて無視されます）。サポートされているタイプのリストをご覧ください。

結果オブジェクトと google.maps.places.PlacesServiceStatus レスポンスを処理するため、nearbySearch() にコールバック メソッドを渡す必要もあります。

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    type: ['restaurant']
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

サンプルを表示

Text Search リクエスト

Google プレイスの Text Search サービスは、文字列に基づいて複数の場所に関する情報を返すウェブ サービスです。たとえば、「渋谷 ピザショップ」や「表参道 靴店」を検索すると、このサービスは、テキスト文字列や場所の優先度設定と合致するプレイスのリストをレスポンスとして返します。検索レスポンスには場所のリストが含まれます。レスポンス内の場所の詳細情報が必要な場合は、Place Details リクエストを送信できます。

Text Search を開始するには、PlacesService の textSearch() メソッドを呼び出します。

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

このメソッドは、以下のフィールドを持つリクエストを受け付けます。

  • query（必須）: 検索するテキスト文字列（「レストラン」、「123 番通り」など）です。地名、住所、施設のカテゴリのいずれかを入力する必要があります。他の種類のテキストを入力した場合、有効な結果が返されず、エラーが発生する場合があります。プレイス サービスはこの文字列と一致する候補を、関連性の高い順に並べて結果として返します。type パラメータが検索リクエストでも使用されている場合、このパラメータは省略できます。
  • 省略可能:
    • openNow - クエリが送信された時点で営業している場所のみがプレイス サービスによって返されることを示すブール値です。クエリにこのパラメータを指定した場合、Google プレイスのデータベースに営業時間が登録されていない場所は返されません。openNow を false に設定しても影響はありません。
    • minPriceLevel と maxPriceLevel - 結果を指定した料金レベルの場所のみに限定します。有効な値の範囲は 0（最も安い）〜4（最も高い）です。
    • 次のいずれかです。
      • bounds: 矩形の検索領域を定義する google.maps.LatLngBounds オブジェクトである必要があります。指定できる境界領域の最大対角距離は約 10 万メートルです。
      • location と radius - location パラメータと radius パラメータを渡すことで、バイアスを設定し、指定した円の範囲内の結果を優先します。これによって、プレイス サービスが指定した範囲内を優先するように検索結果を絞り込むことができますが、指定した範囲外の結果が返されることもあります。 location は google.maps.LatLng オブジェクトで指定し、radius はメートル単位で円の半径を表す単純な整数で指定します。指定可能な最大半径は 50,000 メートルです。
    • type - 結果を指定したタイプに一致する場所に制限します。指定できるタイプは 1 つだけです（複数のタイプを指定すると、最初のエントリの後に指定したタイプはすべて無視されます）。詳しくはサポートされているタイプのリストをご覧ください。

textSearch() には、結果オブジェクトと google.maps.places.PlacesServiceStatus レスポンスを処理するためのコールバック メソッドを渡す必要もあります。

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

検索レスポンス

ステータス コード

PlacesServiceStatus レスポンス オブジェクトには、リクエストのステータスが格納されます。場所のリクエストが失敗した原因を追跡できるようにデバッグ情報が格納される場合もあります。有効なステータス値は次のとおりです。

  • INVALID_REQUEST: このリクエストは無効でした。
  • OK: レスポンスには有効な結果が含まれています。
  • OVER_QUERY_LIMIT: ウェブページは、そのリクエストの割り当て数を超過しました。
  • REQUEST_DENIED: ウェブページで PlacesService を利用できません。
  • UNKNOWN_ERROR: サーバーエラーにより PlacesService リクエストを処理できませんでした。再度リクエストすると、成功する可能性があります。
  • ZERO_RESULTS: リクエストに対する結果が見つかりませんでした。

Place Search の結果

findPlace()、nearbySearch()、textSearch() の各関数は、PlaceResult オブジェクトの配列を返します。

各 PlaceResult オブジェクトには、次のプロパティを含めることができます。

  • business_status: その場所の営業状況を示します（場所がお店やサービスの場合）。次のいずれかの値を含めることができます。
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    データが存在しない場合、business_status は返されません。
  • formatted_address は、人が読める形式のこの場所の住所の文字列です。formatted_address プロパティは、Text Search の場合にのみ返されます。

    ほとんどの場合、この住所は「郵便の宛先」と同一です。イギリスなど一部の国では、ライセンス上の制限があるため実際の郵便の宛先は配信できません。

    フォーマット済み住所は、論理的には 1 つ以上の住所コンポーネントで構成されます。たとえば、「111 8th Avenue, New York, NY」という住所は、「111」（番地）、「8th Avenue」（道路名）、「New York」（都市名）、「NY」（アメリカの州名）で構成されています。

    フォーマット済み住所は、プログラムで解析しないでください。その代わりに、フォーマット済み住所のフィールドに加えて、API レスポンスに含まれる個々の住所コンポーネントを使用してください。

  • geometry: 場所のジオメトリに関する情報です。該当するものは次のとおりです。
    • location は場所の緯度と経度を提供します。
    • viewport は、この場所の表示時に地図上で優先されるビューポートを定義します。
  • permanently_closed（サポート終了）は、場所が恒久的に閉鎖されたか一時的に閉鎖されたかを示すブール値のフラグです（値 true をご覧ください）。permanently_closed は使用しないでください。代わりに、business_status を使用してお店やサービスの営業状況を取得してください。
  • plus_code（Open Location Code と Plus Code を参照）はエンコードされた場所の参照情報です。緯度 / 経度の座標から取得され、8000 分の 1 x 8000 分の 1（14 メートル x 14 メートル）以下の領域を表します。Plus Code は、番地がない場所（建物に番号が付いていない場所や、通りに名前がない場所）で、番地の代わりに使用できます。

    Plus Code は、グローバル コードと複合コードの形式になっています。

    • global_code は、4 文字の市外局番と 6 文字以上のローカルコード（849VCWC8+R9）です。
    • compound_code は、明示的な場所（CWC8+R9, Mountain View, CA, USA）を含む 6 文字以上のローカルコードです。このコンテンツをプログラムで解析しないでください。
    通常は、グローバル コードと複合コードの両方が返されます。ただし、検索結果が遠隔地（海や砂漠など）にある場合は、返されるのはグローバル コードのみです。
  • html_attributions: 検索結果に表示する属性の配列です。配列内の各エントリには、単一の属性の HTML テキストが含まれています。注: これは、検索レスポンス全体のすべての属性が集約されたものです。したがって、レスポンス内のすべての PlaceResult オブジェクトには同一の属性リストが含まれます。
  • icon は、色付きの 71 ピクセル x 71 ピクセルの PNG アイコンの URL を返します。
  • icon_mask_base_uri は、非色付きアイコンのベース URL から、拡張子の .svg または .png を除いた値を返します。
  • icon_background_color は、場所のカテゴリのデフォルトの HEX カラーコードを返します。
  • name: 場所の名前。
  • opening_hours には次の情報を含めることができます。
    • open_now は、場所がその時点に営業しているかどうかを示すブール値です（Maps JavaScript API のプレイス ライブラリではサポートが終了しているため、代わりに utc_offset_minutes を使用してください）。
  • place_id: 場所を一意に識別するテキスト表記の ID です。場所に関する情報を取得するには、この ID を Place Details リクエストに渡します。詳しくは、プレイス ID を使って場所を参照する方法をご覧ください。
  • rating: 集計されたユーザー レビューに基づく場所の評価（0.0～5.0）が含まれます。
  • types: この場所のタイプの配列（["political", "locality"]、["restaurant", "lodging"] など）。この配列は複数の値を含むことも、空にすることもできます。新しい値が事前通知なしに導入される場合があります。サポートされているタイプのリストをご覧ください。
  • vicinity: 場所の簡単な住所です。番地や市町村などが含まれ、州、都道府県、郵便番号、国などは含まれません。たとえば、オーストラリアにある Google のシドニー オフィスの vicinity の値は 5/48 Pirrama Road, Pyrmont です。

追加の結果へのアクセス

デフォルトでは、各 Place Search は 1 つのクエリに対して最大 20 件の結果を返します。ただし、各検索では、3 ページに分けて最大 60 件の結果を返すことができます。追加のページは、PlaceSearchPagination オブジェクトを通じて利用できます。追加のページにアクセスするには、コールバック関数を使用して PlaceSearchPagination オブジェクトを取得する必要があります。PlaceSearchPagination オブジェクトは、次のように定義されます。

  • hasNextPage: 追加の結果があるかどうかを示すブール値のプロパティ。true: 追加の結果ページがある場合に返されます。
  • nextPage(): 次の結果セットを返す関数。検索の実行後、結果の次のページが利用可能になるまで 2 秒待機する必要があります。

次の結果セットを表示するには、nextPage を呼び出します。次の結果ページを表示する前に、それ以前のページを表示しておく必要があります。なお、検索 1 回でリクエスト 1 回分の割り当て量を消費することになります。

次の例では、コールバック関数を変更して PlaceSearchPagination オブジェクトを取得し、複数の検索リクエストを実行できるようにしています。

TypeScript

// 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 initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        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),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// 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 initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        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),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js
サンプルを表示

サンプルを試す

Place Details

領域内の場所のリストを表示するほか、プレイス サービスは特定の場所に関する詳細情報を返すことができます。Place Search のレスポンスで場所が返されたら、その reference プロパティを使用し、その場所についての詳細（完全な住所、電話番号、ユーザーのレビューや評価など）をリクエストできます。

Place Details リクエスト

Place Details をリクエストするには、サービスの getDetails() メソッドを呼び出します。

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

このメソッドは、対象の場所の placeId と、返す場所データのタイプを示すフィールドを含むリクエストを受け取ります。詳しくは、プレイス ID を使って場所を参照する方法をご覧ください。

また、このメソッドはコールバック メソッドも受け取ります。コールバック メソッドでは google.maps.places.PlacesServiceStatus レスポンスで渡されるステータス コードや google.maps.places.PlaceResult オブジェクトを処理する必要があります。

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

サンプルを表示

フィールド（Place Details）

fields パラメータは、文字列（フィールド名）の配列を受け取ります。

fields パラメータを使用して、返す場所データのタイプの配列を指定します（例: fields: ['address_components', 'opening_hours', 'geometry']）。複合的な値を指定する場合はドットを使用します（例: opening_hours.weekday_text）。

フィールドは Place Details の結果に対応しており、Basic（基本）、Contact（連絡先）、Atmosphere（雰囲気）の 3 つの請求カテゴリに分けられます。Basic フィールドは基本レートで課金され、追加料金はかかりません。Contact フィールドと Atmosphere フィールドはより高いレートで課金されます。詳細については、価格表をご覧ください。アトリビューション（html_attributions）は、このフィールドがリクエストされているかどうかにかかわらず、呼び出しのたびに必ず返されます。

Basic

Basic カテゴリには次のフィールドが含まれます。
address_components、adr_address、business_status、 formatted_address、geometry、icon、 icon_mask_base_uri、icon_background_color、name、 permanently_closed（サポート終了）、 photo、place_id、plus_code、type、url、utc_offset（Maps JavaScript API のプレイス ライブラリではサポート終了）、utc_offset_minutes、 vicinity

Contact

Contact カテゴリには、次のフィールドがあります。
formatted_phone_number、international_phone_number、opening_hours、website

Atmosphere

Atmosphere カテゴリには、次のフィールドが含まれます。 price_level、rating、reviews、user_ratings_total

詳しくは、場所のフィールドの概要をご覧ください。場所のデータのリクエストに対する課金方法については、使用量と課金をご覧ください。

Place Details レスポンス

ステータス コード

PlacesServiceStatus レスポンス オブジェクトには、リクエストのステータスが格納されます。Place Details リクエストが失敗した原因を追跡できるようにデバッグ情報が格納される場合もあります。有効なステータス値は次のとおりです。

  • INVALID_REQUEST: このリクエストは無効でした。
  • OK: レスポンスには有効な結果が含まれています。
  • OVER_QUERY_LIMIT: ウェブページは、そのリクエストの割り当て数を超過しました。
  • NOT_FOUND: 参照された場所がプレイスのデータベースで見つかりませんでした。
  • REQUEST_DENIED: ウェブページで PlacesService を利用できません。
  • UNKNOWN_ERROR: サーバーエラーにより PlacesService リクエストを処理できませんでした。再度リクエストすると、成功する可能性があります。
  • ZERO_RESULTS: リクエストに対する結果が見つかりませんでした。

Place Details の結果

正常に処理された getDetails() 呼び出しからは、次のプロパティを持つ PlaceResult オブジェクトが返されます。

  • address_components は、この住所に適用される個々のコンポーネントを含む配列です。

    通常、各住所コンポーネントには次のフィールドがあります。

    • types[] は住所コンポーネントのタイプを示す配列です。サポートされているタイプのリストをご覧ください。
    • long_name は、ジオコーダが返した住所コンポーネントの説明または名前です。
    • short_name は、住所コンポーネントの略称です（略称がある場合）。たとえば、アラスカ州の住所コンポーネントの場合は、long_name には「Alaska」が設定され、short_name には 2 文字の郵便略称を使用して「AK」が設定されます。

    address_components[] 配列については、次の点に注意してください。

    • 住所コンポーネントの配列には、formatted_address よりも多くのコンポーネントが含まれている場合があります。
    • この配列には、formatted_address に含まれているもの以外の住所を持つ行政区画が、すべて含まれているとは限りません。特定の住所を含むすべての行政区画を取得するには、リバース ジオコーディングを使用して住所の緯度と経度をパラメータとしてリクエストに渡します。
    • レスポンスの形式は、リクエスト間で同じになるとは限りません。特に、address_components の数はリクエストされた住所によって異なり、同じ住所でも将来的に変わる可能性があります。コンポーネントは、配列内の位置が変わる場合があります。 コンポーネントのタイプは変わる場合があります。特定のコンポーネントが以降のレスポンスに含まれない場合があります。
  • business_status: その場所の営業状況を示します（場所がお店やサービスの場合）。次のいずれかの値を含めることができます。
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    データが存在しない場合、business_status は返されません。
  • formatted_address: 人が読める形式のこの場所の住所。

    ほとんどの場合、この住所は「郵便の宛先」と同一です。イギリスなど一部の国では、ライセンス上の制限があるため実際の郵便の宛先は配信できません。

    フォーマット済み住所は、論理的には 1 つ以上の住所コンポーネントで構成されます。たとえば、「111 8th Avenue, New York, NY」という住所は、「111」（番地）、「8th Avenue」（道路名）、「New York」（都市名）、「NY」（アメリカの州名）で構成されています。

    フォーマット済み住所は、プログラムで解析しないでください。その代わりに、フォーマット済み住所のフィールドに加えて、API レスポンスに含まれる個々の住所コンポーネントを使用してください。

  • formatted_phone_number: 電話番号の地域慣例に従ってフォーマットされた場所の電話番号。
  • geometry: 場所のジオメトリに関する情報です。該当するものは次のとおりです。
    • location は場所の緯度と経度を提供します。
    • viewport は、この場所の表示時に地図上で優先されるビューポートを定義します。
  • permanently_closed（サポート終了）は、場所が恒久的に閉鎖されたか一時的に閉鎖されたかを示すブール値のフラグです（値 true をご覧ください）。permanently_closed は使用しないでください。代わりに、business_status を使用してお店やサービスの営業状況を取得してください。
  • plus_code（Open Location Code と Plus Code を参照）はエンコードされた場所の参照情報です。緯度 / 経度の座標から取得され、8000 分の 1 x 8000 分の 1（14 メートル x 14 メートル）以下の領域を表します。Plus Code は、番地がない場所（建物に番号が付いていない場所や、通りに名前がない場所）で、番地の代わりに使用できます。

    Plus Code は、グローバル コードと複合コードの形式になっています。

    • global_code は、4 文字の市外局番と 6 文字以上のローカルコード（849VCWC8+R9）です。
    • compound_code は、明示的な場所（CWC8+R9, Mountain View, CA, USA）を含む 6 文字以上のローカルコードです。このコンテンツをプログラムで解析しないでください。
    通常は、グローバル コードと複合コードの両方が返されます。ただし、検索結果が遠隔地（海や砂漠など）にある場合は、返されるのはグローバル コードのみです。
  • html_attributions: この場所の結果に対して表示される属性テキスト。
  • icon: この場所のタイプを表すために使用できる画像リソースへの URL です。
  • international_phone_number には、場所の国際形式の電話番号が含まれます。国際形式では、「+」記号と国コードが先頭に付きます。たとえば、オーストラリアにある Google のシドニー オフィスの international_phone_number は +61 2 9374 4000 です。
  • name: 場所の名前。
  • utc_offset: Maps JavaScript API のプレイス ライブラリではサポートが終了しています。代わりに utc_offset_minutes を使用してください。
  • utc_offset_minutes: この場所の現在のタイムゾーンの UTC からのオフセットの分数を含みます。たとえば、オーストラリアのシドニーにある場所の場合、夏時間の間は 660（UTC から +11 時間）になり、カリフォルニア州にある場所の場合、夏時間でないときは -480（UTC から -8 時間）になります。
  • opening_hours には、次の情報が含まれています。
    • open_now（Maps JavaScript API のプレイス ライブラリではサポートが終了しているため、代わりに opening_hours.isOpen() を使用してください。isOpen と Place Details を併用する方法については、こちらの動画をご覧ください）は、お店やサービスが現在営業しているかどうかを示すブール値です。
    • periods[]: 場所が開いている期間の配列。日曜日から始まる 7 日間を時系列で格納します。各期間に含まれる情報は次のとおりです。
      • open: 場所が開く時刻を表す日付オブジェクトと時刻オブジェクトのペアを含みます。
        • day: 日曜日から始まる曜日に対応する 0～6 の数字。たとえば、2 は火曜日を示します。
        • time: 24 時間の hhmm 形式の時刻を格納します（値の範囲は 0000～2359 です）。time は場所のタイムゾーンで報告されます。
      • close には、その場所が営業終了する曜日を表すオプションと時刻を表すオブジェクトのペアが含まれます。注: 場所が年中無休の場合は、レスポンスに close セクションは含まれません。open 期間に値が 0 の day と、値が 0000 の time が含まれており、close が含まれていなければ、アプリケーションはこれを年中無休であると判断できます。
    • weekday_text は、1 週間の各曜日の書式設定された営業時間を表す 7 つの文字列の配列です。language パラメータが Place Details リクエストで指定された場合、プレイス サービスはその言語で作成されたクチコミを優先するように結果にバイアスをかけます。この配列の要素の順番は、language パラメータによって異なります。1 週間が月曜日から始まる言語もあれば、日曜日から始まる言語もあります。
  • permanently_closed（サポート終了）は、場所が恒久的に閉鎖されたか一時的に閉鎖されたかを示すブール値のフラグです（値 true をご覧ください）。permanently_closed は使用しないでください。代わりに、business_status を使用してお店やサービスの営業状況を取得してください。
  • photos[]: PlacePhoto オブジェクトの配列。 PlacePhoto は、getUrl() メソッドで写真を取得する際に使用できます。また、オブジェクトの次の値を確認する場合にも使用できます。
    • height: 画像の最大高（ピクセル単位）。
    • width: 画像の最大幅（ピクセル単位）。
    • html_attributions: 場所の写真とともに表示される属性テキスト。
  • place_id: 場所を一意に識別するテキスト表記の ID です。Place Details リクエストを介して場所の情報を取得する際に使用できます。詳しくは、プレイス ID を使って場所を参照する方法をご覧ください。
  • rating: ユーザーのクチコミの集計に基づく場所の評価（0.0〜5.0）。
  • reviews: 最大 5 つのレビューの配列。各クチコミは次の複数のコンポーネントで構成されます。
    • aspects[]: PlaceAspectRating オブジェクトの配列を含みます。各オブジェクトは施設の 1 つの属性の評価を提供します。配列内の最初のオブジェクトがメインの特徴とみなされます。各 PlaceAspectRating は次のように定義されます。
      • type: 評価対象の特徴の名前。次のタイプがサポートされています。appeal、atmosphere、decor、facilities、food、overall、quality、service。
      • rating: この特徴についてのユーザーの評価（0～3）。
    • author_name: レビューを送信したユーザーの名前。匿名のクチコミは「Google ユーザー」になります。言語パラメータが設定されている場合、「Google ユーザー」はローカライズされた文字列を返します。
    • author_url は、ユーザーの Google+ プロフィールの URL（プロフィールがある場合）です。
    • language は、ユーザーのクチコミで使用される言語を指定する IETF 言語コードです。このフィールドにはメイン言語のタグのみが含まれ、国または地域を示す 2 次タグは含まれません。たとえば、英語のクチコミはすべてが「en」とタグ付けされ、「en-AU」や「en-UK」などのタグは含まれません。
    • rating: この場所に対するユーザーの総合評価。1〜5 の整数が含まれます。
    • text: ユーザーのクチコミ。Google プレイスで場所のクチコミを投稿する場合、テキストのクチコミは省略可能であるため、このフィールドは空になることもあります。
  • types: この場所のタイプの配列（["political", "locality"]、["restaurant", "lodging"] など）。この配列は複数の値を含むことも、空にすることもできます。新しい値が事前通知なしに導入される場合があります。サポートされているタイプのリストをご覧ください。
  • url: この場所の公式 Google ページの URL。これは、この場所について入手可能な最良の情報を含む Google のページです。アプリケーションでこの場所に関する詳細結果をユーザーに表示する場合、その画面にこのページへのリンクを設置するか、このページを埋め込む必要があります。
  • vicinity: 場所の簡単な住所です。番地や市町村などが含まれ、州、都道府県、郵便番号、国などは含まれません。たとえば、オーストラリアにある Google のシドニー オフィスの vicinity の値は 5/48 Pirrama Road, Pyrmont です。vicinity プロパティは、Nearby Search の場合にのみ返されます。
  • website: 会社のホームページなど、当該の場所の公式ウェブサイトが格納されます。

注: すべての場所に多層的な評価が存在するとは限りません。クチコミ数が少なすぎる場合、詳細のレスポンスには、従来の評価（0.0～5.0）が含まれる場合（評価がある場合）と、評価が何も含まれない場合があります。

プレイス ID を使用した場所の参照

プレイス ID は、Google マップ上の場所を表す一意の参照情報です。プレイス ID は、お店やサービス、名所、公園、交差点など、大部分の場所に利用できます。

アプリでプレイス ID を使用するには、まず ID を検索する必要があります。ID は、Place Search または Place Details リクエストの PlaceResult で確認できます。指定したプレイス ID を使用して、Place Details を検索できます。

プレイス ID は、Google Maps Platform 利用規約のセクション 3.2.3（b）で定められているキャッシュ制限の対象外となります。後で使用するためにプレイス ID の値を保存できます。プレイス ID を保存する際のおすすめの方法については、プレイス ID の概要をご覧ください。

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

場所の写真

Place Photo 機能を使用して、高画質な写真コンテンツをアプリケーションに追加できます。写真サービスを使えば、プレイスや Google+ ローカルのデータベースに保存されている数百万の写真を利用できます。Place Details リクエストを使って場所の情報を検索すると、関連する写真コンテンツに対する写真のリファレンスが返されます。Nearby Search リクエストや Text Search リクエストでも、関連する写真コンテンツがあれば、場所ごとに 1 つの写真のリファレンスが返されます。写真サービスでは、参照された写真にアクセスできるだけでなく、そうした画像をアプリケーションに最適なサイズに変更できます。

PlacesService に対して getDetails()、textSearch()、または nearbySearch() リクエストを実行すると、PlaceResult オブジェクトの一部として PlacePhoto オブジェクトの配列が返されます。

注: 返される写真の数はリクエストによって異なります。

  • Nearby Search や Text Search では、PlacePhoto オブジェクトが 1 つのみ返されます。
  • Place Details リクエストでは、最大 10 個の PlacePhoto オブジェクトが返されます。

関連画像の URL をリクエストするには、PlacePhoto.getUrl() メソッドを呼び出し、有効な PhotoOptions オブジェクトを渡します。PhotoOptions オブジェクトを使用すると、画像の高さと幅の最大値を指定できます。maxHeight と maxWidth の両方に値を指定すると、写真サービスでは、元のアスペクト比を維持しながら、この 2 つの値の小さい方を基準に画像サイズが変更されます。

次のコード スニペットは、場所のオブジェクトを受け入れ、写真が存在する場合に地図にマーカーを追加します。また、デフォルトのマーカー画像が、写真の縮小版に置き換えられます。

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

フォトサービスによって返される写真の提供元は、お店やサービスの所有者、ユーザーの投稿などさまざまです。こういった写真は、帰属情報なしで使用できる場合や、必要な帰属情報が画像内にあらかじめ記載されている場合がほとんどです。ただし、返された photo 要素の html_attributions フィールドに値が含まれる場合は、アプリケーション内でその画像を表示するすべての箇所で、追加の帰属情報として組み込む必要があります。