These functions provide access to historical events across basic users.
As with Analytics Library, the bucketed functions (GlobalAnalytics.bin_by...) produce statistics where date is grouped into "buckets". Buckets are automatically selected depending on the DateRange
size:
- Less than a day: minute buckets
- 1 day to 2 months: hour buckets
- 2 months to 1 year: day buckets
- 1 year to 10 years: week buckets
- 10+ years: month buckets
Import
To use this library and its functions, you must use the import line at the beginning of your Base Python code.
import GlobalAnalytics
Functions
Get events from stream
GlobalAnalytics.events_by_stream(stream_name, filters=None, date_range=None, limit=1000, sort=None)
Returns the events in the specified stream, subject to filters, date_range, limit, and sort.
Credit cost: 1
Parameters
- stream_name:
str
name of stream from which to retrieve data - filters:
Filter
to limit events by tag (Filter Library) - date_range:
DateRange
to query events between specific dates (DateRange Library) - limit:
int
maximum number of values to return - sort:
list|tuple
pair of strings defining tag to sort by and sort order- Example 1: ['observed_at', 'DESC']
- Example 2: ('age', 'ASC')
Return Value
list
dictionaries containing each event's user
, observed_at
time, stream_id
, event_data
, and event_id
.
Example
-
Sample Code:
import GlobalAnalytics events = GlobalAnalytics.events_by_stream('raw', limit=1, sort=['observed_at', 'ASC'])
- Return Value:
[ { "observed_at": "2015-04-11T21:36:53.832111+00:00", "stream_id": 4041905582898064089, "event_id": 4123154489749871,
"user": "user1", "event_data": { "action": "Help Request", "sensor_id": "Kiosk_3", "type": "Kiosk" } } ]
Exceptions
- InsightsException
- Any insights error such as non-existent tag or stream, or issues communicating with insights
Bin by time
GlobalAnalytics.bin_by_time(tag_name, date_range, population=None)
Returns statistics for the population defined by population, for tag_name data. Data is from the period specified by date_range and is bucketed based on the date_range window.
Credit cost: 1
Parameters
- tag_name:
str
tag name, including stream name (eg. "raw.score") - date_range:
DateRange
to limit statistics by date (DateRange Library) - population:
PopulationFilter
to limit statistics by population (PopulationFilter Library)
Return Value
list
list of dicts containing the observed_at timestamp for the bucket as well as the average, min, max, and count for that bucket.
Example
-
Sample Code:
import GlobalAnalytics import DateRange week = DateRange.this_week() bin_by_time = GlobalAnalytics.bin_by_time('raw.test', week)
- Return Value:
[ { "observed_at": "2015-04-11T21:36:53.832111+00:00", "avg": 123, "min": 123, "max": 123, "count": 123 }, … ]
Exceptions
- InsightsException
- Any insights error such as non-existent tag or stream, or issues communicating with insights
Bin by value
GlobalAnalytics.bin_by_value(tag_name, population=None)
Returns the distribution of all distinct values of a particular tag for all events for all users in the defined population.
For each distinct value, the number of occurrences, its percentage of the whole, and its rank are returned. Note that ranks can occur multiple times in the case of ties.
Credit cost: 1
Parameters
- tag_name:
str
tag name, including stream name (eg. "raw.score") - population:
PopulationFilter
to limit statistics by population (PopulationFilter Library)
Return Value
list
list of dicts, one for each distinct value, containing the number of occurrences, its percentage of the whole, and its rank
Example
-
Sample Code:
import GlobalAnalytics import DateRange week = DateRange.this_week() bin_by_value = GlobalAnalytics.bin_by_value('raw.test', week)
- Return Value:
[ { "count": 30, "percent": 90.9090909090909, "rank": 1, "value": 5 }, ... ]
Exceptions
- InsightsException
- Any insights error such as non-existent tag or stream, or issues communicating with insights
List users
GlobalAnalytics.list_users(population=None)
Returns a list of users in the population defined by a population filter.
Credit cost: 1
Parameters
- population:
PopulationFilter
to limit users by population (PopulationFilter Library)
Return Value
list
list of dicts including each user's login_id and user ID
Example
-
Sample Code:
import GlobalAnalytics all_users = GlobalAnalytics.list_users()
- Return Value:
[{u'login_id': u'user1', u'user': 352769716122759168L}, {u'login_id': u'user2', u'user': 352771148062351360L}]
Exceptions
- InsightsException
- Issues communicating with insights
Check if basic user exists
GlobalAnalytics.check_user_exists(login_id)
Returns True if the API Basic User already exists, False otherwise.
Credit cost: 1
Parameters
- login_id:
str
username of the user that is being checked
Return Value
bool
Example
-
Sample Code:
import GlobalAnalytics exists = GlobalAnalytics.check_user_exists('user1')
- Return Value:
True
Exceptions
- InsightsException
- Issues communicating with insights