Documentation

Support

Unity LevelPlay

Get started with LevelPlay

SDK integration

LevelPlay platform

Unity LevelPlay

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 3 minutesLast updated 2 months ago
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 

Name

Type

Description

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.

Field

Description

Example

event_timestamp
Bigint
1657500000000
user_id
String
1834b456-b9ea-4811-a121-9afc165c1eb0
ad_unit
String
Interstitial
ad_source
The Network name that serves the ad
Google AdMob
dsp
The dsp name in case there is
TheTradeDesk
instance_name
the network instance name
DefaultRewarded
country
2 letter country code, as per ISO 3166-1 Alpha-2.
US
us_state
state code which impression happened
OR
device_model
String
SM-A127M
os_version
String
18.3.1
sdk_version
String
5.17.0
app_version
String
2.8.9
advertiser
advertiser name
Project Makeover
advertiser_id
String
com.bgg.jump
advertiser_type
A field representing advertiser types displayed in the game, including iOS store id, Android package name, brand, and more
package_name
click
An integer where 1 indicates a click occurred, and 0 signifies no click
1
click_type
String, 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_ts
Bigint, client timestamp in UTC
1657450000000
video_completed
Relevant for video creative types, an integer where 1 indicates the video was completed, and 0 indicates it was not.
1
video_completed_ts
Bigint
1657450000000
revenue
The Revenue generated by the user (USD).
0.5
category
app category of the advertiser from the app store or google play
Casual
content_rating
The rate on the US Apple/google app store
{"US":"Everyone"}
creative_typeThe main creative type: playable / video/ image
playable
creative_id
String, Ad quality creative id
6c3d78bfe7c74d805c01b13b44e6e1ecff16544c
appstore_url
(current field name is 
url
)		String
https://www.ubereats.com/?utm_campaign=CM2176745-display-doubleclick_42_-99_CR-National_e_all_bra_cpm_es_Eater%7CCR%7CEatsDemandIIYTBumper-L2R0ED22-PO481364&utm_medium=display-programmatic&utm_source=dbm
video_urls
Array of String
https://www.youtube.com/watch?v=rdahaLbmxOw
end_card_urlsArray of String
https://v.ssacdn.com/demand-creatives/assets/videos/m29ateosecjmkxt2xamf.mp4
icon_urls
String
https://lh3.googleusercontent.com/y3iFaRQsuLPIiWnCX_Yg7j2IGWiKtnFFbsQPBwRWxIFszsV_xnZYE5VT7d1udxRqQSCPxn_cyw=w256-h256
image_urls
Array of String
https://i.ytimg.com/vi/Pv8H5ceSeF0/hqdefault.jpg
imp_num
Impression number in the sequence of a user. For banners and native the value is 
-1
3
ad_closed
An integer where 
1
indicates an ad closed event received, and 
0
signifies no ad closed
0
ad_closed_ts
Bigint
1657450000000
developer
String, the developer of the advertiser who had an impression
Supersonic
ad_source_sdk_version
String
5.17.0