SingularのReporting APIへようこそ。SingularのReporting APIは、マーケティングキャンペーンに関する統計情報を集約し、社内のBIシステムやマーケティングパフォーマンスダッシュボードに取り込むことができます。

このガイドでは、Singular Reporting API、ユースケースの理解、クエリの実行方法について説明します。

まずこのガイドをお読みになり、次にReportingAPI リファレンスで技術的な詳細をご確認ください。

はじめにお客様のユースケースを理解する

Singularは様々なソースからデータを収集し、統合します（詳しくはUnderstanding Singular Reporting Dataをお読みください）。

レポーティングAPIを使用する際、見たいデータを選択することができます：

• キャンペーンコストなど、パートナーの広告ネットワークや広告代理店からの 集計データ；
• アトリビューショントラッカー /MMPからの 集計データ（BIシステムに取り込み、必要に応じてネットワークデータと結合することができます；
• ネットワークデータとトラッカーデータをSingularがスマートに結合した結果の結合データ。

すべてのクエリーは同じエンドポイント（Create Async Report）を通して実行されますが、クエリーに含めるフィールドが異なります。

始めるには、APIから何を得たいかを理解してください：

ユースケースです：	ご覧ください：
Singularを使ってすべての広告ネットワークや広告代理店からキャンペーンデータを収集しています。 コストとランレートに関するデータを取得したい。	ネットワークデータの照会
Singularのアトリビューションサービスを使用しているか、サードパーティのアトリビューショントラッカー用のデータコネクターを設定しています。 コンバージョンや収益などのトラッカーデータを取得し、BIプラットフォームや分析に取り込みたい。 トラッカーデータを広告ネットワークデータ（キャンペーンコストなど）と結合してROASを計算する場合は、独自のツールを使用する予定です。	トラッカーデータとネットワークデータを別々にクエリする
Singularアトリビューションサービスを使用している、またはサードパーティのアトリビューショントラッカーのデータコネクターを設定している。 ネットワークデータとトラッカーデータを可能な限り高い粒度で結合するために、Singularの既成ロジックを利用したいとお考えでしょう。	結合データのクエリ

レポートAPIで利用できるデータの種類

ネットワークデータのクエリ

ネットワークデータには、Singularで設定したすべての広告ネットワークから取り込まれたキャンペーン統計が含まれます。アトリビューショントラッカー（Singularで設定している場合）からのデータは含まれません。

例えば、クエリを実行して、指定した日付範囲の各キャンペーン（adn_campaign_id）のコスト（adn_cost）を見ることができます。

ネットワーク・データで利用可能なフィールド

各フィールドの説明については、メトリックとディメンションのページを参照してください。

トラッカーデータとネットワークデータを別々にクエリする

APIを使用して、SingularのアトリビューションサービスまたはSingularで設定したサードパーティのアトリビューショントラッカー（AppsflyerやGoogle Analyticsなど）からトラッカーデータ（統計情報）を引き出すことができます。

例えば、クエリを実行して、指定した日付範囲内の各キャンペーン（tracker_campaign_id）のクリック数（tracker_clicks）とインストール数（tracker_installs）を見ることができます。トラッカーの統計には、インストール後のイベントと収益も含まれます。

トラッカーデータのクエリを実行した後、キャンペーンCPIまたはROIを計算できるように、ネットワークデータと結合する ことができます。

しかし、同じ結果を得るには、通常、結合レポートを実行する方が簡単です。

トラッカーデータで利用可能なフィールド

各フィールドの説明については、Metrics and Dimensionsページを参照してください。

結合データのクエリ

APIを使用して、ネットワークとトラッカーを組み合わせたクエリを実行することができます。これは、キャンペーンコストと収益またはその他のキャンペーンパフォーマンスKPIの両方を表示します。

このタイプのクエリは、トラッカーとネットワークのデータに基づく特別なディメンションとメトリクスを使用しますが、以下で詳述するように、舞台裏で追加のロジックが関与します。

複合クエリとは何ですか？

1. ネットワーク統計（コストなど）とトラッカー統計（インストールや収益など）の両方を同じクエリに含めます。

2. スマートディメンションは、可能な限りネットワークとトラッカーのデータを同じ行にまとめるのに役立ちます。

   Singularの "結合 "または "統合 "ディメンションは、ネットワークとトラッカーの両方のデータに基づいています。これらはSingularによって処理され、一般的なデータの不一致を修正し、可能な限り高い粒度で結合されたデータを確認できるようにします。

   例えば、トラッカー内の特定のキャンペーン名は、広告ネットワークから引き出されたキャンペーン名とは若干異なる場合があります。そのため、トラッカーレポートとネットワークレポートを実行し、結果を結合すると、キャンペーンの行が分割され、一方の行にはネットワーク統計が、もう一方にはトラッカー統計が表示されることがあります。しかし、（unified_campaign_nameディメンジョンを使って）結合レポートを実行すると、Singularはキャンペーンの同じ行でネットワーク統計とトラッカー統計の両方を取得できるようにします。

3. スマートでカスタマイズ可能なメトリクスは、それぞれのケースで適切なソースからデータを引き出します。

   同じ統計がネットワークとトラッカーの両方から提供されている場合、例えば、指定された日付範囲におけるキャンペーンごとのインストール数など、結合されたメトリクスは単一の真実のソースを提供し、業界の標準的な使用法に基づいてトラッカー統計またはネットワーク統計のいずれかをインテリジェントに選択します。

   例えば、custom_installs メトリックにはトラッカーからのインストール数が含まれますが、Facebook や Twitter のようなSAN (Self-Attributed Network) の場合はネットワーク統計の方が重要であり、custom_installs にはネットワークメトリックが含まれます。

   Singularのデフォルトの選択があなたの特定のケースに合わない場合は、Singularに特定のメトリクスを再設定してもらうことができます。

   注： カスタムメトリクスはクリエイティブブレイクダウンでは使用できません。ネットワークメトリクスまたはトラッカーメトリクスのいずれかを選択してください。

メトリクスのソースを知りたい場合はどうすればよいですか？

各キャンペーンの各メトリクスの正確なソースを知りたい場合があります。例えば、ネットワークとトラッカーの間の大きな不一致を見つけ、トラブルシューティングをしようとしている場合などです。

その場合、ネットワーク指標（ネットワークデータの利用可能フィールドを参照）とトラッカー指標（トラッカーデータの利用可能フィールドを参照）を結合レポートに追加できます。たとえば、custom_installs、adn_installs、tracker_installsの3つのインストール・メトリクスをすべて引き出します。

この方法では、custom_installsをKPIとして使用しながら、adn_installsとtracker_installsの間に有意な差があるかどうかを確認できます。

結合データで使用可能なフィールド

各フィールドの説明については、メトリクスとディメンジョンのページを参照してください。

まとめ：どのような種類のデータが利用できますか？

	私がSingularを使っているのは
	アナリティクス + Singularアトリビューション	アナリティクスのみで、サードパーティのトラッカーからデータを取得するようにSingularを設定しています。	広告ネットワークからのみデータを取得
ネットワークデータ	利用可能	利用可能	利用可能
トラッカーデータ	利用可能	利用可能	-
複合フィールド	利用可能	自己帰属ネットワークで利用可能（クリエイティブ・ブレイクダウンなし）	-

レポートAPIをクエリする方法

クエリするデータのタイプを決定し、関心のある特定のメトリクスとディメンションのリストを作成したら、レポートAPIの使用方法を説明します。

基本的なクエリの実行

1	選択したメトリクスとディメンションを指定して、Create Async Reportエンドポイント（エンドポイント・リファレンスを参照）にクエリします。 これにより、非同期レポート・クエリが生成され、レポート ID が返されます。
2	レポート ID を使用して、Get Report StatusAPI エンドポイント（エンドポイント参照を参照）にクエリを実行し、レポートの実行がいつ終了したかを確認します。 レポートが終了すると、Get Report StatusエンドポイントはレポートURLを返します。
3	レポート URL からレポートをダウンロードします。

デイリーレポートの実行

Singularのデータは毎日更新されます。通常、以下のようなデータを毎日Singularから取得します：

• 昨日のデータ
• ネットワークによって更新された過去のデータ。

通常のデイリーレポートでは、以下のタイムウィンドウを使用してヒストリカルデータを取得することをお勧めします：

クエリータイプ	推奨タイムウィンドウ
ネットワーク・データ	7日前
トラッカー・データまたは複合データ	最長コホート期間と同じ期間。例えば、30日間のコホートがある場合、30日間遡ってクエリーします。収益などのコホートデータを取得しない場合は、通常7日前のデータで十分です。

データ可用性の確認

Data Availability Statusエンドポイントを使用すると、各データコネクタについて、指定された日付のデータがSingularにあるかどうか、そのデータが最後に更新されたのはいつかを確認できます。

このエンドポイントの最も一般的な使い方は、各データコネクタについて、昨日のデータがすでに利用可能か どうかを確認することです。これにより、すべてのデータ・コネクタの準備が整えば、すべてのデータについてレポートの実行を開始できます。一部のデータ・コネクタにしかデータがなく、他のデータ・コネクタに はデータがない場合は、すべてのデータ・コネクタの準備が完了するのを待つか、データが利用可能に なったときに各データ・ソースに対してレポートを実行するかを選択します。(非同期レポートの作成で単一のデータ・コネクタに対してレポートを実行するには、data_connector_id でレポートをフィルタリングします)。

Singularでは、同じクエリで複数のデータコネクタ/ソースに対してレポートを実行することは推奨していません。

データの最新性の確認

Singularでネットワーク・データの最新性を確認するには、レポート・クエリにdata_connector_timestamp_utcディメンジョンを含めます。

このディメンジョンには、Singularがデータコネクタからデータの取り込みを開始した日時が含まれます（データの取り込み、処理、Singularデータベースへの保存にかかった時間に関係なく）。

データのタイムスタンプの使用例には次のようなものがあります：

• Singularのレポートとネットワークダッシュボードのデータに矛盾がある場合。
• Singularのデータ転送先（ETL）を使ってSingularからBIプラットフォームにデータを取り込み、Singularに新しいデータがあるかどうかを確認したい場合。