Piano Insight API

序論

Piano Insightのプラットフォームは、サイト全体のトラフィックやサイトコンテンツの参照方法などを、リアルタイムで洞察するための柔軟性のあるツールです。
このページでは、Piano Insight APIの使用方法の概要、および詳細の説明とそれぞれのAPIの使用例を説明します。

JavaScript APIに関しては、イベントデータのセクションをご参照下さい。

本セクションに記載されているJSON APIの使用方法は、サインアップ済みで Piano Insightアカウントを持っており、APIに対して認証を行えることを前提としています。

コンセプト

まずは以下のドキュメントから概要を把握し、Piano Insightプラットフォームがどのように動作するのかの全体像をつかむことで、プラットフォームとAPIを有効にお使いいただけます。

タイトル	内容

タイトル	内容
プラットフォーム入門	プラットフォームの全体の概要、および、初めてPiano Insightプラットフォームを使う際に、何を行うのかを説明します。
サイトとサイトグループ	サイトとは何か、そしてサイトとサイトグループの関係性を説明します。
クロール	いつ、どのようにサイトがクロールされるのか、そしてPiano Insight のクローラーを識別する方法について説明します。
ドキュメント（ページ）のパース	クロールされたサイトページの解析について、およびサイトページに属性情報を追加する方法を説明します。
コンテンツプロファイル	コンテンツプロファイルの生成方法、コンテンツプロファイルとはなにか、そして、コンテンツプロファイルをPianoのシステムがどのように使用するのかを説明します。
ユーザープロファイル	ユーザープロファイルの生成方法、ユーザープロファイルとはなにか、そして、ユーザープロファイルがPiano Insightのシステムにてどのように使用されるのかを説明します。
カスタムタクソノミー	コンテンツプロファイルとユーザープロファイルの生成をカスタマイズする方法を説明します。
外部データ	コンテンツとユーザーに関する外部のデータを Piano Insight プラットフォームに取り込む方法を説明します。
イベントデータ	イベントをプラットフォームへ送信する方法を説明します。例えば、ページビューイベントの送信を、JavaScript APIおよびHTTP APIで行う方法を記載しています。
カスタムパラメータ	カスタムパラメータをプラットフォームへ送信する方法を説明します。例えば、イベントに対してよりリッチなメタデータを付与する方法を記載しています。
計測値	Piano Insight ツールにおける標準的な測定項目、およびそれらが何を測定しているかを説明します。また、他の同様なシステムとの差異に対しても記載しています。
ユーザートラッキングとプライバシー	プラットフォームがユーザーをトラッキングする方法、使用しているテクノロジー、そして、ユーザーがオプトイン/アウトする方法について説明します。
Audience estimation	オーディエンス推定の使用方法を説明します。
Short term intents	ユーザーの興味・嗜好の測定方法について説明します。
Long term storage (LTS)	データ保持期間として標準とLTSご契約時の違いについて説明します。
セグメントマッチング詳解	複雑なオーディエンスセグメントの定義方法と、またセグメントの付与方法を説明します。

使用方法

まずプラットフォームの基本コンセプトに慣れるために、APIを実際に使ってみましょう。 APIはHTTPSで通信し、ユーザ認証により権限が決まります。APIは、データフォーマットとしてJSONを使います。個々のAPIメソッドを試す前に、一般的にAPIがどのように動作するのか見てみましょう。

タイトル	内容

タイトル	内容
APIの認証方法	認証方式についてサンプルを交えて説明します。APIを使用するための準備・設定のガイドについても参照ください。
リクエストとレスポンス	GET/POSTリクエストに対してインプットとアウトプットがどのように扱われるのか、そして条件を指定するためのパラメーターの利用方法を説明します。
エラーコードおよびレスポンス	クライアントに返却されるエラーと、エラーの意味を説明します。

APIメソッド

ここまでの内容でAPIの一般的な動作について学びました。このセクションでは、利用可能なAPIのメソッドについて一覧にしています。 APIのメソッドは、関連したAPIメソッドを論理的グループにしたパス構造で体系化されています。

APIに対する変更は後方互換となるように行われますが、リクエストとレスポンスのフィールドはAPIが更改されるとともに追加されることがあります。APIを使用するクライアントはこの点を考慮に入れて作成してください。

下記のAPIメソッドのドキュメントは現時点では英語版のみの提供です。

パス	内容

パス	内容
/dmp	DMPイベントに関連するAPI
/dmp/push	新しいDMPイベントを送信します。
/dmp/title	DMPカスタムパラメータのラベルを取得します。
/dmp/title/update	DMPカスタムパラメータのラベルをアップデートします。
/dmp/traffic	DMPイベントデータの集計値を取得します。
/dmp/traffic/event	DMPイベントデータのトップリストを取得します。
/dmp/traffic/custom	DMPイベントデータのカスタムパラメータに紐付いたトップリストを取得します。
/dmp/traffic/data	DMPイベントデータの取得
/dmp/traffic/user/histogram	総合的なユーザのDMPイベント分布を取得
/dmp/traffic/user/histogram/event	ユーザのDMPイベントの濃度分布を取得

/document	ドキュメントに関連するAPI
/document/search	ドキュメントを検索します。
/document/update	ドキュメントを更新します。
/document/delete	ドキュメントを削除します。
/document/describe	/document/search で利用可能なフィールドをリストします。

/persisted	API実行時に、Python などを利用せず、HTTPリクエストのみで実行したい場合に利用します。事前に、どのAPIを利用して、どのフィールドを動的にパラメータで変更できるかを指定するために、Persistedリクエストを作成します。 APIの認証の代わりに、事前に登録したPersistedリクエストのidを指定してHTTPでアクセスを行います。
/persisted	登録したPersistedリクエストの情報取得します。
/persisted/create	Persistedリクエストを登録します。
/persisted/update	Persistedリクエストを更新します。
/persisted/delete	Persisted リクエストを削除します。
/persisted/execute	Persisted リクエストを実行します。

/processing	辞書のカスタマイズなどを行うAPI 例：Cxense Searchの同義語辞書など
/processing/dictionary/read	辞書データを取得します。
/processing/dictionary/create	辞書データを作成します。
/processing/dictionary/delete	辞書データを削除します。
/processing/dictionary/update	辞書データの新規アップロードならびに更新を行います。辞書データは、Excelのワークブック、またはJSON形式となります。
/processing/dictionary/search	辞書データの検索を行います。
/processing/linguistics/execute	入力したテキストデータに対するコンテンツプロファイルを取得します。

/profile/content	コンテンツプロファイルに関連するAPI
/profile/content/external/delete	指定したURLパターンで、コンテンツプロファイルへメタデータを付与する設定を削除します。
/profile/content/external/deleteAll	URLパターンで、コンテンツプロファイルへメタデータを付与する設定を全て削除します。
/profile/content/external/read	指定したURLパターンで、コンテンツプロファイルへメタデータを付与する設定を取得します。
/profile/content/external/readAll	URLパターンで、コンテンツプロファイルへメタデータを付与する設定を全て取得します。
/profile/content/external/update	URLパターンで、コンテンツプロファイルへメタデータを付与する設定を追加・更新します。
/profile/content/fetch	指定したURLのコンテンツプロファイルを取得します。
/profile/content/push	指定したURLを再クロールします。
/profile/content/related	指定したキーワードの関連語を取得します。

/profile/user	ユーザープロファイルに関連するAPI
/profile/user	指定したユーザーのプロファイルを取得します。
/profile/user/external/update	指定したユーザーに外部データを付与します。
/profile/user/external/read	指定したユーザーに付与された外部データを取得します。
/profile/user/external/delete	指定したユーザーに付与された外部データを削除します。
/profile/user/external/link	指定した1st パーティクッキー(ckp)と紐づけされた外部IDを取得します。
/profile/user/external/link/list	マッピングされたすべてのユーザープロファイルを表示
/profile/user/external/link/update	指定した1st パーティクッキー(ckp)と指定した外部IDを紐づけします。
/profile/user/segment	ユーザーがアサインされたセグメントの一覧を取得します。

/public	認証時に利用するAPI（認証不要）
/public/date	認証ヘッダーに利用するための現在時刻を取得します。

/reports	レポート取得のためのAPI
/reports/search	/document/search APIで行われたトップクエリのレポート。サイトと日付を指定。
/reports/search/usage	/document/search APIで行われたクエリ数のレポート。サイトと日付を指定。

/segment	DMPオーディエンスセグメントの定義に関連するAPI
/segment/create	オーディエンスセグメントを作成します。
/segment/delete	オーディエンスセグメントを削除します。
/segment/read	オーディエンスセグメントの情報を取得します。
/segment/update	既存のオーディエンスセグメントを更新します。
/segment/data/update	`external`タイプのセグメントのメンバを更新します。
/segment/metadata	セグメントに関連付けられたメタデータを取得

/segment/group	DMPオーディエンスセグメントのグループに関連するAPI
/segment/group/read	既存のセグメントグループの情報を取得します。
/segment/group/create	セグメントグループを作成します。
/segment/group/update	セグメントグループを更新します。
/segment/group/delete	セグメントグループを削除します。

/segment/lookalike	オーディエンス拡張に関連するAPI
/segment/lookalike	オーディエンス拡張の設定情報を取得します。
/segment/lookalike/update	オーディエンスセグメントのオーディエンス拡張設定を編集します。
/segment/lookalike/quality	オーディエンス拡張セグメントのモデル品質を詳しく確認します。

/site	サイトとサイトグループに関するAPI
/site	サイトの情報を取得します。
/site/create	サイトの作成します。
/site/update	既存のサイトを更新します。
/site/group	サイトグループの情報を取得します。
/site/group/create	サイトグループを作成します。
/site/group/update	既存のサイトグループの更新をします

/traffic	各種トラフィック情報を取得するAPIとなります。/traffic APIの概要説明のページも併せてご参照ください。
/traffic	集計されたトラフィックデータを取得します。指定された条件に合致するPV,UU,訪問数,平均滞在時間,ページ数,離脱数,直帰数を取得したい場合に利用します。
/traffic/event	集計されたトラフィックデータのトップリストを取得します。例えば、指定された条件に合致するトップ100のURL毎のPV,UU,訪問数,平均滞在時間,ページ数,離脱数,直帰数を取得したい場合などに利用します。 URLの他にも/traffic/event/describe で取得できるグループを指定することができます。
/traffic/event/describe	/traffic/event で利用可能なグループ名を調べたい時に利用します。実行することで、/traffic/event で利用可能なグループ名の一覧を取得できます。
/traffic/keyword	アクセスされたページのコンテンツプロファイルに含まれる各グループのトップリストを取得します。例えば、指定した期間内にアクセスされたページから抽出されたキーワード（コンセプト）の一覧を取得することができます。抽出されたキーワード以外にも、/traffic/keyword で取得できるグループを指定することができます。
/traffic/keyword/describe	/traffic/keyword で利用可能なグループ名を調べたい時に利用します。実行することで、/traffic/keyword で利用可能なグループ名の一覧を取得します。
/traffic/custom	集計されたカスタムパラメータのトップリストを取得します。カスタムパラメーターを利用してトラフィックデータを収集している場合には、利用しているカスタムパラメーター毎のPV,UU, 訪問数,平均滞在時間,ページ数,離脱数,直帰数を取得できます。
/traffic/custom/describe	/traffic/custom で利用可能なグループ名を調べたい時に利用します。実行することで、/traffic/custom で利用可能なグループ名を取得します。この場合、設定しているカスタムパラメータのグループ名の一覧が取得できます。
/traffic/compare	異なるフィルターでの集計データを比較します。デスクトップでのTOP10のURLならびにそのPV数を取得して、同時に、それらのURLに対してスマートフォンでのPV数を取得したい場合に利用します。
/traffic/related	指定したページと、関連しているページを取得したい場合に利用します。このページを見ている他のユーザーもよく見ているページを取得できます。
/traffic/user	アクセスのあったユーザーの外部ID（貴社会員IDなど）を取得できます。ただし、事前に外部ユーザーIDと1stパーティクッキーの紐づけを行う必要があります。
/traffic/user/interest	ユーザーの興味のあるカテゴリーのトップリストを取得します。ただし、興味のあるカテゴリーの定義を事前に行う必要があります。
/traffic/user/keyword	ユーザーのセグメンテーションや自宅や仕事場などのローケション毎のPV数やユニークユーザー数を取得できます。セグメンテーションを作成するには、Cxense DMPの契約が必要となります。
/traffic/user/external	外部データとして/profile/user/external/update で追加登録された各データ毎のトラフィックデータを取得します。例えば、外部データとして年齢を設定した場合には、年齢毎のPVやUUを取得することができます。
/traffic/user/histogram	各ユーザーのPV数毎のユニークユーザー数の分布情報を取得できます。これを利用して、サイト内で各ユーザがどのくらいのPVをあげているかがわかります。
/traffic/user/histogram/event	各ユーザーが、指定したグループ（/traffic/event/describeで取得した）のデータをいくつ持っているかに関しての分布情報を取得できます。例えば、各ユーザーのデバイス数の分布情報を取得できます。
/traffic/data	イベントデータの取得

シナリオ

アプリケーションの開発シナリオでは、通常複数のAPIやプラットフォームの機能を組み合わせて要求に応えます。このセクションでは、ポインタと、いくつかの例から、一般的なシナリオに対処する最適な方法をご紹介します。

タスク	内容

タスク	内容
Excelの利用	Microsoft Excelをお使いの場合のAPIでの使用方法について説明します。
コンテンツプロファイルの手動チューニング	コンテンツプロファイルの要素を修正または上書きする方法を説明します。
ユーザーデータの取得	ユーザーデータの表示、およびエクスポートについて説明します。