Reporting API

InMobi Publisher Reporting API 3.0 を使用してあなたのアプリのパフォーマンスデータを自動的にダウンロードすることが可能です。このガイドではAPIの主な機能と使用例を示します。

Publisher reporting API はREST 形式で JSON フォーマットをサポートしています。Reporting API の実行にはAPI key を secretKey として渡す必要があります。

API Endpoint:

JSON Response: https://api.inmobi.com/v3.0/reporting/publisher ヘッダーに "Content-Type:application/json" と "Accept:application/json" を指定します。

以下の簡単なステップに従い実装を開始してください。

API Key の生成

API key はInMobiが生成する証明書になります。

InMobi ダッシュボード のAccount SettingsからAPI keyを生成します。

ここで生成されたAPI key は以降のステップで使用するので、コピーして控えておいてください。次回以降ログインした際には、API key は表示されない状態になっています。

注意: API key を再度生成することは可能です。ただし、新しくAPI key を生成すると、以前生成したAPI key は即時に無功なものになります。

有効なAPI key の確認方法

もし複数のAPI key を生成し、どのAPI key が有効なものかわからなくなってしまった場合、以下のステップに従い確認してください。API key の設定画面へのアクセスに関しては前章をご参照ください。

有効なSessionのリクエスト

API リクエストを実行する際には、有効なSession が必須となります。Sessionの有効期間は生成後24時間です。ひとつのAPI key で生成できるSession の上限数は24時間で15個になります。

サンプル リクエスト 1

curl -v https://api.inmobi.com/v1.0/generatesession/generate  
-H "userName:#######" 
-H "secretKey:########"
		

サンプル リクエスト 2

curl -v https://api.inmobi.com/v1.0/generatesession/generate  
-H "userName:#######" 
-H "password:#########" 
-H "secretKey:########"
		

注意: Session の生成時にPassword は必須ではありません。(以前のバージョンの実装で)既にPassword を受け渡している場合も、機能に影響しないので変更する必要はありません。

サンプル レスポンス

JSON
{
"respList": [{
"sessionId": "b8************************d31942",
"accountId": "4028cb************************14",
"subAccounts": null
}],
"error": false,
"errorList": []
}
		

API の実行

全てのレポートデータはGMT時間で戻されます。例: impression の数値の取得。

サンプル リクエスト

curl -v -X POST  
-H "Content-Type:application/json" 
-H "Accept:application/json" 
-H "accountId:14a************************9e"
-H "secretKey: ####" 
-H "sessionId: ###" 
-d  '{"reportRequest":{"metrics":["adImpressions"],"timeFrame":"2017-07-20:2017-07-30","groupBy":["date"], "filterBy":[{ "filterName":"adImpressions", "filterValue": "300" , "comparator":">"}]}}'
https://api.inmobi.com/v3.0/reporting/publisher
		

サンプル レスポンス

{
"error": false,
"respList": [{
"adImpressions": 1786296,
"date": "2017-07-24 00:00:00"
}, {
"adImpressions": 1951438,
"date": "2017-07-25 00:00:00"
}, {
"adImpressions": 8062637,
"date": "2017-07-29 00:00:00"
}, {
"adImpressions": 11151057,
"date": "2017-07-30 00:00:00"
}, {
"adImpressions": 4190525,
"date": "2017-07-21 00:00:00"
}, {
"adImpressions": 10044183,
"date": "2017-07-27 00:00:00"
}, {
"adImpressions": 3881191,
"date": "2017-07-22 00:00:00"
}, {
"adImpressions": 9841295,
"date": "2017-07-20 00:00:00"
}, {
"adImpressions": 4605890,
"date": "2017-07-26 00:00:00"
}, {
"adImpressions": 6175605,
"date": "2017-07-28 00:00:00"
}, {
"adImpressions": 2247567,
"date": "2017-07-23 00:00:00"
}]
}
		

レポートの詳細

以下、レポートで確認できる項目、グルーピング、フィルタリングのパラメータです。

項目

パラメータ 説明
adRequests 広告リクエスト数
adImpressions 広告表示数
clicks クリック数
earnings 平均収益
servedImpressions リクエストに対して戻された広告の数
costPerMille eCPM (1,000 impressions に対して)
fillRate リクエストに対して戻すことのできた広告の割合

グルーピング

パラメータ 説明
country 地域ごとにレポート値をグループ
requestSlot 広告枠(placement)のサイズごとにレポート値をグループ (例 480x320)
platform 端末のOSごとにレポート値をグループ
date 日付ごとにレポート値をグループ
account アカウントごとにレポート値をグループ (アカウントの下に作られたサブアカウント)
inmobiAppId App ID ごとにレポート値をグループ (アプリ配下の全ての広告枠(placement)をまとめる)
placement 広告枠(placement)ごとにレポート値をグループ

フィンルタリング

パラメータ 値の型 説明 コンパレータ
country String 指定した国でフィルタ。 例 “South Korea” =
inmobiAppId Long InMobi アプリ登録時に生成されるApp IDでフィルタ 例 14999472554## =, IN
inmobiAppName Name InMobi アプリ登録時に登録したアプリ名でフィルタ 例 “Horoscoper” =
placementId Long 広告枠(placement Id) でフィルタ 例 1478496451110. =
placementName String 登録した広告枠の名前 (placement name) でフィルタ 例 “Default Interstitial Placement” =
platform String 端末のOSの種類でフィルタ 例 IOS, ANDROID =, IN
earnings Long 収益の合計値でフィルタ 例 100 >, <, =, >=, <=
adImpressions Long 広告表示数 (impressions) でフィルタ 例 100 >, <, =, >=, <=

ページ付け

レポーティングクエリの結果が5,000行を超えるデータセットが戻される場合、ページ付けが必要になります。一つのレポートAPI のコールで戻されるデータセットの上限は5,000行になります。ページ付けは以下のパラメータを使用することで実施できます。

  1. offset (開始位置。一番最初のリクエストでは ‘0’になります)
  2. length (取得する行数、 ※5000未満)

ページ付けをして、複数に分けてデータセットを取得する場合、offset に渡す値は直前のページ付けで設定した合計値(offset + length)です。最後のページで出力される行数は必然的に"length"で指定した数よりも少ないか同等になります。

例: 三行のデータをフェッチ

リクエスト

curl -v -X POST 
-H "Content-Type:application/json" 
-H "Accept:application/json" 
-H "accountId:4028cb************************14" 
-H "secretKey: ####" 
-H "sessionId: ####”
-d  '{"reportRequest":{"metrics":["clicks"],"timeFrame":"2017-07-20:2017-07-30","groupBy":["country"],"offset": 0, "length": 3}}'   
https://api.inmobi.com/v3.0/reporting/publisher
		

レスポンス

{
"error":false,
"respList":[
{"clicks":8,"country":"Finland","countryId":105},
{"clicks":0,"country":"Suriname","countryId":290},
{"clicks":0,"country":"Belarus","countryId":142}
]
}
		

注記:

上記の様なリクエストを実行し、13,000行のレコードが戻ってくる場合、offset と length に 以下の様な値を持たせ3回にわけてレポートをコールする必要があります。

1st call : offset = 0, length = 5000
2nd call : offset = 5000, length = 5000
3rd call : offset = 10000, length = 3000
		

Examples

サンプル 1: アカウントで発生したクリック(clicks)と 収益(earnings)のレポートを取得

リクエスト

curl -v -X POST  
-H "Content-Type:application/json" 
-H "Accept:application/json" 
-H "accountId:14a************************9e"	
-H "secretKey: ####" 
-H "sessionId: ####”
-d  '{"reportRequest":{"metrics":["earnings","clicks"],"timeFrame":"2017-07-20:2017-07-30"}}'
https://api.inmobi.com/v3.0/reporting/publisher
		

レスポンス

{
"error": false,
"respList": [{
"clicks": 3901721,
"earnings": 2076.485
}]
}
		

サンプル 2: アカウントで発生したクリック(clicks)と 収益(earnings)を日別にグループしてレポートを取得

リクエスト

 curl -v -X POST 
 -H "Content-Type:application/json" 
-H "Accept:application/json"
 -H "accountId:4028cb************************14
-H "secretKey: ####" 
-H "sessionId: ####”
-d  '{"reportRequest":{"metrics":["earnings","clicks"],"groupBy":["date"],"timeFrame":"2017-07-20:2017-07-30"}}'  
https://api.inmobi.com/v3.0/reporting/publisher
		

レスポンス

{
"error": false,
"respList": [{
"clicks": 131833,
"date": "2017-07-24 00:00:00",
"earnings": 228.166
}, {
"clicks": 145627,
"date": "2017-07-25 00:00:00",
"earnings": 231.309
}, {
"clicks": 351536,
"date": "2017-07-29 00:00:00",
"earnings": 85.275
}, {
"clicks": 563490,
"date": "2017-07-30 00:00:00",
"earnings": 148.264
}, {
"clicks": 318369,
"date": "2017-07-21 00:00:00",
"earnings": 313.458
}, {
"clicks": 773215,
"date": "2017-07-27 00:00:00",
"earnings": 76.041
}, {
"clicks": 295016,
"date": "2017-07-22 00:00:00",
"earnings": 276.296
}, {
"clicks": 471678,
"date": "2017-07-20 00:00:00",
"earnings": 314.018
}, {
"clicks": 350179,
"date": "2017-07-26 00:00:00",
"earnings": 116.173
}, {
"clicks": 332405,
"date": "2017-07-28 00:00:00",
"earnings": 69.499
}, {
"clicks": 168373,
"date": "2017-07-23 00:00:00",
"earnings": 217.987
}]
}
		

サンプル 3: 指定したアプリID(inmobiAppId)からの広告リクエスト数(adRequests)のレポートを取得

リクエスト

curl -v -X POST  
-H "Content-Type:application/json" 
-H "Accept:application/json" 
-H "accountId:4028cb************************14
-H "secretKey: ####" 
-H "sessionId: ####”
-d  '{"reportRequest":{"metrics":["adRequests"],"timeFrame":"2017-07-20:2017-07-30","filterBy":[{ "filterName":"inmobiAppId", "filterValue": "1489455016170" , "comparator":"="}]}}' 
https://api.inmobi.com/v3.0/reporting/publisher
		

レスポンス

{
"error": false,
"respList": [{
"adRequests": 179623
}]
}
		

サンプル 4: 指定したアプリ名(inmobiAppName)からの収益(earnings)のレポートを取得

リクエスト

curl -v -X POST  
-H "Content-Type:application/json" 
-H "Accept:application/json"
 -H "accountId:4028cb************************14
-H "secretKey: ####" 
-H "sessionId: ####”
-d  '{"reportRequest":{"metrics":["earnings"],"timeFrame":"2017-07-20:2017-07-30", "filterBy":[{ "filterName":"inmobiAppName", "filterValue": "pujia" , "comparator":"="}]}}'   
https://api.inmobi.com/v3.0/reporting/publisher
		

レスポンス

{
"error": false,
"respList": [{
"earnings": 5.282
}]
}
		

サンプル 5: 国別の収益(earnings)のレポートを取得

リクエスト

curl -v -X POST 
-H "Content-Type:application/json" 
-H "Accept:application/json" 
-H "accountId:4028cb************************14
-H "secretKey: ####" 
-H "sessionId: ####”
-d  '{"reportRequest":{"metrics":["earnings"],"timeFrame":"2017-07-20:2017-07-30","groupBy":["country"]}}'   
https://api.inmobi.com/v3.0/reporting/publisher
		

レスポンス

{
"error": false,
"respList": [{
"country": "Republic Of Moldova",
"countryId": 269,
"earnings": 0
}, {
"country": "Macau",
"countryId": 232,
"earnings": 0.002
}, {
"country": "Burma (Myanmar)",
"countryId": 155,
"earnings": 0.005
}, {
"country": "Argentina",
"countryId": 135,
"earnings": 0
}, {
"country": "Philippines",
"countryId": 67,
"earnings": 0
}, {
"country": "Aruba",
"countryId": 137,
"earnings": 0
}, {
"country": "India",
"countryId": 11,
"earnings": 0.003
}, {
"country": "Vietnam",
"countryId": 109,
"earnings": 0
}, {
"country": "China",
"countryId": 164,
"earnings": 2075.454
}, {
"country": "Mozambique",
"countryId": 250,
"earnings": 0
}, {
"country": "Cameroon",
"countryId": 158,
"earnings": 0
}, {
"country": "Canada",
"countryId": 101,
"earnings": 0.004
}, {
"country": "United Kingdom",
"countryId": 46,
"earnings": 0.043
}, {
"country": "East Timor",
"countryId": 177,
"earnings": 0
}, {
"country": "Egypt",
"countryId": 50,
"earnings": 0
}, {
"country": "Mongolia",
"countryId": 246,
"earnings": 0
}, {
"country": "Peru",
"countryId": 265,
"earnings": 0
}, {
"country": "New Zealand",
"countryId": 119,
"earnings": 0
}, {
"country": "Mauritius",
"countryId": 242,
"earnings": 0
}, {
"country": "Hong Kong",
"countryId": 207,
"earnings": 0.007
}, {
"country": "Belarus",
"countryId": 142,
"earnings": 0
}, {
"country": "Antigua And Barbuda",
"countryId": 134,
"earnings": 0
}, {
"country": "Hungary",
"countryId": 120,
"earnings": 0
}, {
"country": "Kazakhstan",
"countryId": 217,
"earnings": 0
}, {
"country": "Greece",
"countryId": 113,
"earnings": 0
}, {
"country": "Iran, Islamic Republic Of",
"countryId": 209,
"earnings": 0
}, {
"country": "Austria",
"countryId": 110,
"earnings": 0
}, {
"country": "Singapore",
"countryId": 74,
"earnings": 0.002
}, {
"country": "Colombia",
"countryId": 165,
"earnings": 0
},
		

エラーコード

エラーコードとエラー内容の説明

エラーコード 説明
1000 レポートで予期せぬエラーが発生しました。
1001 リクエストのオブジェクトが無効です。
1002 リクエストに含まれる offset 値が無効です。
1003 リクエストに含まれる length 値が無効です。
1004 クライアントのリクエストが無効です。クライアントのリクエストが正しく作成されているされていることを確認してください。
2000 アカウントIDがリクエストに含まれていません。リクエストにアカウントIDを含めてください。
2001 フィルターに含まれるアカウントIDが無効、もしくはあなたにアクセス権限の無いアカウントIDです。:[無効なアカウントIDのリスト]
2021 リクエストに無効な項目が含まれています。: [無効な項目のリスト]
2022 リクエストに無効なグループ条件が含まれています。:[無効な groupBysのリスト]
2023 リクエストに無効なフィルタ条件が含まれています。:[無効な filtersのリスト]
2024 フィルタで使用している比較符号が無効です。[無効なフィルタ]比較符号はいづれかのものになります。[有効なフィルタ]
2025 リクエストに無効なフィルタが含まれています(国別フィルタの値)。 [無効な国のリスト]
2027 from-date は to-date の日付より後の日付を指定できません。
2028 リクエストに含まれる日付のフォーマットが無効です。
2029 リクエストに無効なソート条件が含まれています。:[無効な orderBy のリスト] レポートで引いている項目、またはグループで使用している項目のみがソート(orderBy)で使用できます。
2030 ソート(orderBy)で指定している並び順の値が無効です。'asc' または 'desc'を指定してください。
2031 リクエストに含まれているフィルターに値が設定されていません。[無効なフィルターのリスト] 適切なフィルターの値を設定してください。
2032 リクエストに含まれている期間を指定する日時のフォーマットが無効です。正しいフォーマットは start date:end date( yyyy-MM-dd:yyyy-MM-dd)です。
2033 リクエストに含まれるメーカーのフィルタの値が無効です。[無効なメーカーのリスト]
2034 リクエストに含まれるプラットフォームのフィルタの値が無効です。[無効なプラットフォームのリスト]
2035 リクエストに含まれるキャリアのフィルタの値が無効です。[無効なキャリアのリスト]
2036 from-date または to-date に設定する日付はリクエストを実行する日より以前でなければなりません。

FAQs

1. 収益(earnings)に表示される値の通貨単位は何になりますか?

収益(earnings)はUSドルで表記されます。

2. 一つのセッションで実行できるリクエスト数の上限はいくつですか?

一つのセッションで実行できるリクエスト数に上限はありません。

3. 1日のうちで作成できるセッション数の上限はいくつですか?

1日のうちで作成できるセッション数の上限は15です。

4. 障害や遅延が発生した際の復旧までにかかる時間は通常どれくらいですか?

通常、問題が発覚してから24〜48時間で修正対応を完了します。

5. データの遅延期間は通常どのくらいですか?

データ遅延期間は通常、4〜5時間分です。InMobi はGMT時間に従っています。

Reporting API 1.1 からの移行

InMobi publisher reporting API 1.1 からの移行の場合、以下のレポーティング項目は廃止されている点、ご注意ください。

Metrics costPerClick, CTR, servedImpressions
GroupBy site, refTag, manufacturer, carrier
Filters accountId, siteId, siteName, carrier, manufacturer, refTag, requestedSlotId, platformId, clicks, CostPerClick, CTR

Note:

InMobi Publisher Reporting API 1.1 の実装ガイドは こちらから