Ad Quality Raw Data API

Extract impression-level ad quality metrics—like revenue, click rate, ad source, creative ID, and UX patterns—from your Android app via the Ad Quality Raw Data API for BI platform analysis.

Read time 5 minutes

The Ad Quality Raw Data API enables you to pull impression-level data from Ad Quality to use on your internal BI platform.

How to use the API

  • Pulling the Ad Quality raw data is performed by completing the following steps:
  1. Make an API request which returns a URL link to download the report
  2. Download the report by clicking on the provided link
  • Each API call must be made for each individual app and  a single date
  • The data for each date is stored and available for 14 days
    • Example: Data for January 1st will be available until January 14th_
  • Data for any given date will only be available the following day from 08:00 AM UTC. Make sure to only call the API after this time
    • Example: The data for January 1st is only available on January 2nd, after 08:00 AM UTC_
  • Data will continue to be updated for a period of 2 days after they become available. After that, they will not change.
    • Example: The data for January 1st will update on January 2nd and January 3rd. After January 3rd, the data will not change_
  • Date & App Key aren't included in the report as they are unique per report (file)

API request for report URL

A valid API hit returns a link to the requested file.

Authentication Type

Bearer API authentication

Method

GET https://ad-quality.soomla.com/api/rawdata/v1?

Required Parameters 

NameTypeDescription
dateStringYYYY-MM-DD (UTC Timezone)
appKeyStringApplication Key (as seen on our platform)

Request Example URL

request GET 'https://ad-quality.soomla.com/api/rawdata/v1?appKey=c0492d05&date=2022-07-12'
``` 

#### Response Example URL

```js
{
   "urls": [
       "https://ad-quality-raw-data-api.s3.amazonaws.com/production/daily_dumps/2022-07-06/4/appkey%3Dc0492d05/20220707_070020_00066_jht7e_bucket-00000.gz?AWSAccessKeyId=ASIAZF2UTGTCQF2VSIVE&Expires=1657212469&Signature=u%2F2qOWmVw3iC2v21nqRYnOE443s%3D&x-amz-security-token=FwoGZXIvYXdzELv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDJtzCMfRJtv%2B7dCGjyLkAQX4BODoGx%2F92huTOXt86j31N1mrr2UvKuD9Qi5w1Kzu0B%2FfBrXlk4in64Z53Iy%2BOR1A5cGxvu25LObGXreMeCfdLz1S5p4WOM1ldmKgkWxYMvU01obpj3dvUXob4G1Gz13Uf5Go9B7THZlVV6g8Mhduk7zpIqYRmwYDCq4U2WBeN%2BKiJOT6Rf2SRDvpDXQJDW1bl%2FV4UfYFJUz8s%2B1HIVxmeVmrIzJVevD35Wjh4dGHuD0OTRSEL7NsTjzqtTZs7mUIWjqV2aJh8l8Rz%2BwG3d%2FGtgblKJ%2Fi3wE5X0xJjkQNJgm6WCiW1pqWBjIyuheodw%2FxNLedYFcSY7wuJa6iKhxdZQwumUZgp1TS0j2kfu8eSPe6D0jvsGhlpk4zYms%3D"
   ],
   "expiration": "2022-07-07 18:47:49"
}

Fields Definition

This table displays the fields that will show in the reports after you pull the Ad Quality raw data. For each you can see a description and an example of what it will contain. 

Select the URL that was pulled by using the preceding steps to download the report.

FieldDescriptionExample
event_timestampBigint1657500000000
user_idString1834b456-b9ea-4811-a121-9afc165c1eb0
ad_unitStringInterstitial
ad_sourceThe Network name that serves the adGoogle AdMob
dspThe dsp name in case there isTheTradeDesk
instance_namethe network instance nameDefaultRewarded
CountryUS
us_statestate code which impression happenedOR
device_modelStringSM-A127M
os_versionString18.3.1
sdk_versionString5.17.0
app_versionString2.8.9
advertiseradvertiser nameProject Makeover
advertiser_idStringcom.bgg.jump
advertiser_typeA field representing advertiser types displayed in the game, including iOS store id, Android package name, brand, and morepackage_name
clickAn integer where 1 indicates a click occurred, and 0 signifies no click1
click_typeString, Did we see a UX pattern that relates to this Ad Quality glossary (qClick, proximity_click, auto_click, early_click,hasty_click, other)auto_click,proximity_click
click_tsBigint, client timestamp in UTC1657450000000
video_completedRelevant for video creative types, an integer where 1 indicates the video was completed, and 0 indicates it was not.1
video_completed_tsBigint1657450000000
revenueThe Revenue generated by the user (USD). 0.5
categoryapp category of the advertiser from the app store or google playCasual
content_ratingThe rate on the US Apple/google app store
{"US":"Everyone"}
creative_typeThe main creative type: playable / video/ imageplayable
creative_idString, Ad quality creative id6c3d78bfe7c74d805c01b13b44e6e1ecff16544c
appstore_url (current field name is ‘url')String
video_urlsArray of String
end_card_urlsArray of String
icon_urlsString
image_urlsArray of String
https://i.ytimg.com/vi/Pv8H5ceSeF0/hqdefault.jpg
imp_numImpression number in the sequence of a user. For banners and native the value is '-1'3
ad_closedAn integer where 1 indicates an ad closed event received, and 0 signifies no ad closed0
ad_closed_tsBigint1657450000000
developerString, the developer of the advertiser who had an impressionSupersonic
ad_source_sdk_versionString5.17.0