Impressions

Impression data is data generated from our standard on-page JS. Once you've created campaigns, and whitelisted the content you'd like to see tracked, you can request data about the campaigns here.

In general, this API is built to be as flexible as possible, to help you retrieve the data you need, in the absolute least amount of time and effort. We have several parts of the query construction process.

All requests should be POST requests to https://ndg.io/api/v3/analytics/impressions with the below as keys. Body should be JSON encoded, with the header Content-Type set to application/json.

Notes:

  • There are several more filters, groups, and metrics coming. This will be part of the same V3 API, and fit into the existing format.
  • If a group doesn't exist, a metric doesn't have any values for a given day in a date range, or your campaign doesn't exist (or belong to you) Nudge will not return data.

Rate Limits

This is currently not enforced. However, we will start with limiting to 5 campaign or URL requests per minute. This means that you can either:

  • Submit 5 API requests each with 1 campaign or URL inside them
  • Submit 1 API request with 5 campaigns
  • Submit 1 API request with 3 campaigns and 2 URL IDs
  • Submit 3 API requests, 2 with 1, and 1 each inside the next 3

With any new API call, we need to get an understanding of usage patterns. With the new flexible API, this is difficult to look into. This limit will adjust as we get a better idea of performance.

Filters

Filters (key filters). Should contain the filters for the data you wish to view. The options are below.

Key Required Format Description
url_ids yes (one url_id or campaign_id) Either a list of Nudge URL IDs, or a single URL ID. This will run the described checks for the given URL ID(s). This can be used in conjunction with campaign_ids.
campaign_ids yes (one campaign_id or url_id) Either a list of Nudge campaign IDs or a single campaign ID. This will run the described cehcks for the given campaign ID(s). This can be used in conjunction with url_ids.
created_gte no YYYY-mm-dd HH:MM:SS (i.e. 2019-04-01 14:59:41) This is the lower date range limit you're requesting.
created_lte no YYYY-mm-dd HH:MM:SS (i.e. 2019-04-01 14:59:41) This is the upper date range limit you're requesting.
device no desktop / mobile / tablet This will only show you results for the given device type.
timezone no Full timezone name (i.e. US/Eastern, or Pacific/Auckland) This should be used if you're wanting to see data as it was in your local time. Defaults to UTC. Note: setting this will not only affect the date filters, but also the response data. Any dates / times in a response will also be in the timezone requested.

Groups

Groups (key groups) allows you to describe the dimensions by which your data should be split up by. Each unique combination of groups will yield a new row in the report, with each of the metrics below supplied. Please use the least amount of groups as you need. These can add a lot of time to your requests.

Key Description Data type
day Create a new group for each day. Please use the timezone filter to ensure correct days. string
url Create a new group for each URL in a campaign. string
device Create a new group for each device we see. string
traffic_source Create a new group for each traffic source we see. string
creative Create a new group for each creative we see. string
placement Create a new group for each placement we see. string
publisher Create a new group for each publisher we see. string
country Create a new group for each country we see. string
city Create a new group for each city we see. string

Metrics

Metrics (key metrics) describes which metrics will be visible in each group defined above. Please use the least amount of metrics as you require at a time, the more you add, the longer your request will take. At least one metric is required for each request.

Note: float values will show 0 as their 0 value, not 0.0.

Key Description Data type
impressions The total impressions measured. integer
people The total unique users measured. integer
total_time_spent The total time spent (seconds) we've measured. integer
average_time_spent The average time spent (seconds) we've measured. float
total_scrolled The total scroll distance travelled by all users. float
average_scrolled The average scroll fraction your users have gone down the page. Expressed as a percentage. float
total_bounced The total number of users who have bounced, where they have spent less than 5 seconds on page. integer
average_bounced The average number of bounced users. Expressed as a percentage. float
earned_impressions The total earned impressions for all users in the group. integer
time_taken_segments This will return the average time taken to reach 10%, 20%, 30%..100% of the page. In seconds. float
impressions_at_time This will return the total impressions at 3, 5, 7, 10, 15, 20, 30 seconds. integer
scroll_drop_off This will return the total users at 10% scrolled, 20%, 30%..100% of the page. integer
virality This will return the total virality for the group. float

Ordering

Ordering (key order) is useful if you want to calculate the top N. This should be a list items that also appear in the metrics or groups keys.

Note: Ordering cannot be applied to time_taken_segments, impressions_at_time, or scroll_drop_off metrics.

Order direction

This only needs to be set if the order key is used. Set this to -1 if you'd like the largest values first. Set to 1 if you'd like the smallest values first. If you set order, we default to -1.

Limit

This limits the results, and is only useful if order and order_direction have been supplied.

Example

Give me the impressions and people each day through January using tablet for a campaign and a URL.

{
    "filters" : {
        "url_ids" : ["url_id_here"],
        "campaign_ids" : ["campaign_id_here", "second_campaign_here"],
        "timezone" : "US/Eastern",
        "device" : "tablet",
        "created_gte" : "2019-01-01 00:00:00",
        "created_lte" : "2019-01-31 23:59:59"
    },
    "metrics" : ["impressions", "people"],
    "groups" : ["day"]
}

Response:
{
    "url_id_here" : [
        {
            "day" : "2019-01-01",
            "impressions" : 41,
            "people" : 30
        },
        {
            "day" : "2019-01-02",
            "impressions" : 141,
            "people" : 100
        },
        ...
    ],
    "campaign_id_here" : [
        ...
    ],
    "seconds_campaign_here" : [
        ...
    ]
}