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

エンリッチ取引履歴

概要

このガイドでは、位置情報と特定の販売者を照合し、その詳細を表示する方法を説明します。

「ACMEHCORP」のような略語を使った取引明細書を発行すると、お客様にはわかりにくい場合があります。これにより、請求に関する異議申し立てや追加のサポート費用が発生する可能性があります。代わりに、Acme Housewares などの完全な販売者名を指定することをおすすめします。

エンリッチ取引履歴を使用すると、販売者の正式名称、業種、店頭の画像、連絡先や場所の詳細など、直感的に理解できる取引情報を簡単に提供できます。これにより、透明性が高まり、ネットプロモータースコア（NPS）が向上し、アプリの使用時間が長くなります。

未加工の取引明細とエンリッチされた販売者の詳細を比較するモバイル画面のサンプル — エンリッチ取引履歴のサンプル画面（クリックして拡大）

API を有効にする

エンリッチ取引履歴を実装するには、Google Cloud コンソールで次の API を有効にする必要があります。次のリンクから Google Cloud コンソールを開き、選択したプロジェクトで各 API を有効にできます。

設定について詳しくは、Google Maps Platform スタートガイドをご確認ください。

実装ガイドのセクション

このガイドでは、次の実装とカスタマイズについて説明します。

	販売者と Google Maps Platform の照合	取引履歴内の販売者を、Google Maps Platform の場所に関連付ける。
	販売者の詳細を表示する	豊富なデータを含む取引履歴を使用して、販売者に関する有用な情報を表示し、ユーザーが取引内容をすぐに把握できるようにする。
	販売者の所在地の地図を追加する	高度なマーカーを使用して、販売者の所在地の地図を追加する。

販売者と Google Maps Platform の照合

この例で使用する API: Places API（新版）

その他: JavaScript

次のフローチャートは、アプリケーションで、販売者の既存のデータベースの Place Details やテキスト検索リクエストを介して販売者の取引履歴が照合され、結果が返される仕組みを示しています。

販売者の取引記録をプレイス ID と Place Details に一致させるフローチャート — 販売者の照合フローの図（クリックして拡大）

Google Maps Platform のプレイス ID を取得する

事業の名称や住所など、基本情報を格納する販売者のデータベースがあるとします。特定の場所に関する情報（連絡先情報やユーザーが入力した評価など）を Google Maps Platform から取得するには、データベース内の販売者ごとに、対応するプレイス ID が必要になります。

ビジネスのプレイス ID を取得するには、Places API（新版）のテキスト検索（新版）エンドポイントを呼び出し、フィールドマスクで places.id フィールドのみをリクエストします。これにより、Text Search Essentials（ID のみ）SKU がトリガーされます。販売者に複数の所在地がある場合は、クエリに販売者名と市町村名を含めます。返された結果を検証して、販売者と一致していることを確認します。

たとえば、販売者名と市町村名を使用して、Google 台北オフィスのプレイス ID をリクエストする場合は以下のようになります。

curl -X POST -d '{
  "textQuery" : "Google Taipei"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

プレイス ID を保存する

今後のリクエスト用に Google Maps Platform の販売者情報を保管しておくには、販売者レコードの属性として、プレイス ID をデータベースに無期限に保存することをおすすめします。テキスト検索（新版）リクエストは、販売者ごとに 1 回だけ実行する必要があります。また、ユーザーが取引明細をリクエストするたびにプレイス ID を検索することもできます。

保存したプレイス ID の正確性を維持するには、フィールドマスクで id フィールドのみを指定した Place Details（新版）リクエストを実行して、12 か月ごとにプレイス ID を更新します。

表示する Place Details が、ユーザーが取引した販売者と一致しない場合は、ユーザーが販売者の照合の精度に関するフィードバックを送信できるようにすることをおすすめします。

販売者の詳細を表示する

この例で使用する API: Places API（新版）

その他: Places SDK for Android | Places SDK for iOS | プレイスライブラリ、Maps JavaScript API

ユーザーが店舗を訪問した後に、必要な Place Details を共有できます。Places API（新版）で Place Details（新版）エンドポイントを呼び出すと、Google Maps Platform 利用規約の範囲内で、レスポンスをフィルタして、情報ウィンドウ、ウェブサイドバー、モバイルの詳細ビューにレンダリングできます。

販売者名、住所、地図、連絡先情報が表示されたモバイル取引明細ビュー — 販売者の詳細画面のサンプル（クリックして拡大）

Place Details エンドポイントにリクエストを発行するには、各店舗のプレイス ID が必要です。販売者の店舗のプレイス ID を取得する方法については、Google Maps Platform のプレイス ID を取得するをご覧ください。

次の Place Details（新版）リクエストの場合は、Google 台北 101 のプレイス ID の JSON 形式として、表示名、フォーマットされた住所、座標、ウェブサイト、電話番号、アイコン、営業時間、評価が返されます。

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: displayName,formattedAddress,location,websiteUri,nationalPhoneNumber,iconMaskBaseUri,regularOpeningHours,rating' \
'https://places.googleapis.com/v1/places/ChIJraeA2rarQjQRyAqIxkx2vN8'

Maps JavaScript API を使用してウェブアプリケーションを構築している場合は、Place クラスを使用して、クライアントで同じフィールドを取得することもできます。

const place = new google.maps.places.Place({
  id: "ChIJraeA2rarQjQRyAqIxkx2vN8",
});

await place.fetchFields({
  fields: [
    "displayName",
    "formattedAddress",
    "location",
    "websiteURI",
    "nationalPhoneNumber",
    "regularOpeningHours",
    "rating",
  ],
});

販売者の所在地の地図を追加する

この例で使用する API: Maps JavaScript API | Geocoding API | Maps Static API

その他: Android | iOS

販売者の所在地を確認する

Place Details の地理座標を使用して、地図上にマーカーを配置できます。販売者のデータベースに地理座標がなく、番地しかない場合、Place Details をリクエストしていなければ、Geocoding API を使ってサーバー側で番地を緯度と経度の座標に変換し、それらの座標をデータベースに保存して、少なくとも 30 日に 1 回更新することができます。

次の例では、Geocoding API を使用して Google 台北オフィスのプレイス ID の緯度と経度を取得しています。

```html
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJraeA2rarQjQRyAqIxkx2vN8&key=YOUR_API_KEY
```

ウェブマップに高度なマーカーを追加する

ユーザーが、情報を参照したり操作したりするためではなく、取引を確認するために地図を見る場合は、操作が制限された地図を設定し、販売者の場所に高度なマーカーを配置します。高度なマーカーを使用するには、マップ ID と marker ライブラリ（libraries=marker）が必要です。

まず、libraries=marker を使用して Maps JavaScript API を読み込み、地図用のコンテナ div を追加します。

<script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=marker&callback=initMap"></script>
<div id="map" style="height: 300px; width: 100%;"></div>

次に、gestureHandling: "none" と zoomControl: false を使用して地図を初期化し、インタラクティビティを制限します。mapId を指定し、販売者の座標に google.maps.marker.AdvancedMarkerElement を作成します。

function initMap() {
  const merchantLocation = { lat: 25.033976, lng: 121.5645389 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: merchantLocation,
    zoom: 16,
    mapId: "DEMO_MAP_ID",
    gestureHandling: "none",
    zoomControl: false,
  });

  new google.maps.marker.AdvancedMarkerElement({
    map,
    position: merchantLocation,
    title: "Google Taipei",
  });
}

また、ピンの背景、枠線、グリフの色を変更したり、販売者のカテゴリにカスタムグラフィック画像を指定したりして、高度なマーカーをカスタマイズすることもできます。

静的な地図画像を追加する

パソコンやモバイルウェブでインタラクティブでない地図画像を使用する場合は、販売者の緯度 / 経度座標または住所のマーカーを 1 つ使用して Maps Static API の URL を作成します。Maps Static API は、指定したパラメータに基づいて地図の画像モードを返します。

次のリクエストでは、サイズが 640×480 ピクセル、Google 台北オフィスの赤いマーカーを中心とした、Cloud ベースのマップスタイルが適用された道路地図が返されます。

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:red%7C25.033976%2C121.5645389&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

次の表に、リクエストの各セクションの説明を示します。

API URL	https://maps.googleapis.com/maps/api/staticmap?
画像サイズ	size=640x480
販売者の位置マーカー（URL エンコードを使用）	markers=color:red%7C25.033976%2C121.5645389
Cloud ベースのマップのスタイル設定	map_id=b224095f76859890
API キー	key=YOUR_API_KEY
デジタル署名（リクエストにデジタル署名する方法をご覧ください）	signature=`BASE64_SIGNATURE`

このリクエストにより、次の静的地図画像が生成されます。

Google 台北オフィスを中心とした地図。赤い位置マーカーが表示されている

住所をマーカーの位置として渡すこともできます。

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:green%7CTaipei%20101%20Tower%2CNo.%207信義路五段信義區台北市%20Taiwan%20110&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

その他のパラメータオプションについては、Maps Static API のドキュメントをご覧ください。

モバイルアプリに地図を追加する

Maps SDK for Android または Maps SDK for iOS を使用している場合は、Place Details の座標を基に高度なマーカーを配置できます。

ユーザーが、情報を参照したり操作したりするためではなく、取引を確認するために地図を見る場合は、操作が制限された地図を構成します。

Android アプリの場合は、Android 向けの高度なマーカーとマーカーを含む地図を追加するをご覧ください。また、ライトモードを有効にして、操作を制限することもできます。
iOS アプリの場合は、iOS 向けの高度なマーカーとマーカーを含む地図を追加するをご覧ください。また、GMSUISettings クラスを使用してコントロールと操作を無効にする方法もご覧ください。