Return statistics collected about various events, by event type, platform, campaign, etc

Return statistics collected about various events, by event type, platform, campaign, etc.
Using @ALL will return statistics across, say, platforms.
Using @EACH will return statistics for each, say, platform.
You can also ask for a single or a subset of values, like for example platforms=Android,Web.

This API returns data with 3 different level of detail:

  • Global statistics, when [email protected] which is the default.
  • Statistics for each campaign, when [email protected] or when filtering against more than one campaign at a time.
  • Detailed statistics by notification for a single campaign, when using campaignIds=aSingleCampaignId.

@EACH can only be combined with @ALL, when you want to combine statistics, say, across all platforms, as well as to have the detail platform by platform.
By default, the API defaults to @ALL,@EACH. Only event types cannot be combined using @ALL as if would make little sense to add app opens to notifications sent.

The default output format groups counters into per-date objects as shown below:

{
  "data": [
    {
      "date": 1479168000000,
      "dateISO8601": "2016-11-15T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "counters": [
        {
          "type": "@NOTIFICATION_SENT",
          "count": 79
        },
        {
          "type": "@NOTIFICATION_SENT",
          "platform": "Android",
          "count": 42
        },
        {
          "type": "@NOTIFICATION_SENT",
          "platform": "iOS",
          "count": 37
        },
        "…"
      ]
    },
    "…"
  ]
}

You can also ask to merge the counters and date objects to yield what could be called data points:

{
  "data": [
    {
      "date": 1479168000000,
      "dateISO8601": "2016-11-15T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "type": "@NOTIFICATION_SENT",
      "count": 79
    },
    {
      "date": 1479168000000,
      "dateISO8601": "2016-11-15T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "type": "@NOTIFICATION_SENT",
      "platform": "Android",
      "count": 42
    },
    {
      "date": 1479168000000,
      "dateISO8601": "2016-11-15T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "type": "@NOTIFICATION_SENT",
      "platform": "iOS",
      "count": 37
    },
    "…"
  ]
}

Note that you will have as many objects sharing the same date as we had counters within the per-date object previously.

Let's say you are only interested in @NOTIFICATION_SENT events and want a single object per date, with a platform break-down. This is easily done by using both [email protected]_SENT and flatten=platforms:

{
  "data": [
    {
      "date": 1479168000000,
      "dateISO8601": "2016-11-15T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "type": "@NOTIFICATION_SENT",
      "@ALL": 79,
      "Android": 42,
      "iOS": 37
    },
    {
      "date": 1479254400000,
      "dateISO8601": "2016-11-16T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "type": "@NOTIFICATION_SENT",
      "@ALL": 61,
      "Android": 34,
      "iOS": 27
    },
    "…"
  ]
}

Note how the count field disappeared and the different values of platform have been changed into fields.

If you had not controlled the types to return, you would have gotten one object per date and per type, like we had in the previous example with the platforms.

In order to avoid name clashes (especially with custom event names) and to help better identify the counter fields, you can use a prefix.
Here is how the previous example would look by using flattenPrefix=platform::

{
  "data": [
    {
      "date": 1479168000000,
      "dateISO8601": "2016-11-15T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "type": "@NOTIFICATION_SENT",
      "platform:@ALL": 79,
      "platform:Android": 42,
      "platform:iOS": 37
    },
    {
      "date": 1479254400000,
      "dateISO8601": "2016-11-16T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "type": "@NOTIFICATION_SENT",
      "platform:@ALL": 61,
      "platform:Android": 34,
      "platform:iOS": 27
    },
    "…"
  ]
}

You can also opt for a sub-object if you prefer by ending the prefix with a dot. Here is an example using flattenPrefix=values.:

{
  "data": [
    {
      "date": 1479168000000,
      "dateISO8601": "2016-11-15T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "type": "@NOTIFICATION_SENT",
      "values": {
        "@ALL": 79,
        "Android": 42,
        "iOS": 37
      }
    },
    {
      "date": 1479254400000,
      "dateISO8601": "2016-11-16T00:00:00.000+00:00",
      "campaignId": "@ALL",
      "campaignName": "@ALL",
      "type": "@NOTIFICATION_SENT",
      "values": {
        "@ALL": 61,
        "Android": 34,
        "iOS": 27
      }
    },
    "…"
  ]
}

Note, we do not end-up with the default format here, there is no array of counters, but an object containing the flatten field's values as sub-fields and associated counts as values.

The addZero parameter will help you obtain a dense output. When a counter is 0, it is normally not even materialized into existence. The same is true if for a given date we have no counter. If using addZero=true we ensure that missing dates and counters are populated with 0s.

This leads us to the CSV format, controlled by using format=csv. CSV is a table-like format, it has a set of columns presented in the first row, and a list of rows that all have the same columns.
When using the CSV format, you basically impose flattening (using flatten=counters by default) and addZero=true. The keys that would be present in the data-point objects in JSON are all collected and form the set of columns, presented in the first header line. Following are each data-point object.
Note that if you did not sufficiently filtered the output (using [email protected] for instance like before) you might have several lines for a given date.

Here is how the first example would look in CSV:

"date","dateISO8601","campaignId","campaignName","type","platform","count"
1479168000000,"2016-11-15T00:00:00.000+00:00","@ALL","@ALL","@NOTIFICATION_SENT","@ALL",79
1479168000000,"2016-11-15T00:00:00.000+00:00","@ALL","@ALL","@NOTIFICATION_SENT","Android",42
1479168000000,"2016-11-15T00:00:00.000+00:00","@ALL","@ALL","@NOTIFICATION_SENT","iOS",37
…

And here is how it would look in CSV by with [email protected]_SENT and flatten=platforms like a later example:

"date","dateISO8601","campaignId","campaignName","type","@ALL","Android","iOS"
1479168000000,"2016-11-15T00:00:00.000+00:00","@ALL","@ALL","@NOTIFICATION_SENT",79,42,37
1479254400000,"2016-11-16T00:00:00.000+00:00","@ALL","@ALL","@NOTIFICATION_SENT",61,34,27
…
Language
Authentication
Query
Click Try It! to start a request and see the response here!