序論
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を使用するための準備・設定のガイドについても参照ください。 |
|
|
GET/POSTリクエストに対してインプットとアウトプットがどのように扱われるのか、そして条件を指定するためのパラメーターの利用方法を説明します。 |
|
|
クライアントに返却されるエラーと、エラーの意味を説明します。 |
APIメソッド
ここまでの内容でAPIの一般的な動作について学びました。このセクションでは、利用可能なAPIのメソッドについて一覧にしています。 APIのメソッドは、関連したAPIメソッドを論理的グループにしたパス構造で体系化されています。
|
APIに対する変更は後方互換となるように行われますが、リクエストとレスポンスのフィールドはAPIが更改されるとともに追加されることがあります。APIを使用するクライアントはこの点を考慮に入れて作成してください。 |
下記のAPIメソッドのドキュメントは現時点では英語版のみの提供です。
|
パス |
内容 |
|---|---|
|
/dmp |
DMPイベントに関連するAPI |
|
新しいDMPイベントを送信します。 |
|
|
DMPカスタムパラメータのラベルを取得します。 |
|
|
DMPカスタムパラメータのラベルをアップデートします。 |
|
|
DMPイベントデータの集計値を取得します。 |
|
|
DMPイベントデータのトップリストを取得します。 |
|
|
DMPイベントデータのカスタムパラメータに紐付いたトップリストを取得します。 |
|
|
DMPイベントデータの取得 |
|
|
総合的なユーザのDMPイベント分布を取得 |
|
|
ユーザのDMPイベントの濃度分布を取得 |
|
|
|
|
|
/document |
ドキュメントに関連するAPI |
|
ドキュメントを検索します。 |
|
|
ドキュメントを更新します。 |
|
|
ドキュメントを削除します。 |
|
|
/document/search で利用可能なフィールドをリストします。 |
|
|
|
|
|
/persisted |
API実行時に、Python などを利用せず、HTTPリクエストのみで実行したい場合に利用します。 事前に、どのAPIを利用して、どのフィールドを動的にパラメータで変更できるかを指定するために、Persistedリクエストを作成します。 APIの認証の代わりに、事前に登録したPersistedリクエストのidを指定してHTTPでアクセスを行います。 |
|
登録したPersistedリクエストの情報取得します。 |
|
|
Persistedリクエストを登録します。 |
|
|
Persistedリクエストを更新します。 |
|
|
Persisted リクエストを削除します。 |
|
|
Persisted リクエストを実行します。 |
|
|
|
|
|
/processing |
辞書のカスタマイズなどを行うAPI 例：Cxense Searchの同義語辞書など |
|
辞書データを取得します。 |
|
|
辞書データを作成します。 |
|
|
辞書データを削除します。 |
|
|
辞書データの新規アップロードならびに更新を行います。辞書データは、Excelのワークブック、またはJSON形式となります。 |
|
|
辞書データの検索を行います。 |
|
|
入力したテキストデータに対するコンテンツプロファイルを取得します。 |
|
|
|
|
|
/profile/content |
コンテンツプロファイルに関連するAPI |
|
指定したURLパターンで、コンテンツプロファイルへメタデータを付与する設定を削除します。 |
|
|
URLパターンで、コンテンツプロファイルへメタデータを付与する設定を全て削除します。 |
|
|
指定したURLパターンで、コンテンツプロファイルへメタデータを付与する設定を取得します。 |
|
|
URLパターンで、コンテンツプロファイルへメタデータを付与する設定を全て取得します。 |
|
|
URLパターンで、コンテンツプロファイルへメタデータを付与する設定を追加・更新します。 |
|
|
指定したURLのコンテンツプロファイルを取得します。 |
|
|
指定したURLを再クロールします。 |
|
|
指定したキーワードの関連語を取得します。 |
|
|
|
|
|
/profile/user |
ユーザープロファイルに関連するAPI |
|
指定したユーザーのプロファイルを取得します。 |
|
|
指定したユーザーに外部データを付与します。 |
|
|
指定したユーザーに付与された外部データを取得します。 |
|
|
指定したユーザーに付与された外部データを削除します。 |
|
|
指定した1st パーティクッキー(ckp)と紐づけされた外部IDを取得します。 |
|
|
マッピングされたすべてのユーザープロファイルを表示 |
|
|
指定した1st パーティクッキー(ckp)と指定した外部IDを紐づけします。 |
|
|
ユーザーがアサインされたセグメントの一覧を取得します。 |
|
|
|
|
|
/public |
認証時に利用するAPI（認証不要） |
|
認証ヘッダーに利用するための現在時刻を取得します。 |
|
|
|
|
|
/reports |
レポート取得のためのAPI |
|
/document/search APIで行われたトップクエリのレポート。サイトと日付を指定。 |
|
|
/document/search APIで行われたクエリ数のレポート。サイトと日付を指定。 |
|
|
|
|
|
/segment |
DMPオーディエンスセグメントの定義に関連するAPI |
|
オーディエンスセグメントを作成します。 |
|
|
オーディエンスセグメントを削除します。 |
|
|
オーディエンスセグメントの情報を取得します。 |
|
|
既存のオーディエンスセグメントを更新します。 |
|
|
|
|
|
セグメントに関連付けられたメタデータを取得 |
|
|
|
|
|
/segment/group |
DMPオーディエンスセグメントのグループに関連するAPI |
|
既存のセグメントグループの情報を取得します。 |
|
|
セグメントグループを作成します。 |
|
|
セグメントグループを更新します。 |
|
|
セグメントグループを削除します。 |
|
|
|
|
|
/segment/lookalike |
オーディエンス拡張 に関連するAPI |
|
オーディエンス拡張の設定情報を取得します。 |
|
|
オーディエンスセグメントのオーディエンス拡張設定を編集します。 |
|
|
オーディエンス拡張セグメントのモデル品質を詳しく確認します。 |
|
|
|
|
|
/site |
サイトとサイトグループに関するAPI |
|
サイトの情報を取得します。 |
|
|
サイトの作成します。 |
|
|
既存のサイトを更新します。 |
|
|
サイトグループの情報を取得します。 |
|
|
サイトグループを作成します。 |
|
|
既存のサイトグループの更新をします |
|
|
|
|
|
/traffic |
各種トラフィック情報を取得するAPIとなります。/traffic APIの概要説明のページも併せてご参照ください。 |
|
集計されたトラフィックデータを取得します。 指定された条件に合致するPV,UU,訪問数,平均滞在時間,ページ数,離脱数,直帰数を取得したい場合に利用します。 |
|
|
集計されたトラフィックデータのトップリストを取得します。 例えば、指定された条件に合致するトップ100のURL毎のPV,UU,訪問数,平均滞在時間,ページ数,離脱数,直帰数を取得したい場合などに利用します。 URLの他にも/traffic/event/describe で取得できるグループを指定することができます。 |
|
|
/traffic/event で利用可能なグループ名を調べたい時に利用します。 実行することで、/traffic/event で利用可能なグループ名の一覧を取得できます。 |
|
|
アクセスされたページのコンテンツプロファイルに含まれる各グループのトップリストを取得します。 例えば、指定した期間内にアクセスされたページから抽出されたキーワード（コンセプト）の一覧を取得することができます。 抽出されたキーワード以外にも、/traffic/keyword で取得できるグループを指定することができます。 |
|
|
/traffic/keyword で利用可能なグループ名を調べたい時に利用します。 実行することで、/traffic/keyword で利用可能なグループ名の一覧を取得します。 |
|
|
集計されたカスタムパラメータのトップリストを取得します。 カスタムパラメーターを利用してトラフィックデータを収集している場合には、利用しているカスタムパラメーター毎のPV,UU, 訪問数,平均滞在時間,ページ数,離脱数,直帰数を取得できます。 |
|
|
/traffic/custom で利用可能なグループ名を調べたい時に利用します。 実行することで、/traffic/custom で利用可能なグループ名を取得します。 この場合、設定しているカスタムパラメータのグループ名の一覧が取得できます。 |
|
|
異なるフィルターでの集計データを比較します。 デスクトップでのTOP10のURLならびにそのPV数を取得して、同時に、それらのURLに対してスマートフォンでのPV数を取得したい場合に利用します。 |
|
|
指定したページと、関連しているページを取得したい場合に利用します。このページを見ている他のユーザーもよく見ているページを取得できます。 |
|
|
アクセスのあったユーザーの外部ID（貴社会員IDなど）を取得できます。ただし、事前に外部ユーザーIDと1stパーティクッキーの紐づけを行う必要があります。 |
|
|
ユーザーの興味のあるカテゴリーのトップリストを取得します。 ただし、興味のあるカテゴリーの定義を事前に行う必要があります。 |
|
|
ユーザーのセグメンテーションや自宅や仕事場などのローケション毎のPV数やユニークユーザー数を取得できます。 セグメンテーションを作成するには、Cxense DMPの契約が必要となります。 |
|
|
外部データとして/profile/user/external/update で追加登録された各データ毎のトラフィックデータを取得します。 例えば、外部データとして年齢を設定した場合には、年齢毎のPVやUUを取得することができます。 |
|
|
各ユーザーのPV数毎のユニークユーザー数の分布情報を取得できます。 これを利用して、サイト内で各ユーザがどのくらいのPVをあげているかがわかります。 |
|
|
各ユーザーが、指定したグループ（/traffic/event/describeで取得した）のデータをいくつ持っているかに関しての分布情報を取得できます。 例えば、各ユーザーのデバイス数の分布情報を取得できます。 |
|
|
イベントデータの取得 |
シナリオ
アプリケーションの開発シナリオでは、通常複数のAPIやプラットフォームの機能を組み合わせて要求に応えます。 このセクションでは、ポインタと、いくつかの例から、一般的なシナリオに対処する最適な方法をご紹介します。
|
タスク |
内容 |
|---|---|
|
Microsoft Excelをお使いの場合のAPIでの使用方法について説明します。 |
|
|
コンテンツプロファイルの要素を修正または上書きする方法を説明します。 |
|
|
ユーザーデータの表示、およびエクスポートについて説明します。 |