概要

ユーザーは、PitneyBowes forward geocoding APIを活用することで、インプットしたアドレスから緯度/経度を取得し、ジオポイント値へ変換することができます。これは、顧客のアドレスを拡張する際に有効です。

このタイプのトランスフォーメーションは、データトランスフォーメーションモジュールで、PB - Forward Geocodeステップを使用することで実行することができます。

セットアップ

こちらのステップを使用するためには、Yellowfinの環境に、PitneyBowes Geocodeのプラグインをインストールしなくてはいけません。

Yellowfinのマーケットプレイスからプラグインをダウンロードします。（トランスフォーメーションステップ項目から検索することができます）
Yellowfinのインスタンスへこれをインストールします。プラグインのインストール方法については、こちらを参照してください。

こちらのステップは、2018年2月13日以降にリリースされた、Yellowfin 7.4で機能します。

設定概要

ステップの設定詳細について、簡単に概説します。

インプットオプション

基礎的な設定：アドレス全体が単一行のインプットとして提供される場合は、こちらの設定を使用します。
Advanced configuration（高度な設定）：アドレスの個々の要素が個別に指定されている場合は、こちらの設定を使用します。左側が空白のフィールド、またはnull値のフィールドは無視されます。こちらはより具体的な設定のため、Full Address（フルアドレス）バージョンよりも優れた結果を生成する傾向があります。

計算フィールドステップを使用し、各フィールドにプラス（+）演算子を用いることで、分割アドレスを連結することもできます。

API KeyとAPI Secret：これは、PitneyBowes APIへ接続するための詳細情報です。これらの値は、geocodingステップを実行するために必要です。API Keyを取得するためには、こちらを参照してください。：https://www.pitneybowes.com/us/developer/geocoding-apis.html
Preview Mode Row Limit（プレビューモードでのロウ（行）制限）：PitneyBowes APIは、トランスフォーメーションフローを構成、またはテストする際に、迅速に消費されるクレジットのシステムを使用します。こちらのフィールドを使用して、プレビュー実行でこのステップに消費されるクレジット量の上限を設定することができます。こちらの値を0に設定すると、制限は適用されません。各データロウ（行）がクレジットを使用するため、こちらで指定した数字は、データプレビューパネルに表示されるロウ（行）数に影響します。注意：クレジットは、フローがすでに発行され、実行されている場合には適用されません。

ステップの出力

APIは、アドレスに提供された詳細のレベルに基づき、可能な緯度/経度の一覧を返します。このステップは、この一覧から最初に一致したものを選択します。APIが何の一致も返さない場合は（不十分なアドレス詳細が提供された場合に発生する可能性があります）、null値が表示されます。

返されるポイントは、APIが作成した一致レベルの中心になります。例えば、住所が提供され、APIがこれを実際の住所と一致することができた場合、ジオポイントは実際のアドレスに配置されます。しかし、市町村区だけが一致した場合は、返されるジオポイントは市の中心地になります。

多くのデータベースはジオメトリーフィールド型を保存することができないため、一致したジオポイントは「POINT（緯度, 経度）」のテキスト文字列として返されます。例：POINT(-112.1234, 45.123)。この値は、データベース機能（SQLサーバ、など）や、Yellowfinのビューレベルのよく知られたテキスト、またはWKTコンバーターを使用したマップ表示のために、ジオメトリーオブジェクトに変換することができます。

ステップ設定手順

データトランスフォーメーションモジュールに移動します。（「作成」ボタン＞「トランスフォーメーションフロー」）
インプットステップ一覧を展開し、フローにデータをインポートするステップを使用します。
ジオポイントに変換するためのアドレス値が、データに含まれていることを確認してください。今回の例では、異なるフィールドに保存されているアドレス値を表示しています。
PitneyBowes Forward GeoCodeステップを使用する準備が整ったら、トランスフォーメーションステップパネルを表示し、フローにステップをドラッグします。
フロー内の前のステップと接続をします。
ステップをクリックして、トランスフォーメーションフローパネルに設定詳細を表示します。（ステップ設定の詳細概要を確認したい場合は、こちらをクリックしてください）
以下に説明するように、アドレスの設定には2つのオプションがあります。
1. 基礎的な設定：こちらのデフォルトモードでは、単一フィールドに含まれるFull Adress（フルアドレス）を含めることができます。Full Address（フルアドレス）ドロップダウンから、こちらのフィールドを選択します。
2. Advanced configuration（高度な設定）：アドレスが様々なフィールドに分割されている場合は、こちらのモードを使用します。
  1. Advanced configuration（高度な設定）トグルを有効にします。追加のオプション設定が表示されます。
  2. 異なるアドレスの詳細を選択します。
PitneyBowes API Keyと Secretを入力します。ステップを機能させるために、API Keyが使用制限を超過していないことを確認します。
注意：Yellowfinは、保存時にこの値を暗号化するため、これをセキュアに保つことができます。
プレビュー/テストモードでAPI詳細情報を使用できる回数の制限を設定します。これは、プレビューモードでのステップのテスト時にAPIクレジットを超過しないようにするために必要な設定です。こちらで定義した制限は、フル、またはスケジュールされた実行（例：プレビューモードではない場合）時の実際の試行回数に影響を与えません。
すべての設定が完了したら、「適用」ボタンをクリックします。
設定が適用されると、ステップは、変換されたジオポイントを表示する「LongLat」と呼ばれるカラム（列）を生成します。
注意：これは、この出力のデフォルトのカラム（列）名です。この名前は変更することができます。
さらにステップを追加して、データのトランスフォーメーションを継続するか、アウトプットステップを使用して結果を保存します。

トラブルシューティング

手順が失敗した場合は、様々な原因が考えられます。

- API Keyが使用制限を超過している。このステップの使用を継続するためには、新しいKeyが必要です。
- 提供されたAPI Keyが不正確であった。
- 提供されたインプットアドレスフィールドが不正確である（または、カラム（列）のデータ型に一致しない）。