The User Activity API allows a Google Analytics property owner to retrieve all analytics measurement data associated with a single user. Specifically, the API retrieves all of the measurement data associated with a particular User ID or Client ID.
Making a User Activity Request
To make a User Activity Request, construct a request object with the following fields:
The Client ID or User ID associated with the user
- See Cookies and User Identification for details on how to look up these fields.
An Analytics View ID containing the data associated with the user.
- You can use the Account Explorer to look up your view ID.
While not required, you will probably need a date range for the data you're interested in. By default, the API lists user activity for the past week.
Sample Request
POST https://analyticsreporting.googleapis.com/v4/userActivity:search
{
"viewId": "9999999",
"user": {
"type": "CLIENT_ID",
"userId": "1034600000.76425000000"
},
"dateRange": {
"startDate": "2018-01-01",
"endDate": "2018-12-31",
}
}
Sample Response
{
"sessions": [{
"sessionId": "1539184430",
"deviceCategory": "desktop",
"platform": "Windows",
"dataSource": "web",
"sessionDate": "2018-10-10"
"activities": [{
"activityTime": "2018-10-10T08:13:50.555105Z",
"source": "(direct)",
"medium": "(none)",
"channelGrouping": "Direct",
"campaign": "(not set)",
"keyword": "(not set)",
"hostname": "shop.googlemerchandisestore.com",
"landingPagePath": "/gpsmap",
"activityType": "PAGEVIEW",
"customDimension": [{
"index": 1,
"value": "(not set)"
}, ...]
}, ...]
}, ...]
"totalRows": 1000,
"nextPageToken": "A6JGY3",
"sampleRate": 1
}
Sessions and Activities
User activity data is grouped by session. Each
session contains general
information about the session, such as session ID and date, as well as a list
of user activities for that session.
The user activities in a session consist
of every "hit" for which the user was responsible; this includes things like
pageviews, ecommerce events, and custom events sent via gtag(...)
or ga(...)
.
Pagination
The User Activity API uses pagination to break up large data sets into multiple requests and responses. However, because the data returned by the API is structured hierarchically, some special considerations need to be taken by the developer in order to correctly collate the data.
The basic "row" type for the purpose of pagination is the Activity. Because User Data is grouped by session, this means that a page boundary can occur inside of a session, and that session can have can have activities spanning multiple pages.
Sample Data
For demonstration purposes, we'll use the following sample data. In this example, the user interacted with the site in 6 sessions over the course of 3 days.
Date | Session ID | Event Label | Time |
---|---|---|---|
2018-11-23 | 1 | A | 10:26 |
2018-11-23 | 1 | B | 10:32 |
2018-11-23 | 1 | C | 10:39 |
2018-11-23 | 2 | A | 18:04 |
2018-11-23 | 2 | B | 18:11 |
2018-11-23 | 2 | C | 18:26 |
2018-11-24 | 3 | A | 11:26 |
2018-11-24 | 3 | B | 11:29 |
2018-11-24 | 3 | C | 11:39 |
2018-11-24 | 3 | D | 11:42 |
2018-11-24 | 4 | A | 23:50 |
2018-11-24 | 4 | B | 23:54 |
2018-11-25 | 5 | C | 00:02 |
2018-11-25 | 5 | D | 00:13 |
2018-11-25 | 6 | A | 13:01 |
2018-11-25 | 6 | B | 13:09 |
2018-11-25 | 6 | C | 13:12 |
2018-11-25 | 6 | D | 13:23 |
Single Page
If you make a user activity request with a pageSize
of at least 18, the data
will all be delivered in a single page, and will look something like this:
POST https://analyticsreporting.googleapis.com/v4/userActivity:search
{
"viewId": "9999999",
"user": {
"type": "CLIENT_ID",
"userId": "1034600000.76425000000",
},
"dateRange": {
"startDate": "2018-11-20",
"endDate": "2018-11-30",
},
"pageSize": 100,
}
{
"totalRows": 18,
"sessions": [{
"sessionId": "1",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T10:26:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-23T10:32:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-23T10:39:00",
"event": {"eventLabel": "C"}
}]
}, {
"sessionId": "2",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T18:04:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-23T18:11:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-23T18:26:00",
"event": {"eventLabel": "C"}
}]
}, {
"sessionId": "3",
"sessionDate": "2018-11-24",
"activities": [{
"activityTime": "2018-11-24T11:26:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-24T11:29:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-24T11:39:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-24T11:42:00",
"event": {"eventLabel": "D"}
}]
}, {
"sessionId": "4",
"sessionDate": "2018-11-24",
"activities": [{
"activityTime": "2018-11-24T23:50:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-24T23:54:00",
"event": {"eventLabel": "B"}
}]
}, {
"sessionId": "5",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T00:01:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-25T00:13:00",
"event": {"eventLabel": "D"}
}]
}, {
"sessionId": "6",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T13:01:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-25T13:09:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-25T10:12:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-25T10:23:00",
"event": {"eventLabel": "D"}
}]
}]
}
Multiple Pages
However, if your page size is 5, then this data will be broken up into 4 response pages:
Date | Session ID | Event Label | Time |
---|---|---|---|
Page 1: | |||
2018-11-23 | 1 | A | 10:26 |
2018-11-23 | 1 | B | 10:32 |
2018-11-23 | 1 | C | 10:39 |
2018-11-23 | 2 | A | 18:04 |
2018-11-23 | 2 | B | 18:11 |
Page 2: | |||
2018-11-23 | 2 | C | 18:26 |
2018-11-24 | 3 | A | 11:26 |
2018-11-24 | 3 | B | 11:29 |
2018-11-24 | 3 | C | 11:39 |
2018-11-24 | 3 | D | 11:42 |
Page 3: | |||
2018-11-24 | 4 | A | 23:50 |
2018-11-24 | 4 | B | 23:54 |
2018-11-25 | 5 | C | 00:02 |
2018-11-25 | 5 | D | 00:13 |
2018-11-25 | 6 | A | 13:01 |
Page 4: | |||
2018-11-25 | 6 | B | 13:09 |
2018-11-25 | 6 | C | 13:12 |
2018-11-25 | 6 | D | 13:23 |
Notice that session 2 is broken up across the first and second pages, and that the 2 sessions on November 24 are broken up across the second and third pages. The responses will look something like this:
{
"totalRows": 18,
"nextPageToken": "UGMGQS",
"sessions": [{
"sessionId": "1",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T10:26:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-23T10:32:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-23T10:39:00",
"event": {"eventLabel": "C"}
}]
}, {
"sessionId": "2",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T18:04:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-23T18:11:00",
"event": {"eventLabel": "B"}
}]
}]
}
{
"totalRows": 18,
"nextPageToken": "1FKOME",
"sessions": [{
"sessionId": "2",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T18:26:00",
"event": {"eventLabel": "C"}
}]
}, {
"sessionId": "3",
"sessionDate": "2018-11-24",
"activities": [{
"activityTime": "2018-11-24T11:26:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-24T11:29:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-24T11:39:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-24T11:42:00",
"event": {"eventLabel": "D"}
}]
}]
}
{
"totalRows": 18,
"nextPageToken": "7S77H6",
"sessions": [{
"sessionId": "4",
"sessionDate": "2018-11-24",
"activities": [{
"activityTime": "2018-11-24T23:50:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-24T23:54:00",
"event": {"eventLabel": "B"}
}]
}, {
"sessionId": "5",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T00:01:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-25T00:13:00",
"event": {"eventLabel": "D"}
}]
}, {
"sessionId": "6",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T13:01:00",
"event": {"eventLabel": "A"}
}]
}]
}
{
"totalRows": 18,
"sessions": [{
"sessionId": "6",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T13:09:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-25T10:12:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-25T10:23:00",
"event": {"eventLabel": "D"}
}]
}]
}
Data Sampling
If a client has accumulated a huge amount of data for the requested date
range, the API may return only a sampled subset of activities. When this
happens, the sampleRate
field will indicate what fraction of the user's
activities were returned.
How data is sampled
The user data is sampled at the activity level. For instance, with a sampling
rate of 50% (0.5
), half of the user's activities will be present in the
response.
These sampled activities are selected arbitrarily; the API does not provide any guarantees about random sampling, nor that the sampling is proportional across activities for the given date range.
Prevent data sampling
Because this API treats a session as simply a collection of activities, any sessions for which no activities appear in the sampled set will not appear in the response. If you require a comprehensive list of sessions or activities, make follow-up requests with smaller date ranges.
For example, if you request data from 2018-01-01
to 2018-12-31
, and the
response indicates a sampling rate of 0.25
, divide the requested date range
into 4 parts, such that each part will hopefully contain about a quarter of the
original data:
2018-01-01
to2018-03-31
2018-04-01
to2018-06-30
2018-07-01
to2018-09-30
2018-10-01
to2018-12-31