AdGear reporting service API documentation

The reporting service is used to query our analytics database through a REST interface. Since the execution time and result set size of a given query are not known in advance and may be large, the interface we provide is asynchronous.

The core model is a query. The query structure defines the computation that will be run on the analytics engine. The parameters that are required for all queries are a type (representing the fact table), a date range (limiting the rows considered), a list of dimensions that are required to pivot and a list of metrics to aggregate around the dimensions. Here’s an example of a valid query:

{
  "type": "trader_delivery",
  "start_date": "2016-04-01T00:00:00",
  "end_date": "2016-04-07T23:59:59",
  "time_zone": "America/Montreal",
  "dimensions": ["month", "campaign_id", "flight_id"],
  "metrics": ["impressions", "impressions_dropped", "clicks", "clicks_dropped", "ctr"],
  "filter": "advertiser_id = 52",
  "metrics_filter": "impressions > 100",
  "order_fields": ["month", "-impressions"],
  "limit": 10
}

Note that specifying both a start and an end date is mandatory, but the time zone is optional, and will default to UTC (which can also be specified explicitly using time zone “Etc/UTC”). Valid time zone names include “America/Los_Angeles”, “America/Toronto”, “America/Montreal”, “America/New_York”, and “Europe/London”.

In a query, the filter field takes the shape of a SQL predicate expression (the kind of subexpression one can put in a WHERE clause): a more complex example than the advertiser_id = 52 filter above could be advertiser_id = 52 AND advertiser_name = 'Acme'. Likewise, metrics_filter is a SQL boolean expression, to be used as an aggregate filter (HAVING clause), for example impressions > 100 AND impressions < 800.

The next most important model is the Report. A report is mostly metadata that surrounds a query. The workflow of a query is the following:

• User asks for a report to be built;
• the reporting service acknowledges the query and gives the user information needed to query its status ;
• the reporting service executes the query in background:
  • on success, the results get saved and we notify the user with URLs;
  • on failure, we notify the user of the failure.

Here’s an example of a report:

{
  "id": 1,
  "public_id": "628a3960-521a-11e3-8f96-0800200c9a66",
  "status": "completed",
  "urls": [
    "http://reporting.trader.adgear.com/public/123.csv.gz",
    "http://reporting.trader.adgear.com/public/456.tsv.zip"
  ],
  "secure_urls": [
    "https://reporting.trader.adgear.com/public/123.csv.gz",
    "https://reporting.trader.adgear.com/public/456.tsv.zip"
  ],
  "created_at": "2016-04-01T00:00:00Z",
  "updated_at": "2016-04-01T00:00:00Z",
  "author_id": 1,
  "author_name": "Json Smith",
  "title": "test title",
  "metadata": "{\"my_custom_property\":\"my_custom_value\"}",
  "query": {
    "type": "adgear_agency_delivery",
    "start_date": "2016-04-01T00:00:00Z",
    "end_date": "2016-04-07T23:59:59Z",
    "dimensions": ["campaign_id"],
    "metrics": ["impressions"],
    "filter": "campaign_id = 52",
    "order_fields": ["campaign_id", "-impressions"],
    "limit": 1,
    "offset": 0
  },
  "notification": {
    "emails": ["json.smith@gmail.com"],
    "http_callbacks": ["http://my.callback.com/"]
  },
  "report_url": "http://reporting.trader.adgear.com/reports/1",
  "report_public_url":
    "http://reporting.trader.adgear.com/reports/public/628a3960-521a-11e3-8f96-0800200c9a66",
  "output_formats": [
    {"format" : "tsv", "compression" : "zip"},
    {"format" : "csv", "compression" : "gzip"},
    {"format" : "xlsx", "compression" : "none"}
  ]
}

On report completion (successful or not), e-mail addresses mentioned receive a message giving a short summary of the report’s status and instructions to download the actual report (essentially, the value of the report_public_url field). Callbacks URLs receive, as a POST request body, a JSON description of the report, in the same format as the example above.

Error codes are as follows:

• 1 - UNEXPECTED ERROR
• 2 - QUERY EXECUTION TIMEOUT EXCEEDED

Authentication

Authentication credentials must be provided using an ‘Authorization’ HTTP header with a value specified as follows: ‘Bearer <username>:<api_auth_token>’