Description
This API allows to export page view event data.
The user must be authenticated and have read permissions to site group/site.
This API is intended for bulk data export and may take extensive time to complete. Do not depend on this API for use in interactive applications or similar scenarios where a low latency response is necessary. Even requests for very limited amounts of data may take a long time to complete.
Count limit and pagination
-
By default the API is limited to exporting maximum 1 000 000 events in one request. If the period specified by
startandstopcontains too many events, the API will respond with an error suggesting to reduce the interval of interest.Alternatively, it is possible to paginate the events by specifyingcount. In this case, the response will contain up to the specified number of events, and apaginationStopif there are more events to retrieve (If there is a tiny mismatch in the count, which can happen due to the nature of eventual consistency of our distributed event database it may return a paginationStop even if the rest are 0 events).The returnedpaginationStopcan then be included in the next request as apaginationStartallowing to paginate without any bi-effect on the specified filters, such asexplodeUsers.
Customers need to keep calling the API until paginationStop is no longer provided.
When using pagination, set start and stop of subsequent requests to the start/stop value returned by the first request. Note that time filters using relative offsets (such as segments) may affect the result.
If count is too low (i.e., there are more than 1000 events per second), the response will contain an empty set of events and a paginationStop. This indicates that the API user must either increase the count or stop the execution to avoid an infinite loop.
See the examples below.
About uniqueness of events
Events are evaluated for uniqueness using the userId, eventId, time and url fields. Some events can have the same eventId in some cases. However, those events with the same eventId are treated as unique events because the other fields are different.
If a unique identifier is needed for reporting purposes, one can concatenate and hash the four fields in a page view record. For example, in psuedo-code:
eventKey = sha256(userId + eventId + time + url)
Request
The request object has the following fields:
|
Name |
Type |
Required |
Description |
|---|---|---|---|
|
|
Array of String |
No |
The set of sites to aggregate over. |
|
|
String |
No |
The site to aggregate over. A more convenient alternative to |
|
|
Array of String |
No |
The set of site groups to aggregate over. |
|
|
String |
No |
The site group to aggregate over. A more convenient alternative to |
|
|
Integer or String |
No |
The start time of the period of interest specified according to Traffic time specification. The default value is one hour ago. |
|
|
Integer or String |
No |
The stop time of the period of interest specified according to Traffic time specification. The value is exclusive. Default value is right now. |
|
|
Array of Object |
No |
Traffic filters to be applied. Conjunctive semantics ( |
|
|
Array of String |
No |
The event fields to export. The available field names can be found below or via /traffic/data/describe. Only the t |
|
|
Array of String |
No |
The external user identifier types to return. Must be specified whenever externalUserIds field is requested. Use /traffic/data/describe to list available identity types. Only the specified and found types will be included in the response. |
|
|
Array of String |
No |
The specific origins to use in combination with DMP filters (the filters starting with " |
|
|
String |
No |
The origin to aggregate over. A more convenient alternative to |
|
|
Integer |
No |
The pagination count. When specified, instead of failing on too many events, the response will contain up to the specified count of events and a |
|
|
Integer |
No |
The time of the first event to be included in the result. The field can only be used in combination with |
The available fields are given below. These names and values are similar to the group names and values used in /traffic/event as much as possible:
|
Name |
Description |
Example response value |
|---|---|---|
|
|
The time of event, measured in Unix time. Returned by default. |
|
|
|
The cross-site user identifier which can be used to differentiate devices/browsers, lookup user profiles (e.g., /profile/user), or filtering by the user id. For the latter purpose, the corresponding filter will be: |
|
|
|
The alternative cross-site identifier. The returned identifier can be used to differentiate devices/browsers,but not for user profile lookups or filtering. This field is deprecated and it is recommended to use userId instead. |
6bfffa9c4e0daabe |
|
|
The requested and known external user identities associated with the user.The identity types must be specified in the request via |
|
|
|
The identifier used to differentiate distinct events from the same user. |
|
|
|
The site identifier. |
|
|
|
Indicates whether the event is considered as the first event in session. |
|
|
|
Indicates whether the event is considered as the last event in session. |
|
|
|
Indicates whether the event is considered as the only event in session. |
|
|
|
The active time on a page in seconds, if known. |
|
|
|
|
|
|
|
The name of the browser. |
|
|
|
The name of the browser version. |
|
|
|
The language used by the browser. |
|
|
|
The timezone used by the browser in minutes relative to UTC. |
|
|
|
The name of the operating system. |
|
|
|
The brand of the mobile device. |
|
|
|
The type of the device. |
|
|
|
The URL of the visited page. |
|
|
|
The name of the site hosting the page. |
|
|
|
The user query associated with a particular event. |
|
|
|
The URL of the referrer page. |
|
|
|
The name of the site hosting the referrer page. |
|
|
|
Classification of the referrer host. |
|
|
|
The name of the referrer search engine. |
|
|
|
The name of the referrer social network. |
|
|
|
The name of the referrer news aggregator. |
|
|
|
The user query associated with the referrer/preceding event. |
|
|
|
The desktop resolution. |
|
|
|
The color depth used by the device. |
|
|
|
The country code inferred from the user's IP address. |
|
|
|
The region code inferred from the IP address. |
|
|
|
The city name inferred from the IP address. |
oslo |
|
|
The metro code (DMA) inferred from the IP address, if available. |
oslo |
|
|
The postal code inferred from the IP address, if available. |
10023 |
|
|
The company/provider name inferred from the IP address. |
|
|
|
The connection speed/type inferred from the IP address. |
|
|
|
The ISO 3166-2 region code inferred from the IP address. |
no-03 |
|
|
The name of the site hosting the exit link page. |
|
|
|
The name of the exit link host. |
|
|
|
The user query associated with the exit link. |
|
|
|
The browser/device capabilities. |
|
|
|
The list of displayed ad space identifiers. |
|
|
|
The list of intents. |
["cake"] |
|
|
The list of custom parameters. |
|
|
|
The list of user profile parameters. |
|
|
|
The list of retargeting profile parameters. |
|
|
|
The scroll depth on a page in percents, if known. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Response
The response object has the following fields:
|
Name |
Type |
Description |
|---|---|---|
|
|
Integer |
The start time of the period of intertest in seconds, measured in Unix time. |
|
|
Integer |
The stop time of the period of interest in seconds, measured in Unix time. |
|
|
Array of Object |
The list of events where each event consists of specified field names and the corresponding values. |
|
|
Integer |
The pagination start time if any was specified. The value represents seconds measured in Unix time. |
|
|
Integer |
The pagination stop time if |
Examples
Example
$ python cx.py /traffic/data '{"start":"-1h", "siteId":"12345", "fields":["eventId", "userId", "url","customParameters", "externalUserIds"], "externalUserIdTypes":["cxd"]}'
{
"start": 1443005094,
"stop": 1443005694,
"events": [
{
"time": 1443005573,
"userId": "cx:24e3e2b04:ksfrvi",
"eventId": 921814992,
"externalUserIds": [
{
"type": "cxd",
"id": "CRM91595539"
}
],
"customParameters": [
{
"group": "cx_source",
"item": "cxrecs"
}
],
"url": "https://example.com/frontpage"
}
]
}
Pagination examples
# Limit the result to at maximum 1000 events. The response indicates that there are more events to retrieve.
$ python cx.py /traffic/data '{"start": 1443005570, "stop": 1443005580, "siteId":"23456", "count":1000}'
{
"start": 1443005570,
"stop": 1443005580,
"events": [{"time": 1443005570}, ... ,{"time": 1443005573},{"time": 1443005573}], # 999 events
"paginationStop": 1443005574
}
# Limit the result to at maximum 1000 events starting from 1443005574. The response indicates that there are more events to retrieve.
$ python cx.py /traffic/data '{"start": 1443005570, "stop": 1443005580, "siteId":"23456", "count":1000, "paginationStart": 1443005574}'
{
"start": 1443005570,
"stop": 1443005580,
"events": [{"time": 1443005574},{"time": 1443005574}, ... ,{"time": 1443005578},{"time": 1443005578}], # 997 events
"paginationStart": 1443005574,
"paginationStop": 1443005579
}
# Limit the result to at maximum 1000 events starting from 1443005578. The response indicates that there are no more events to retrieve.
$ python cx.py /traffic/data '{"start": 1443005570, "stop": 1443005580, "siteId":"23456", "count":1000, "paginationStart": 1443005579}'
{
"start": 1443005570,
"stop": 1443005580,
"events": [{"time": 1443005579},{"time": 1443005579},{"time": 1443005579},{"time": 1443005579}] # 4 events
"paginationStart": 1443005579
}
# Limit the result to at maximum 1000 events. The response indicates that the count is too low.
$ python cx.py /traffic/data '{"start": 1442995570, "stop": 1442995580, "siteId":"23456", "count":1000}'
{
"start": 1442995570,
"stop": 1442995580,
"events": [],
"paginationStop": 1442995570
}