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" : [
...
]
}