Reporting

We have 4 types of reports:

  • advertiser-level reports
  • publisher-level reports
  • network-level reports
  • inventory reports

Reports are constructed using JSON.

Here is an example report:

{
  "scope": "advertiser",
  "groups": [
    "campaign_id"
  ],
  "metrics": [
    "impressions"
  ],
  "where": [
    ["advertiser_id", "==", "1337"]
  ],
  "from": "2016-04-01 00:00:00",
  "to": "2016-05-02 00:00:00",
  "timezone": "UTC",
  "emails": ["test@example.com"]
}
Parameter Required Description
scope Yes is the string advertiser, publisher, network_buy, network_sell, network_managed or inventory to select the type of report.
groups Yes* is a list of group columns
metrics Yes* is a list of metric columns.
where Yes is a list of expression lists.
An expression list is in the form of [column, op, value].
column can be any of the group columns or sum columns.
op can be any of ==, !=, in or not in as a string.
value is either a number or in case of in and not in an list of numbers.
from Yes is a date/time formatted like YYYY-MM-DD HH:00:00 and is inclusive.
It is truncated to the hour.
to Yes is a date/time formatted like YYYY-MM-DD HH:00:00 and is exclusive.
It is truncated to the hour.
timezone Yes Timezone used for all times. For a supported list see: timezones
emails No Array of email addresses that get a notification email once the report is ready to download
name No Optional name for the report

* Note: either groups or metrics is required.

The JSON should be POSTed to http://api.atomx.com/v3/report. The following parameters are accepted:

Parameter Value Description
sort [column_name].[asc|desc] Sorting ascending or descending on column names
limit number Specify the number of rows to return. 0 or omitted means unlimited
offset number Specify the row to start at. Default is 0
download none or [excel|excel-tab|unix] Download the report as CSV instead of inside JSON. If a string is provided, export in specified dialect. Defaults to 'excel' (CSV)
save none or [true|false] Should the report be saved in the users report history. Defaults to true
editable none or [true|false] Should other users be able to change the date range of this report. Defaults to false

This will return a JSON like:

{
  'success': <true or false>,
  'timestamp': <timestamp>,
  'resource': 'report',
  'report': {
    'id': <report ID>,
    'length': <number or rows>,
    'name': <report name>,
    'totals': <sum of each column>,
    'columns': <names of the columns>,
    'data': <list of lists with the data>,
    'user_id': <ID of the user who created the report>,
    'emails': <list of emails>,
    'is_scheduled_report': <true or false>,
    'whitelabel_url': <url the report was run on>,
    'lines': <number of lines in result>,
    'query': <your original query>
  }
}

You can re-run the report by requesting http://api.atomx.com/v3/report/{report-id}

Groups

Advertiser:

Numeric value String value String + numeric value
advertiser_id advertiser_name advertiser_name_id
advertiser_network_id advertiser_network_name advertiser_network_name_id
app_id app_name app_name_id
browser_id browser_name browser_name_id
campaign_id campaign_name campaign_name_id
conversion_pixel_id conversion_pixel_name conversion_pixel_name_id
country_id country_name country_name_id
creative_id creative_name creative_name_id
device_type_id device_type_name device_type_name_id
dma_id dma_name dma_name_id
domain_id domain_name domain_name_id
operating_system_id operating_system_name operating_system_name_id
placement_type_id placement_type_name placement_type_name_id
publisher_id publisher_name publisher_name_id
publisher_network_id publisher_network_name publisher_network_name_id
site_id site_name site_name_id
size_id size_name size_name_id
day
hour
month

Publisher:

Numeric value String value String + numeric value
advertiser_id advertiser_name advertiser_name_id
advertiser_network_id advertiser_network_name advertiser_network_name_id
app_id app_name app_name_id
browser_id browser_name browser_name_id
country_id country_name country_name_id
device_type_id device_type_name device_type_name_id
dma_id dma_name dma_name_id
domain_id domain_name domain_name_id
operating_system_id operating_system_name operating_system_name_id
placement_id placement_name placement_name_id
placement_type_id placement_type_name placement_type_name_id
publisher_id publisher_name publisher_name_id
publisher_network_id publisher_network_name publisher_network_name_id
site_id site_name site_name_id
size_id size_name size_name_id
user_variable_1
user_variable_2
user_variable_3
day
hour
month

Network Buy:

Numeric value String value String + numeric value
advertiser_id advertiser_name advertiser_name_id
advertiser_network_id advertiser_network_name advertiser_network_name_id
app_id app_name app_name_id
browser_id browser_name browser_name_id
campaign_id campaign_name campaign_name_id
conversion_pixel_id conversion_pixel_name conversion_pixel_name_id
country_id country_name country_name_id
creative_id creative_name creative_name_id
device_type_id device_type_name device_type_name_id
dma_id dma_name dma_name_id
domain_id domain_name domain_name_id
network_id network_name network_name_id
operating_system_id operating_system_name operating_system_name_id
placement_type_id placement_type_name placement_type_name_id
publisher_id publisher_name publisher_name_id
publisher_network_id publisher_network_name publisher_network_name_id
site_id site_name site_name_id
size_id size_name size_name_id
day
hour
month

Network Sell:

Numeric value String value String + numeric value
advertiser_id