The Marketing Reporting API provides access to aggregate and granular app related data. Reports can be confined to any specific date range. Please note that all the timestamps should be represented in Coordinated Universal Time (UTC).
Important Endpoints listed below are all relative to the base url https://marketing-api.upsight.com/v2/report/
.
Unless otherwise documented, all Reporting API requests support the following query parameters (optional):
Param | Type | Default | Optional | Description |
---|---|---|---|---|
auth | string | none | no |
Auth token acquired after a successful :ref: login <login-code> |
startts | timestamp | endts - (36 * granularity) | yes | The low end of reporting date range |
endts | timestamp | startts - (36 * granularity) | yes | The high end of the reporting date range |
range | int | 36 | yes | The number of data points to return |
granularity | string | "day" | yes |
The increment between each data point. Valid values: "hour" , "day" |
Note By default, endts
is set to now
(current hour or day, depending on granularity
) and startts
to 36 days/hours in the past.
range
may be combined with either startts
or endts
.
If both are used, range
is ignored.
If you want reporting data for the time window 1/1/2011 to 1/11/2011, set the following values:
endts = 1320130800
(timestamp for 1/11/2011),range = 10
, andgranularity = day
Type | Descriptions |
---|---|
impressions | Number of times the content unit is displayed |
actionrate | Rate by which impressions are acted upon |
actions | Number of times an impression resulted in an action (e.g. clicked) |
conversionrate | Rate by which actions result in a conversion |
conversions | Number of times an action has resulted in a conversion |
ecpm | Effective cost per thousand impressions |
revenue | Net Revenue generated by the content unit |
value | Net Value generated by the content unit |
Type | Descriptions |
---|---|
impressions | Number of times the campaign was displayed |
clickrate | Rate by which impressions are clicked (clicks/impressions) |
clicks | Number of times an impression lead to a click |
conversionrate | Rate by which clicks lead to a conversion |
conversions | Number of times a click lead to a conversion |
ecpm | Effective cost per thousand impressions |
spend | Total dollar amount spent on campaign |
value | Total net value of a campaign (such as VGP) |
Type | Descriptions |
---|---|
users | Number of users |
sessions | Number of times the game was started |
revenue | Net Amount of revenue a game generated |
spend | Amount spent in advertising |
value | Amount of value a game generated (Promotional, such as VGP) |
iap_value | Net Amount of in-app purchases a game generated |
Type | Descriptions |
---|---|
users | Number of users |
sessions | Number of times the game was started |
revenue | Amount of revenue generated |
spend | Amount spent in advertising |
value | Amount of value a game generated (Promotional, such as VGP) |
iap_value | Net Amount of in-app purchases a game generated |
All request to the reporting API require an auth token. The following example illustrates how to acquire a new token. Please substitute email and password with your Dashboard login credentials.
# python
import requests
import json
company_name = 'My Company Name Inc.'
contact_fname = 'First Name'
contact_lname = 'Last Name'
company_email = '<email>'
mypassword = '<password>'
marketing_api = 'https://marketing-api.upsight.com/v2'
marketing_api_user = marketing_api + '/account/user'
marketing_api_auth = marketing_api + '/account/auth'
marketing_api_game = marketing_api + '/account/game'
marketing_api_device = marketing_api + '/account/device'
marketing_api_content_game = marketing_api + '/content/game'
r = requests.post(marketing_api_auth,
{'email': company_email,
'password': mypassword})
if r.status_code <= 201:
jsresp = json.loads(r.content)
idtoken = jsresp['response']['identity_token']
print('Logged in account, using token %s' % (idtoken))
else:
print('Account login request failed with error code %d, %s'
% (r.status_code, r.content))
Returns aggregate metrics for the specified content unit.
/report/game/<game_id:int>/content/<content_id:int>/report
Parameter | Type | Description |
---|---|---|
game_id | int | The Game ID this content unit is associated with. |
content_id | int | The Content ID the report is associated with. |
auth | Authentication token (authentication header may be used instead). Required |
GET /report/game/2012/content/2225/report?startts=1320883200&endts=1323993600
{
"errobj": null,
"response": {
"conversions": 14044,
"revenue": 11149.72,
"value": 5598.50,
"startts": 1320883200,
"actions": 96599,
"conversionrate": 14.54,
"actionrate": 5.87,
"endts": 1323993600,
"impressions": 1646949,
"ecpm": 6.77
},
"error": null
}
Returns aggregated data for multiple content units for a span of time
/report/game/<game_id:int>/content/aggregate/report
Parameter | Type | Description |
---|---|---|
game_id | int | The Game ID this content unit is associated with. |
content_id | int | The Content ID the report is associated with. |
auth | Authentication token (authentication header may be used instead). Required |
GET /report/game/1/content/aggregate/report?content=1,2,3&startts=1330560000&endts=1331164800
{
"errobj": null,
"response": {
"conversions": 1578,
"value": 0,
"revenue": 609.79,
"startts": 1330560000,
"actions": 10980,
"conversionrate": 14.37,
"actionrate": 13.16,
"endts": 1331164800,
"impressions": 83466,
"ecpm": 7.31
},
"error": null
}
Returns meta data and a list of data points for the specified report type.
Each data point is returned as a (timestamp, value) pair.
Data points are spaced out according to the granularity
parameter (set to 'day'
by default).
The API will not perform interpolation to fill gaps in reporting with intermediate data points.
/report/game/<game_id:int>/content/<content_id:int>/report/<report_type:str>
Parameter | Type | Description |
---|---|---|
game_id | int | The Game ID this content unit is associated with. |
content_id | int | The Content ID the report is associated with. |
report_type | string | See the Detailed Content Report Types table. |
auth | Authentication token (authentication header may be used instead). Required |
GET /report/game/2102/content/1000107/report/ecpm
{
"errobj": null,
"response": {
"startts": 1320969600,
"endts": 1324080000,
"report": "ecpm",
"game_id": [2102],
"content_id": [1000107]
"datapoints": [
[
1322092800,
6.96
],
[
1322179200,
8.54
],
[
1322265600,
10.30
],
...
},
"error": null
}
Returns meta data and a list of data points for a given report type over a span of time across multiple content units. Each data point is represented by a time stamp and a value. Each point is spaced out according to granularity (day by default). This currently does not fill in the blanks if there is no data to return for the next point in the sequence.
/report/game/<game_id:int>/content/aggregate/report/<report_type:str>
Parameter | Type | Description |
---|---|---|
game_id | int | The Game ID the report is associated with. |
content_id | int |
A list of comma separate content_id values to report against.
|
report_type | string | See the Detailed Content Report Types table. |
auth | Authentication token (authentication header may be used instead). Required |
GET /report/game/1/content/aggregate/report/conversions?startts=1330560000&endts=1331164800&content=1,2,3
{
"errobj": null,
"response": {
"startts": 1330560000,
"endts": 1331164800,
"datapoints": [
[
1330560000,
544
],
[
1330646400,
469
],
],
"report": "conversions",
"game_id": [
1
],
"content_id": [
1,
2,
3
]
},
"error": null
}
Returns aggregate data for one campaign.
/report/game/<game_id:int>/campaign/<campaign_id:int>/report
Parameter | Type | Description |
---|---|---|
game_id | int | The Game ID that this content unit is associated with. |
campaign_id | int | The Campaign Id the report is associated with. |
auth | Authentication token (authentication header may be used instead). Required |
GET /report/game/2012/campaign/2225/report?startts=1320883200&endts=1323993600
{
"errobj": null,
"response": {
"conversions": 14044,
"spend": 11149.72,
"value": 19403.33,
"startts": 1320883200,
"actions": 96599,
"conversionrate": 14.54,
"actionrate": 5.87,
"endts": 1323993600,
"impressions": 1646949,
"ecpm": 6.77
},
"error": null
}
Returns meta data and a list of data points for the specified report type.
Each data point is returned as a (timestamp, value) pair.
Data points are spaced out according to the granularity
parameter (set to 'day' by default).
The API will not perform interpolation to fill gaps in reporting with intermediate data points.
/report/game/<game_id:int>/campaign/<campaign_id:int>/report/<report_type:str>
Parameter | Type | Description |
---|---|---|
game_id | int | The Game ID that this campaign unit is associated with. |
campaign_id | int | The Campaign ID the report is associated with. |
report_type | string | See the Detailed Campaign Report Types table |
auth | Authentication token (authentication header may be used instead). Required |
GET /report/game/1793/campaign/2559/report/impressions?startts=1320883200&endts=1323993600
{
"errobj": null,
"response": {
"report": "impressions",
"game_ids": [
1793
],
"startts": 1320883200,
"campaign_ids": [
2559
],
"endts": 1323993600,
"datapoints": [
[
1322092800,
31132
],
[
1322179200,
26934
],
[
1322265600,
29146
],
...
],
},
"error": null
}
Returns a list of conversions, specified by UDID, click timestamp, conversion timestamp, and campaign id.
By default, it returns data for today.
To retrieve the conversion data for a different date, either use the startts
and endts
parameters defined :ref: above <common-query-params>
, or set the date
parameter to the timestamp of the desired reporting day.
/report/game/<game_id:int>/udid
Parameter | Type | Description |
---|---|---|
game_id | int | The Game ID that the report is associated with. |
date | int (epoch format datestamp) | Sets the conversion date to generate the list by. Optional. |
auth | Authentication token (authentication header may be used instead). Required |
GET /report/game/2012/udid?date=1324321675
{
"errobj": null,
"response": {
"conversions": [
[
"0377a1764751a3cd09ec3f2ed14d872c80aff838",
1324270579,
1324274582,
2315
],
[
"04a6700f7acfc305d91d673e2d51e1b6601c41ef",
1324233439,
1324282368,
2315
],
[
"050b161dd31758563259fa402cfeaab1757dc5b4",
1324229614,
1324307724,
2315
],
...
},
"error": null
}
Returns meta data at the account level.
/report/report
Parameter | Type | Description |
---|---|---|
auth | Authentication token (authentication header may be used instead). Required |
GET /report/report?startts=1320883200&endts=1323993600
{
"errobj": null,
"response": {
"users": 78864,
"revenue": 50.53,
"sessions": 96107,
"startts": 1320883200,
"endts": 1323993600,
"spend": 20905.5,
"value": 59033.25,
"iap_value": 3500.30
},
"error": null
}
Returns meta data and a list of data points for the specified report type.
Each data point is returned as a (timestamp, value) pair.
Data points are spaced out according to the granularity
parameter (set to 'day' by default).
The API will not perform interpolation to fill gaps in reporting with intermediate data points.
/report/report/<report_type:str>
Parameter | Type | Description |
---|---|---|
report_type | string | See the Detailed Account Report Types table. |
auth | Authentication token (authentication header may be used instead). Required |
GET /report/report/spend?startts=1320883200&endts=1323993600
{
"errobj": null,
"response": {
"report": "spend",
"startts": 1320883200,
"endts": 1323993600,
"datapoints": [
[
1322092800,
5.25
],
[
1322179200,
0.00
],
[
1322265600,
0.00
],
...
],
},
"error": null
}
Aggregation reports allow you to retrieve data across multiple content units, and even across multiple games, filtered by either content_unit_type
, or content_category
.
Possible values for content_category
: promotion
, monetization
Across all matching content units for the specified game.
Filters content units by content unit type or content category. Aggregates results across all matching content units.
Filtered by content category (use case: game overview page charts)::
GET /report/game/<game-id:int>/contentcategory/<content_category:str>/report
GET /report/game/<game_id:int>/contentcategory/<content_category:str>/report/<report_type:str>
Filtered by content type (use case: list view of a single content unit type)::
GET /report/game/<game_id:int>/contenttype/<content_type:str>/report
GET /report/game/<game_id:int>/contenttype/<content_type:str>/report/<report_type:str>
Filter across multiple games
Across all matching content units, irrespective of Game ID.
This finds the list of games based on the provided auth token (i.e. all games for a user), then retrieves all content units for those games based on content category or content unit type, and aggregates results across those content units.
Filtered by content category (use case: publisher overview page).
GET /report/contentcategory/<content_category:str>/report
GET /report/contentcategory/<content_category:str>/report/<report_type:str>
Filtered by content type::
GET /report/contenttype/<content_type:str>/report
GET /report/contenttype/<content_type:str>/report/<report_type:str>
Retrieve user data across all games owned by a publisher:
GET /report/data_collection
Retrieve user data for a single game, across all content units:
GET /report/game/<game_id:int>/data_collection
Retrieve user data for a single content unit:
GET /report/game/<game_id:int>/content/<content_id:int>/data_collection
See :ref:common-query-params
for the parameters that these 3 methods share in common with the rest of the Reporting API.
These methods also support one additional parameter:
Parameter | Format | Description |
---|---|---|
query | csv , json |
Valid format options are csv , and json .
Defaults to csv .
Optional.
See details on each format below.
|
Timestamp,Game Name,Game ID,Content Unit Name,Content Unit ID,Name,Email Address,Phone Number,Age,Gender,Zip Code,Reward Item(s),Connection Type,Platform,Hardware,OS,IP-Based Geolocation,Placement
2/1/2012 12:00:00 AM,Blood & Glory,1234,Email Newsletter Promo A,9999,John Doe,johnnyj@playhaven.com,5555555555,25,male,N/A,WiFi,iOS,iPhone4,iOS 5.0,USA,game_launch
...
[
["Timestamp",
"Game Name",
"Game ID",
"Content Unit Name",
"Content Unit ID",
"Name",
"Email Address",
"Phone Number",
"Age",
"Gender",
"Zip Code",
"Reward Item(s)",
"Connection Type",
"Platform",
"Hardware",
"OS",
"IP-Based Geolocation",
"Placement"],
["2/1/2012 12:00:00 AM",
"Blood & Glory",
1234,
"Email Newsletter Promo A",
9999,
"John Doe",
"johnnyj@playhaven.com",
5555555555,
25,
"male",
94103,
null,
"WiFi",
"iOS",
"iPhone4",
"iOS 5.0",
"USA",
"game_launch"],
...
]
Returns the latest generated reports.
Note Where possible, this API conforms to the standard JSON/JSONP over HTTP API conventions.
/accountreports?<auth:str>&<report_type:str>
Parameter | Type | Description |
---|---|---|
type | string | Comma delimited string, used to grab specific reports. If not used than all reports are returned. |
auth | Authentication token (authentication header may be used instead). Required |
GET /accountreport?auth=3faba1eabb53404794bc973cb9269a20&type=publisher
{
'errobj': None,
'error': None,
'response': [
{
'title': 'PlayHaven Pub Report',
'url' : "https://playhaven-reports.s3.amazonaws.com/advertiser_report_2012-09-18-PlayHaven.xlsx?Signature=R3GnZGytWvLhfZvSywUtYBNCDks%3D&Expires=1348570805&AWSAccessKeyId=AKIAI2PDNMF554M3LEOA",
'report_type' : 'publisher',
'created_on': 1325379600,
'expires_on': 1325984400,
'user_id' : 1
}
]
}
GET /accountreport?auth=3faba1eabb53404794bc973cb9269a20
{
'errobj': None,
'error': None,
'response': [
{
'title': 'PlayHaven Ad Report',
'url' : "https://playhaven-reports.s3.amazonaws.com/advertiser_report_2012-09-18-PlayHaven.xlsx?Signature=R3GnZGytWvLhfZvSywUtYBNCDks%3D&Expires=1348570805&AWSAccessKeyId=AKIAI2PDNMF554M3LEOA",
'report_type' : 'advertiser',
'created_on': 1325379600,
'expires_on': 1325984400,
'user_id' : 1
},
{
'title': 'PlayHaven Pub Report',
'url' : "https://playhaven-reports.s3.amazonaws.com/advertiser_report_2012-09-18-PlayHaven.xlsx?Signature=R3GnZGytWvLhfZvSywUtYBNCDks%3D&Expires=1348570805&AWSAccessKeyId=AKIAI2PDNMF554M3LEOA",
'report_type' : 'publisher',
'created_on': 1325379600,
'expires_on': 1325984400,
'user_id' : 1
}
]
}
GET /accountreport?auth=3faba1eabb53404794bc973cb9269a20&type=publisher,advertiser
{
'errobj': None,
'error': None,
'response': [
{
'title': 'PlayHaven Ad Report',
'url' : "https://playhaven-reports.s3.amazonaws.com/advertiser_report_2012-09-18-PlayHaven.xlsx?Signature=R3GnZGytWvLhfZvSywUtYBNCDks%3D&Expires=1348570805&AWSAccessKeyId=AKIAI2PDNMF554M3LEOA",
'report_type' : 'advertiser',
'created_on': 1325379600,
'expires_on': 1325984400,
'user_id' : 1
},
{
'title': 'PlayHaven Pub Report',
'url' : "https://playhaven-reports.s3.amazonaws.com/advertiser_report_2012-09-18-PlayHaven.xlsx?Signature=R3GnZGytWvLhfZvSywUtYBNCDks%3D&Expires=1348570805&AWSAccessKeyId=AKIAI2PDNMF554M3LEOA",
'report_type' : 'publisher',
'created_on': 1325379600,
'expires_on': 1325984400,
'user_id' : 1
}
]
}