Upsight logo Back to top

Marketing Reporting API

Overview

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.

Example

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, and
  • granularity = day

Detailed Content Report Types

TypeDescriptions
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

Detailed Campaign Report Types

TypeDescriptions
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)

Detailed Game Report Types

TypeDescriptions
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

Detailed Account Report Types

TypeDescriptions
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

Auth Token

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))

Content Unit Reports

Content Unit Report

Description

Returns aggregate metrics for the specified content unit.

HTTP:GET 

/report/game/<game_id:int>/content/<content_id:int>/report

Parameters

ParameterTypeDescription
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

Example Request 

GET /report/game/2012/content/2225/report?startts=1320883200&endts=1323993600

Example Response 

{
    "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
}

Content Unit Reports

Aggregate Content Unit Report

Description

Returns aggregated data for multiple content units for a span of time

HTTP:GET 

/report/game/<game_id:int>/content/aggregate/report

Parameters

ParameterTypeDescription
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

Example Request 

GET /report/game/1/content/aggregate/report?content=1,2,3&startts=1330560000&endts=1331164800

Example Response 

{
    "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
}

Content Unit Reports

Detailed Content Unit Report

Description

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.

HTTP:GET 

/report/game/<game_id:int>/content/<content_id:int>/report/<report_type:str>

Parameters

ParameterTypeDescription
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

Example Request 

GET /report/game/2102/content/1000107/report/ecpm

Example Response 

{
    "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
}

Content Unit Reports

Aggregate Detailed Content Unit Report

Description

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.

HTTP:GET 

/report/game/<game_id:int>/content/aggregate/report/<report_type:str>

Parameters

ParameterTypeDescription
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

Example Request 

GET /report/game/1/content/aggregate/report/conversions?startts=1330560000&endts=1331164800&content=1,2,3

Example Response 

{
    "errobj": null,
    "response": {
        "startts": 1330560000,
        "endts": 1331164800,
        "datapoints": [
           [
           1330560000,
           544
           ],
           [
           1330646400,
           469
           ],
        ],
        "report": "conversions",
        "game_id": [
           1
        ],
        "content_id": [
           1,
           2,
           3
        ]
    },
"error": null
}

Campaign Reports for Advertisers

Aggregate Campaign Report

Description

Returns aggregate data for one campaign.

HTTP:GET 

/report/game/<game_id:int>/campaign/<campaign_id:int>/report

Parameters

ParameterTypeDescription
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

Example Request 

GET /report/game/2012/campaign/2225/report?startts=1320883200&endts=1323993600

Example Response 

{
    "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
}

Campaign Reports for Advertisers

Detailed Campaign Report

Description

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.

HTTP:GET 

/report/game/<game_id:int>/campaign/<campaign_id:int>/report/<report_type:str>

Parameters

ParameterTypeDescription
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

Example Request 

GET /report/game/1793/campaign/2559/report/impressions?startts=1320883200&endts=1323993600

Example Response 

{
    "errobj": null,
    "response": {
        "report": "impressions",
        "game_ids": [
            1793
         ],
         "startts": 1320883200,
         "campaign_ids": [
             2559
          ],
         "endts": 1323993600,
         "datapoints": [
             [
                 1322092800,
                 31132
             ],
             [
                 1322179200,
                 26934
             ],
             [
                 1322265600,
                 29146
             ],
             ...
         ],
     },
     "error": null
}

UDID

UDID Report

Description

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.

HTTP:GET 

/report/game/<game_id:int>/udid

Parameters

ParameterTypeDescription
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

Example Request 

GET /report/game/2012/udid?date=1324321675

Example Response 

{
    "errobj": null,
    "response": {
    "conversions": [
        [
            "0377a1764751a3cd09ec3f2ed14d872c80aff838",
            1324270579,
            1324274582,
            2315
        ],
        [
            "04a6700f7acfc305d91d673e2d51e1b6601c41ef",
            1324233439,
            1324282368,
            2315
        ],
        [
            "050b161dd31758563259fa402cfeaab1757dc5b4",
            1324229614,
            1324307724,
            2315
        ],
        ...
    },
    "error": null
}

Account Level Reports

Aggregate Account Level Report

Description

Returns meta data at the account level.

HTTP:GET 

/report/report

Parameters

ParameterTypeDescription
auth Authentication token (authentication header may be used instead). Required

Example Request 

GET /report/report?startts=1320883200&endts=1323993600

Example Response 

{
    "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
}

Account Level Reports

Detailed Account Level Report

Description

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.

HTTP:GET 

/report/report/<report_type:str>

Parameters

ParameterTypeDescription
report_type string See the Detailed Account Report Types table.
auth Authentication token (authentication header may be used instead). Required

Example Request 

GET /report/report/spend?startts=1320883200&endts=1323993600

Example Response 

{
    "errobj": null,
    "response": {
        "report": "spend",
        "startts": 1320883200,
        "endts": 1323993600,
        "datapoints": [
            [
                1322092800,
                5.25
            ],
            [
                1322179200,
                0.00
            ],
            [
                1322265600,
                0.00
            ],
            ...
         ],
     },
     "error": null
}

Aggregated Reports

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

Game-level aggregation

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>

Opt In Data Collection Report

Retrieving Collected User Data

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:

ParameterFormatDescription
querycsv, json Valid format options are csv, and json. Defaults to csv. Optional. See details on each format below.

CSV Output Format

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
...

JSON Output Format

[
  ["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"],
 ...
]

Retrieving Account Reports

Retrieving Account Reports

Description

Returns the latest generated reports.

Note Where possible, this API conforms to the standard JSON/JSONP over HTTP API conventions.

HTTP:GET 

/accountreports?<auth:str>&<report_type:str>

Parameters

ParameterTypeDescription
typestring 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

Example Request 1 

GET /accountreport?auth=3faba1eabb53404794bc973cb9269a20&type=publisher

Example Response 1 

{
    '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
        }
    ]
}

Example Request 2 

GET /accountreport?auth=3faba1eabb53404794bc973cb9269a20

Example Response 2 

{
    '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
        }
    ]
}

Example Request 3 

GET /accountreport?auth=3faba1eabb53404794bc973cb9269a20&type=publisher,advertiser

Example Response 3 

{
    '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
        }
    ]
}