見出し画像

DAR APIでデジタル広告のリーチ計測を「人」ベースに行う

Dentsu Digital Tech Blog

こんにちは！電通デジタルのBI担当です。

今回は、技術記事でありつつも実験的に少し柔らかめな文体でお送りします。専門知識がなくても伝わるように書いていきます。応援よろしくお願いします。

画像1

応援よろしくお願いします

はじめに

今回は「DAR（ディーエーアール）」というサービスの一部のAPIについて説明します。このAPIですが、（広告業界も狭いため）ネット上に参考情報や日本語記事がなかなか存在しません。

APIから取得できるデータが更新されるタイミングなど、いくつかつまづきポイントもあるため、Tech blogという形で残せればと思い今回記事を書きました。

DARとは

デジタル広告の出稿や計測を担当されている方なら一度は聞いたことがある名前だと思いますが…DARという名前はご存知でしょうか？

知らないという方のために説明すると、DARは「Digital Ad Ratings」の略で、Nielsen社が提供するサービスの名称です。「デジタル広告視聴率を測る」というサービスで、広告が「何回見られたか」ではなく「何人に見られたか」という人を単位にしたリーチ計測を可能にします。

画像5


DAR公式サイト https://www.netratings.co.jp/solution/DigitalAdRatings.html

広告出稿時にDARの「計測タグ」を入れたり、広告出稿前に管理画面から広告キャンペーンを登録したりする必要がありますが、非常に有用なサービスであり、弊社でも多くのクライアント様に利用してもらっています。

ここからは、DAR計測タグを入れた後、具体的にAPIで取得できるデータの内容を紹介します。

DAR APIの一部紹介

DARには非常に多くのAPIが用意されていますが…今回は主要なAPIを4つ紹介しますね。

※以降のリクエストに関しては、変数部分（${YOUR_SECRET_KEY} など）は適宜読み替えてください。レスポンスに関しては、マニュアルに掲載されているものを一部説明のため編集したもので、データの内容は実際のものではありません。

まずは…TOKENの取得方法

誰のデータを取得するのかというのを判別するために、API用の認証情報を作成する必要があります。ユーザーID、パスワード、シークレットキーを元に、アクセストークンを取得できます。

curl \
   -H 'application/x-www-form-urlencoded' \
   -H "Authorization: Basic ${YOUR_SECRET_KEY}" \
   -d grant_type=password \
   -d username=${YOUR_USERNAME} \
   -d password=${YOUR_PASSWORD} \
https://api.developer.nielsen.com/watch/oauth/token
# アクセストークン
# ※DARのマニュアルに載っている仮のトークンです

{
    "token_type": "BearerToken",
    "expires_in": "239999",
    "refresh_token": "L8GTAAPQ0NOOrgtvgW2gNFdDfYG9wGHs",
    "access_token": "H6A0dqAtNFH81xj30PbdCCCjwiRH"
}

それでは、ここからAPIをご紹介します。

①Campaign Reference API

このAPIでは、DARに登録されている全ての「広告キャンペーン」を確認することができます。例えば春の広告キャンペーン、新商品発売キャンペーンなど、広告は必ず特定の「キャンペーン」に属します。

この後、広告の数値データを取得するために「campaignId」が必要になるため、まずこのAPIを呼び出し、キャンペーンIDをゲットしましょう。

curl \
   -H "Content-Type:application/json" \
   -H "Accept:application/json" \
   -H "Authorization: Bearer ${TOKEN}" \
   -d '{ \
         "countryCode": "JP", \
         "date":"07/27/2020" \
       }' \
https://api.developer.nielsen.com/watch/dar/campaignratings/v3/CampaignReference

日付は「MM/DD/YYYY」形式で指定することに注意。指定した日付以前にスタートしたキャンペーンのデータが一覧で返ってきます。

# ①キャンペーンデータ（サンプルデータ）
# 事前に登録した情報がきちんと反映されているか確認しましょう。
#「JAPAN MOTOR」という会社の、夏と春の広告キャンペーンが登録されているようですね。

[
 {
   "campaignId": 602276381,
   "parentCampaignId": 602276381,
   "campaignName": "JP-JAPAN_MOTOR-CAR1-Summer-dentsudigital",
   "advertiserId": "963435",
   "advertiserName": "JAPAN MOTOR",
   "brandId": "bnd151932000",
   "brandName": "CAR1",
   "campaignStartDate": "07/11/2020",
   "campaignEndDate": "08/10/2020",
   "mediaType": "OCR",
   "targetDemo": "B",
   "targetStartAge": 20,
   "targetEndAge": 999,
   "adReferenceCampaignId": "cmp1156230",
   "countryCode": "JP",
   "viewabilityEnabled": "N",
   "viewabilityProviderName": ""
 },
 {
   "campaignId": 602276382,
   "parentCampaignId": 602276382,
   "campaignName": "JP-JAPAN_MOTOR-CAR1-Spring-dentsudigital",
   "advertiserId": "963435",
   "advertiserName": "JAPAN MOTOR",
   "brandId": "bnd362711000",
   "brandName": "CAR1",
   "campaignStartDate": "04/01/2020",
   "campaignEndDate": "05/10/2020",
   "mediaType": "OCR",
   "targetDemo": "B",
   "targetStartAge": 20,
   "targetEndAge": 999,
   "adReferenceCampaignId": "cmp1156230",
   "countryCode": "JP",
   "viewabilityEnabled": "N",
   "viewabilityProviderName": ""
 },
 //…
]

名前、広告主、開始日・終了日など、「キャンペーン」の各情報がレスポンスに含まれます。

②Campaign Site Reference API

各キャンペーンで、どのような媒体のどのような枠に出稿しているかを確認することができます。「campaignId」1つにつき、複数の広告媒体（siteId）、複数の広告枠（placementId）が紐付きます。

curl \
   -H "Content-Type:application/json" \
   -H "Accept:application/json" \
   -H "Authorization: Bearer ${TOKEN}" \
   -d '{ \
         "countryCode": "JP", \
         "campaignId":"${campaignId}" \
       }' \ 
https://api.developer.nielsen.com/watch/dar/campaignratings/v3/CampaignSiteReference
# ②媒体✕枠のサンプルデータ
# 事前に登録した情報がきちんと反映されているか確認しましょう。
# キャンペーン「602276381」は、YoutubeとTwitterを使ったキャンペーンのようですね。

[
 {
   "campaignId": 602276381,
   "siteId": 1690781,
   "siteName": "YouTube Homepage",
   "siteURL": "www.youtube.com",
   "adNetworkFlag": "T",
   "placementId": 613028104,
   "tagPlacementId": "457164",
   "placementName": "youtube-bumper-20200711-20200810",
   "countryCode": "JP",
   "placementStatus": "Completed"
 },
 {
   "campaignId": 602276381,
   "siteId": 1690782,
   "siteName": "Twitter.com",
   "siteURL": "www.twitter.com",
   "adNetworkFlag": "T",
   "placementId": 613028105,
   "tagPlacementId": "457165",
   "placementName": "twitter-promotweet-20200711-20200810",
   "countryCode": "JP",
   "placementStatus": "Completed"
 }
 //…
]

各キャンペーンで使用する媒体（Site）や枠（Placement）の情報が掲載されていることがわかると思います。

③Campaign Exposure By Placement API

いよいよ来ました。この③が、「人ベース」での数値を取得するためのAPIです。枠ごとのリーチ（UU）、impを確認することができます。

curl \
   -H "Content-Type:application/json" \
   -H "Accept:application/json" \
   -H "Authorization: Bearer ${TOKEN}" \
   -d '{ \
         "countryCode": "JP", \
         "date":"07/25/2020", \       // データを取得したい日付（MM/DD/YYYY）
         "campaignId":"602276381", \  // データを取得したいキャンペーン
         "platformId":"7", \          // 7:計測対象デバイス「PC+mobile」
         "audienceQualifierId":"0" \  // 0:不正なimpressionsを除いたデータ
       }' \
https://api.developer.nielsen.com/watch/dar/campaignratings/v7/CampaignPlacementExposure 
# ③特定の日付✕属性✕媒体✕枠
# リーチ（UU）、impを確認できます。

[
 {
   "campaignDataDate": "07/25/2020",
   "campaignId": 602276381,
   "platformId": 7,
   "countryCode": "JP",
   "demoGroupId": "",
   "demoId": 30000,                 //「30000」は全性年代
   "placementId": 613028104,        //枠のID。詳細は②と組み合わせて確認する
   "tagPlacementId": "japan-youtube-00001",
   "siteId": 1690781,               //媒体のID。詳細は②と組み合わせて確認する
   "reportingFrequencyType": "D",
   "audienceQualifierId": 0,
   "reach": "241245",               //「人数」の情報はここ！キャンペーン開始日からの累積数値
   "impressions": "356299",
   "universeEstimate": "124329000", //日本全体の推定人数。リーチ率を簡単に計算できます。
   ...
 },
...
]

日付、属性、枠の情報とともにリーチやインプレッションの数が掲載されていることを確認ください。上で掲載したのは1データのみですが、実際には枠や属性ごとの多くのデータが返ってきます。

また、リーチやimpressionsの数値は、「キャンペーン開始日」からの累積であることに注意してください。特定日付のimpや新規のリーチ人数を取得したい場合は、当日の数値を前日の数値で引く必要があります。

さらに、リーチやimpressionsの数値は、ボットに対するフィルタリングなどの処理で調整が入る場合があります。ある日の数値がその前日の数値よりも少なくなる場合があるので、累積が前日より減少していても驚かないようにしましょう。

④Campaign Demographic Reference API

先程のAPIで、「demoId」という項目が返ってきたことに気づかれたでしょうか。DARでは、reachやimpressionsというデータを、属性別に取得できます。このAPIでは、DemoIDの番号がどのような属性を指すかを取得することができます。

curl \
   -H "Content-Type:application/json" \
   -H "Accept:application/json" \
   -H "Authorization: Bearer ${TOKEN}" \
   -d '{"countryCode": "JP" }' \
https://api.developer.nielsen.com/watch/dar/campaignratings/v1/DemographicReference 
[
　...
 {
   "demoId": 2004,
   "demoGroupGender": "MALE 21-24",
   "demoGroupAlphaCode": "M",
   "demoGroupStartAge": 21,
   "demoGroupEndAge": 24
 },
  {
   "demoId": 1999,
   "demoGroupGender": "FEMALE",
   "demoGroupAlphaCode": "F",
   "demoGroupStartAge": 2,
   "demoGroupEndAge": 999
 },
  {
   "demoId": 1999,
   "demoGroupGender": "FEMALE",
   "demoGroupAlphaCode": "F",
   "demoGroupStartAge": 13,
   "demoGroupEndAge": 999
 },
 {
   "demoId": 2999, 
   "demoGroupGender": "MALE",
   "demoGroupAlphaCode": "M",
   "demoGroupStartAge": 2,
   "demoGroupEndAge": 999
 },
 {
   "demoId": 2999,
   "demoGroupGender": "MALE",
   "demoGroupAlphaCode": "M",
   "demoGroupStartAge": 13,
   "demoGroupEndAge": 999
 },
 {
   "demoId": 30000,
   "demoGroupGender": "ALL",
   "demoGroupAlphaCode": "B",
   "demoGroupStartAge": 2,
   "demoGroupEndAge": 999
 },
 ...
]

demoId「1999」と「2999」について、複数のデータが返ってきていますが、よく見ると「demoGroupStartAge」が異なることがわかると思います。現状のDARでは、12歳以下のデータは取得されない事になっているため、「demoGroupStartAge」が「13」になっている方を使用するようにしてください。

おまけ：DAR APIを使用する際のポイント

画像3

APIエラーが出る場合

マニュアルにも記載がありますが、DAR APIからデータを取得する際、HTTP 500 Internal Server Errorが返ってくることがあります。

システムからAPIを呼び出す場合は、リトライ処理を忘れないようにしてください。マニュアルでは、「2秒間隔で最大3回までリトライする」ことが推奨されています。

日本時間何時にデータが更新されるか

DARのマニュアルは英語のみで、現状日本語の情報が少ないです。特に日本時間でデータが更新されるタイミングは知らないとどうしようもないので、下記に便利な表を載せておきます。

スクリーンショット 2020-07-25 4.52.32

↑DARの技術サポート様より頂いたありがたい表（一部編集）

USでは毎年3月の第2日曜日から「夏時間」となり、11月の第1日曜日の翌日から「冬時間」となります。

障害などの影響で上記時間にリリースされない場合もあるため、実際にデータが更新されたかどうかの確認は「Campaign Data Availability API」という専用のAPIで確認するようにしてください。

おわりに

DARでどのようなデータを取得できるか、伝わりましたでしょうか。非常に細かくデータを確認できる、人を基準とするリーチ計測に有益なツールであることが伝わっていれば嬉しいです。

今後もデジタル広告業界の技術関連記事をどんどん投稿してまいりますので、ぜひ応援・スキ（ハート）をよろしくお願いします！


みんなにも読んでほしいですか？

オススメした記事はフォロワーのタイムラインに表示されます！