Summary API Reports

Last Updated: Jan 09, 2017 05:10PM PST
The summary reporting API provides a set of reports to expose campaign, cohort, and events. Not all packages include access to this API; if you are interested in using this API and your package does not have access, please contact your Apsalar sales representative or account manager.


Base URI: https://clients.apsalar.com/api/

Formats: 

  • JSON: Returns JSON
  • CSV: Returns a downloadable .CSV
  • HTML: Returns a table in the web browser

Arguments explained:

  • 'start' and 'end': Represents the start and end date of the report selection, formatted as 'YYYY-MM-DD'
  • 'days': Positive integer that will return current day plus the number of previous days requested. For example, if '1' is used, the current day's results will be returned and if '2' is used, the current day and yesterday's data will be returned. Where both 'days' and 'start'/'end' appear in a request, 'start'/'end' takes precedence.
  • 'apps': Formatted as platform.longname (e.g. iOS.com.apsalar.sampleapp). Data for multiple apps can be requested by separating with comma
  • 'longname': Represents the longname of the application (e.g. com.apsalar.sampleapp)
  • 'platform': Represents the OS type of the application (e.g. Android or iOS)
  • 'events': Formatted as platform.longname@event_name (e.g. iOS.com.apsalar.sampleapp@_START__, Android.com.apsalar.othersampleapp@__START__)
  • 'event': Formatted as the name of the event (e.g. __START__, PURCHASE)
  • 'dimensions': Represents the dimensions chosen for the report, based on the type of the report, a maximum of 3 dimensions is allowed.
    • possible values for dimensions are "Attribution", "Campaign", "Campaign Source", "Campaign Group", "Publisher", "Country" and "Geographic Region".
    • cohort_report_api allows a maximum of 2 dimensions. 
    • traffic_report_api allows a maximum of 3 dimension
  • 'no_site', 'no_country', 'no_creative' : Formatted to restrict the site, country and creative columns from the output report
  • 'include_attribution', 'include_campaign', 'include_country', 'include_campaign_group', 'include_geographic_region', 'include_campaign_source': Formatted to include the columns in the output report
  • 'exclude_campaign', 'exclude_country', 'exclude_campaign_group', 'exclude_geographic_region', 'exclude_campaign_source': Formatted to exclude the columns in the output report
  • 'summary_type': Formatted to summarize the data based on Daily, Weekly or Monthly, this applies to the date column by row-wise
  • 'breakdown_type': Formatted to break down the columns with cumulative values on column wise
  • 'metric_option': Represents the data type in cohort report. Possible values are "Events" or "Unique Users"
  • 'retention_option': Represents the transform type in cohort report. Possible values are "Count" or "Cumulative"
  • 'referral_only': Restricts the output data to only the non-organic entries
  • 'kind': Represents the kind of login while listing the login. Possible values are "api_keys" or "client_logins"


Reports:


campaign_summary_report - User acquisition report with reengagements broken down by campaign, group, site and creative
  • Argument allowed:
    • start, end, days, apps, no_country, no_site, no_creative
  • Output columns:
    • date - Date that install or re-engagement is attributed to, by click time
    • platform - Android or iOS
    • longname - The bundle ID of the app
    • app_name - The display name of the app as seen in the Apsalar UI
    • campaign - Campaign name that install or re-engagement is attributed to (maps to Campaign in the Traffic Report)
    • group - Group name that install or re-engagement is attributed to (maps to Campaign Group  column in the Traffic Report)
    • network - Network that install or re-engagement is attributed to (maps to Campaign Source column in the Traffic Report)
    • country - Country at the time of install (maps to Country column in the Traffic Report)
    • site - Publisher ID (maps to the Publisher column in the Traffic Report)
    • creative - Creative ID (maps to the Creative column in the Traffic Report)
    • spend - Amount spent on the campaign (limited support)
    • impressions - Impressions generated by the campaign on that date (limited support) (maps to Impressions column in the Traffic Report)
    • clicks - Total clicks for the combination of dimensions in the row (maps to Clicks column in the Traffic Report)
    • installs: Total installs for the combination of dimensions in the row (maps to Attribution column in Traffic Report, for installs)
    • install_lifetime_value - Lifetime revenue from installs for the combination of dimensions in the row (maps to Revenue column in Traffic Report, for installs)
    • install_transactions - Total transactions attributed to installs for the combination of dimensions in the row (maps to Transactions column in Traffic Report, for installs)
    • re-engagements - Total re-engagements for the combination of dimensions in the row (maps to Attribution column in Traffic Report, for re-engagements)
    • re-engagements_lifetime_value - Lifetime revenue from re-engagements for the combination of dimensions in the row (maps to Revenue column in Traffic Report, for re-engagements)
    • re-engagement_transactions - Total transactions attributed to re-engagements for the combination of dimensions in the row (maps to Transactions column in Traffic Report, for re-engagements)
  • Example:
      https://clients.apsalar.com/api/campaign_summary_report.html?start=2016-11-01&end=2016-11-17&apps=Android.com.apsalar.production.accountmanager&no_site&no_creative
      

event_cohort_report - User acquisition report is broken down by campaign, group and site and installs separated from reengagements
  • Argument allowed:
    • start, end, days, events, no_site, no_country
  • Output columns:
    • date - Date that install or re-engagement is attributed to, by click time
    • platform - Android or iOS
    • longname - The bundle ID of the app
    • app_name - The display name of the app as seen in the Apsalar UI
    • event - Name of the event
    • cohort_type - The type of attribution, either "install" or "re-engagement"
    • campaign - Campaign name that install or re-engagement is attributed to (maps to Campaign in the Traffic Report)
    • group - Group name that install or re-engagement is attributed to (maps to Campaign Group  column in the Traffic Report)
    • network - Network that install or re-engagement is attributed to (maps to Campaign Source column in the Traffic Report)
    • publisher - Publisher ID
    • country - Country at the time of install (maps to Country column in the Traffic Report)
    • events - Total events for the combination of dimensions in the row
    • events_day_0 through events_day_30 - Events per day for day 0, day 1, day 2, etc., for the combination of dimensions in the row
    • events_week_0 through events_week_25 - Events per week for week 0, week 1, week 2, etc., for the combination of dimensions in the row
    • unique - Total unique users for the combination of dimensions in the row
    • uniques_day_0 through uniques_day_30 - Unique users per day for day 0, day 1, day 2, etc., for the combination of dimensions in the row
    • uniques_week_0 through uniques_week_25 - Unique users per week for week 0, week 1, week 2, etc., for the combination of dimensions in the row
    • tv - Total lifetime revenue for the combination of dimensions in the row
    • ltv_day_0 through ltv_day_30 - Lifetime revenue per day for day 0, day 1, day 2, etc., for the combination of dimensions in the row
    • ltv_week_0 through ltv_week_25 - Lifetime revenue per week for week 0, week 1, week 2, etc., for the combination of dimensions in the row
  • Example:
      https://clients.apsalar.com/api/event_cohort_report.html?start=2016-09-01&end=2016-09-01&events=Android.com.apsalar.production.accountmanager@__START__,Android.com.apsalar.production.accountmanager@copyAIFA&no_country

event_report - User acquisition report is broken down by campaign, group, and site
  • Argument allowed:
    • start, end, days, events, no_site, no_country
  • Output columns:
    • date - Date that install or re-engagement is attributed to, by click time
    • platform - Android or iOS
    • longname - The bundle ID of the app
    • app_name - The display name of the app as seen in the Apsalar UI
    • event - Name of the event
    • campaign - Campaign name that install or re-engagement is attributed to (maps to Campaign in the Traffic Report)
    • group - Group name that install or re-engagement is attributed to (maps to Campaign Group  column in the Traffic Report)
    • network - Network that install or re-engagement is attributed to (maps to Campaign Source column in the Traffic Report)
    • publisher - Publisher ID
    • country - Country at the time of install (maps to Country column in the Traffic Report)
    • events - Total events for the combination of dimensions in the row
    • events_day_0 through events_day_30 - Events per day for day 0, day 1, day 2, etc., for the combination of dimensions in the row
    • events_week_0 through events_week_25 - Events per week for week 0, week 1, week 2, etc., for the combination of dimensions in the row
    • unique - Total unique users for the combination of dimensions in the row
    • uniques_day_0 through uniques_day_30 - Unique users per day for day 0, day 1, day 2, etc., for the combination of dimensions in the row
    • uniques_week_0 through uniques_week_25 - Unique users per week for week 0, week 1, week 2, etc., for the combination of dimensions in the row
    • tv - Total lifetime revenue for the combination of dimensions in the row
    • ltv_day_0 through ltv_day_30 - Lifetime revenue per day for day 0, day 1, day 2, etc., for the combination of dimensions in the row
    • ltv_week_0 through ltv_week_25 - Lifetime revenue per week for week 0, week 1, week 2, etc., for the combination of dimensions in the row
  • Example:
      https://clients.apsalar.com/api/event_report.html?start=2016-09-01&end=2016-09-01&events=Android.com.apsalar.production.accountmanager@__START__,Android.com.apsalar.production.accountmanager@copyAIFA&no_country

cohort_report_api - User acquisition report by install time
  • Argument allowed:
    • start, end, longname, platform, include_attribution, include_campaign, include_country, include_campaign_group, include_geographic_region, include_campaign_source, exclude_campaign, exclude_country, exclude_campaign_group, exclude_geographic_region, exclude_campaign_source, event, dimensions, summary_type, metric_option, retention_option, referral_only, breakdown_type
  • Output columns:
    • date - Date that install or re-engagement is attributed to, by click time
    • primary_dim - Primary dimension chosen for the cohort
    • secondary_dim - Secondary dimension is chosen for the cohort
    • tot - Total number of events chosen for the argument "event"
    • uniques - The Total unique number of events chosen for the argument "event"
    • size - Number of installs and re-engagements
    • spend - Total spend on the selected cohort
    • col1 through col31 : Split of column from day 1 until day 30
  • Example:
      https://clients.apsalar.com/api/cohort_report_api.html?start=2016-09-01&end=2016-09-01&longname=com.apsalar.production.accountmanager&platform=Android&event=Retention&metric_option=Events&retention_option=Cumulative&dimensions=Attribution,Country&referral_only=false&summary_type=Daily&breakdown_type=day

traffic_report_api - User acquisition report by click time
  • Argument allowed:
    • start, end, longname, platform, include_attribution, include_campaign, include_country, include_campaign_group, include_geographic_region, include_campaign_source, exclude_campaign, exclude_country, exclude_campaign_group, exclude_geographic_region, exclude_campaign_source, dimensions, referral_only
  • Output columns:
    • primary_dim - Primary dimension chosen in the dimension
    • secondary_dim - Secondary dimension is chosen in the dimension
    • tertiary_dim - Tertiary dimension is chosen in the dimension
    • attributions - Number of installs and re-engagements
    • revenue, arpa, clicks, click_thru_rate, impressions, roi, spend, transactions, trend, ecpm, ecpi, ecpc, roas, uninst_rate (multiple values)
  • Example:
      https://clients.apsalar.com/api/traffic_report_api.html?start=2016-09-01&end=2016-09-01&longname=com.apsalar.production.accountmanager&platform=Android&dimensions=Attribution,Country,Campaign&referral_only=false


Access

To access data via the Summary Reporting API, you must provide credentials from your Apsalar account with API access.
  • By default, client permissions are turned off
  • To adjust API settings for your main Apsalar account (if disabled) or to modify the API access for previously added additional users, please contact Apsalar Support


Limitations

  • 100,000 max rows returned
  • If greater than 100,000 rows would be returned from your query, no results will be returned


Loading In Excel

The 'HTML' web query is the most effective method for integrating an API call into Excel in a manner that can easily be refreshed.

Using a .iqy file, it is possible to import API data with prompts for required parameters allowing for quick data refresh. Attached to this article is a sample .iqy file which can be integrated into an Excel file using the following steps:
  • For Windows:
    • Click Data menu option
    • Select Existing Connections
    • Then select Browse for More
    • Select the Apsalar_Summary_Report_API_Sample.iqy file and follow the provided prompts.
  • For Mac:
    • Click Data menu option
    • Select Get External Data
    • Then select Run Saved Query...
    • Select the Apsalar_Summary_Report_API_Sample.iqy file and follow the provided prompts.
support@apsalar.com
http://assets1.desk.com/
apsalarinc
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
Invalid characters found
/customer/en/portal/articles/autocomplete