Query

class Column()

---

class CoreQuery(api, parameters=None, metadata={}, title={})

CoreQuery is the main way through which to produce reports from data in Google Analytics.

The most important methods are:

• metrics and dimensions (both of which you can also pass as lists when creating the query)
• range and its shortcuts that have the granularity already set: hourly, daily, weekly, monthly, yearly, total
• filter to filter which rows are analyzed before running the query
• segment to filter down to a certain kind of session or user (as opposed to filter which works on individual rows of data)
• limit to ask for a subset of results
• sort to sort the query

CoreQuery is mostly immutable: wherever possible, methods return a new query rather than modifying the existing one, so for example this works as you'd expect it to:

base = profile.query('pageviews')
january = base.daily('2014-01-01', months=1).get()
february = base.daily('2014-02-01', months=1).get()

CoreQuery#daily(start=0, stop=0, months=None, days=None)

Return a new query that fetches metrics within a certain date range.

query.range('2014-01-01', '2014-06-30')

If you don't specify a stop argument, the date range will end today. If instead you meant to fetch just a single day's results, try:

query.range('2014-01-01', days=1)

More generally, you can specify that you'd like a certain number of days, starting from a certain date:

query.range('2014-01-01', months=3)
query.range('2014-01-01', days=28)

Note that if you don't specify a granularity (either through the interval method or through the hourly, daily, weekly, monthly or yearly shortcut methods) you will get only a single result, encompassing the entire date range, per metric.

Note: it is currently not possible to easily specify that you'd like to query the last last full week(s), month(s) et cetera. This will be added sometime in the future.

CoreQuery#dimensions(*dimensions)

Return a new query with additional dimensions.

query.dimensions('search term', 'search depth')

CoreQuery#filter(value=None, **selection)

Most of the actual functionality lives on the Column object and the all and any functions.

CoreQuery#get()

Run the query and return a Report.

This method transparently handles paginated results, so even for results that are larger than the maximum amount of rows the Google Analytics API will return in a single request, or larger than the amount of rows as specified through CoreQuery#step, get will leaf through all pages, concatenate the results and produce a single Report instance.

CoreQuery#hourly(start=0, stop=0, months=None, days=None)

Return a new query that fetches metrics within a certain date range.

query.range('2014-01-01', '2014-06-30')

If you don't specify a stop argument, the date range will end today. If instead you meant to fetch just a single day's results, try:

query.range('2014-01-01', days=1)

More generally, you can specify that you'd like a certain number of days, starting from a certain date:

query.range('2014-01-01', months=3)
query.range('2014-01-01', days=28)

Note that if you don't specify a granularity (either through the interval method or through the hourly, daily, weekly, monthly or yearly shortcut methods) you will get only a single result, encompassing the entire date range, per metric.

Note: it is currently not possible to easily specify that you'd like to query the last last full week(s), month(s) et cetera. This will be added sometime in the future.

CoreQuery#interval(granularity)

Note that if you don't specify a granularity (either through the interval method or through the hourly, daily, weekly, monthly or yearly shortcut methods) you will get only a single result, encompassing the entire date range, per metric.

CoreQuery#limit(*_range)

Return a new query, limited to a certain number of results.

# first 100
query.limit(100)
# 50 to 60
query.limit(50, 10)

Please note carefully that Google Analytics uses 1-indexing on its rows.

CoreQuery#metrics(*metrics)

Return a new query with additional metrics.

query.metrics('pageviews', 'page load time')

CoreQuery#monthly(start=0, stop=0, months=None, days=None)

Return a new query that fetches metrics within a certain date range.

query.range('2014-01-01', '2014-06-30')

If you don't specify a stop argument, the date range will end today. If instead you meant to fetch just a single day's results, try:

query.range('2014-01-01', days=1)

More generally, you can specify that you'd like a certain number of days, starting from a certain date:

query.range('2014-01-01', months=3)
query.range('2014-01-01', days=28)

Note that if you don't specify a granularity (either through the interval method or through the hourly, daily, weekly, monthly or yearly shortcut methods) you will get only a single result, encompassing the entire date range, per metric.

Note: it is currently not possible to easily specify that you'd like to query the last last full week(s), month(s) et cetera. This will be added sometime in the future.

CoreQuery#next()

Return a new query with a modified start_index. Mainly used internally to paginate through results.

CoreQuery#precision(precision)

For queries that should run faster, you may specify a lower precision, and for those that need to be more precise, a higher precision:

# faster queries
query.range('2014-01-01', '2014-01-31', precision=0)
query.range('2014-01-01', '2014-01-31', precision='FASTER')
# queries with the default level of precision (usually what you want)
query.range('2014-01-01', '2014-01-31')
query.range('2014-01-01', '2014-01-31', precision=1)
query.range('2014-01-01', '2014-01-31', precision='DEFAULT')
# queries that are more precise
query.range('2014-01-01', '2014-01-31', precision=2)
query.range('2014-01-01', '2014-01-31', precision='HIGHER_PRECISION')      

CoreQuery#range(start=0, stop=0, months=None, days=None)

Return a new query that fetches metrics within a certain date range.

query.range('2014-01-01', '2014-06-30')

If you don't specify a stop argument, the date range will end today. If instead you meant to fetch just a single day's results, try:

query.range('2014-01-01', days=1)

More generally, you can specify that you'd like a certain number of days, starting from a certain date:

query.range('2014-01-01', months=3)
query.range('2014-01-01', days=28)

Note that if you don't specify a granularity (either through the interval method or through the hourly, daily, weekly, monthly or yearly shortcut methods) you will get only a single result, encompassing the entire date range, per metric.

Note: it is currently not possible to easily specify that you'd like to query the last last full week(s), month(s) et cetera. This will be added sometime in the future.

CoreQuery#segment(value=None, scope=None, metric_scope=None, **selection)

Return a new query, limited to a segment of all users or sessions.

Accepts segment objects, filtered segment objects and segment names:

query.segment(account.segments['browser'])
query.segment('browser')
query.segment(account.segments['browser'].any('Chrome', 'Firefox'))

Segment can also accept a segment expression when you pass in a type argument. The type argument can be either users or sessions. This is pretty close to the metal.

# will be translated into `users::condition::perUser::ga:sessions>10`
query.segment('condition::perUser::ga:sessions>10', type='users')

See the Google Analytics dynamic segments documentation

You can also use the any, all, followed_by and immediately_followed_by functions in this module to chain together segments.

Everything about how segments get handled is still in flux. Feel free to propose ideas for a nicer interface on the GitHub issues page

CoreQuery#set(key=None, value=None, **kwargs)

set is a way to add raw properties to the request, for features that this module does not support or supports incompletely. For convenience's sake, it will serialize Column objects but will leave any other kind of value alone.

CoreQuery#sort(*columns, **options)

Return a new query which will produce results sorted by one or more metrics or dimensions. You may use plain strings for the columns, or actual Column, Metric and Dimension objects.

Add a minus in front of the metric (either the string or the object) to sort in descending order.

# sort using strings
query.sort('pageviews', '-device type')
# alternatively, ask for a descending sort in a keyword argument
query.sort('pageviews', descending=True)

# sort using metric, dimension or column objects
pageviews = profile.core.metrics['pageviews']
query.sort(-pageviews)

CoreQuery#step(maximum)

Return a new query with a maximum amount of results to be returned in any one request, without implying that we should stop fetching beyond that limit (unlike CoreQuery#limit.)

Useful in debugging pagination functionality.

Perhaps also useful when you want to be able to decide whether to continue fetching data, based on the data you've already received.

CoreQuery#total(start=0, stop=0, months=None, days=None)

Return a new query that fetches metrics within a certain date range.

query.range('2014-01-01', '2014-06-30')

If you don't specify a stop argument, the date range will end today. If instead you meant to fetch just a single day's results, try:

query.range('2014-01-01', days=1)

More generally, you can specify that you'd like a certain number of days, starting from a certain date:

query.range('2014-01-01', months=3)
query.range('2014-01-01', days=28)

Note that if you don't specify a granularity (either through the interval method or through the hourly, daily, weekly, monthly or yearly shortcut methods) you will get only a single result, encompassing the entire date range, per metric.

Note: it is currently not possible to easily specify that you'd like to query the last last full week(s), month(s) et cetera. This will be added sometime in the future.

CoreQuery#weekly(start=0, stop=0, months=None, days=None)

Return a new query that fetches metrics within a certain date range.

query.range('2014-01-01', '2014-06-30')

If you don't specify a stop argument, the date range will end today. If instead you meant to fetch just a single day's results, try:

query.range('2014-01-01', days=1)

More generally, you can specify that you'd like a certain number of days, starting from a certain date:

query.range('2014-01-01', months=3)
query.range('2014-01-01', days=28)

Note that if you don't specify a granularity (either through the interval method or through the hourly, daily, weekly, monthly or yearly shortcut methods) you will get only a single result, encompassing the entire date range, per metric.

Note: it is currently not possible to easily specify that you'd like to query the last last full week(s), month(s) et cetera. This will be added sometime in the future.

CoreQuery#yearly(start=0, stop=0, months=None, days=None)

Return a new query that fetches metrics within a certain date range.

query.range('2014-01-01', '2014-06-30')

If you don't specify a stop argument, the date range will end today. If instead you meant to fetch just a single day's results, try:

query.range('2014-01-01', days=1)

More generally, you can specify that you'd like a certain number of days, starting from a certain date:

query.range('2014-01-01', months=3)
query.range('2014-01-01', days=28)

Note that if you don't specify a granularity (either through the interval method or through the hourly, daily, weekly, monthly or yearly shortcut methods) you will get only a single result, encompassing the entire date range, per metric.

Note: it is currently not possible to easily specify that you'd like to query the last last full week(s), month(s) et cetera. This will be added sometime in the future.

---

class Query()

Return a query for certain metrics and dimensions.

# pageviews (metric) as a function of geographical region
profile.core.query('pageviews', 'region')
# pageviews as a function of browser
profile.core.query(['pageviews'], ['browser'])

The returned query can then be further refined using all methods available on the CoreQuery object, such as limit, sort, segment and so on.

Metrics and dimensions may be either strings (the column id or the human-readable column name) or Metric or Dimension objects.

Metrics and dimensions specified as a string are not case-sensitive.

profile.query('PAGEVIEWS')

If specifying only a single metric or dimension, you can but are not required to wrap it in a list.

Query#dimensions(*dimensions)

Return a new query with additional dimensions.

query.dimensions('search term', 'search depth')

Query#filter(value=None, **selection)

Most of the actual functionality lives on the Column object and the all and any functions.

Query#metrics(*metrics)

Return a new query with additional metrics.

query.metrics('pageviews', 'page load time')

Query#set(key=None, value=None, **kwargs)

set is a way to add raw properties to the request, for features that this module does not support or supports incompletely. For convenience's sake, it will serialize Column objects but will leave any other kind of value alone.

Query#sort(*columns, **options)

Return a new query which will produce results sorted by one or more metrics or dimensions. You may use plain strings for the columns, or actual Column, Metric and Dimension objects.

Add a minus in front of the metric (either the string or the object) to sort in descending order.

# sort using strings
query.sort('pageviews', '-device type')
# alternatively, ask for a descending sort in a keyword argument
query.sort('pageviews', descending=True)

# sort using metric, dimension or column objects
pageviews = profile.core.metrics['pageviews']
query.sort(-pageviews)

---

class RealTimeQuery()

A query against the Google Analytics Real Time API.

Note: brand new! Please test and submit any issues to GitHub.

RealTimeQuery#dimensions(*dimensions)

Return a new query with additional dimensions.

query.dimensions('search term', 'search depth')

RealTimeQuery#filter(value=None, **selection)

Most of the actual functionality lives on the Column object and the all and any functions.

RealTimeQuery#limit(maximum)

Return a new query, limited to a certain number of results.

Unlike core reporting queries, you cannot specify a starting point for live queries, just the maximum results returned.

# first 50
query.limit(50)

RealTimeQuery#metrics(*metrics)

Return a new query with additional metrics.

query.metrics('pageviews', 'page load time')

RealTimeQuery#set(key=None, value=None, **kwargs)

set is a way to add raw properties to the request, for features that this module does not support or supports incompletely. For convenience's sake, it will serialize Column objects but will leave any other kind of value alone.

RealTimeQuery#sort(*columns, **options)

Return a new query which will produce results sorted by one or more metrics or dimensions. You may use plain strings for the columns, or actual Column, Metric and Dimension objects.

Add a minus in front of the metric (either the string or the object) to sort in descending order.

# sort using strings
query.sort('pageviews', '-device type')
# alternatively, ask for a descending sort in a keyword argument
query.sort('pageviews', descending=True)

# sort using metric, dimension or column objects
pageviews = profile.core.metrics['pageviews']
query.sort(-pageviews)

---

class Report()

Executing a query will return a report, which contains the requested data.

Queries are executed and turned into a report lazily, whenever data is requested. You can also explicitly generate a report from a query by using the Query#get method.

# will return a query object
profile.core.query.metrics('pageviews').range('yesterday')
# will return a report object
profile.core.query.metrics('pageviews').range('yesterday').get()
# will generate a report object and return its rows -- these
# two are equivalent
profile.core.query.metrics('pageviews').range('yesterday').rows
profile.core.query.metrics('pageviews').range('yesterday').get().rows

You can access the data in a Report object both rowwise and columnwise.

report = query.metrics('pageviews', 'sessions').range('yesterday')
# first ten rows
report.rows[:10]
# work with just session data points
report['sessions'][:10]
report.rows[:10]['sessions']

For simple data structures, there are also some shortcuts.

These shortcuts are available both directly on Report objects and lazily-loaded via Query objects.

# reports with a single value
query = profile.core.query('pageviews').range('yesterday')
report = query.get()
assert query.value == report.value
# reports with a single metric
profile.core.query('pageviews').daily('yesterday', days=-10).values
# reports with a single result
query = profile.core.query(['pageviews', 'sessions']).range('yesterday')
assert query.first == query.last

---

class Segment()

---

function deepcopy(x, memo=[], _nil=None)

Deep copy operation on arbitrary Python objects.

See the module's doc string for more info.

---

function describe(profile, description)

Generate a query by describing it as a series of actions and parameters to those actions. These map directly to Query methods and arguments to those methods.

This is an alternative to the chaining interface. Mostly useful if you'd like to put your queries in a file, rather than in Python code.

---

class partial()

partial(func, *args, **keywords) - new function with partial application of the given arguments and keywords.

partial#

x.init(...) initializes x; see help(type(x)) for signature

partial#

tuple of arguments to future partial calls

partial#

function object to use in future partial calls

partial#

dictionary of keyword arguments to future partial calls

---

function refine(query, description)

Refine a query from a dictionary of parameters that describes it. See describe for more information.

---

function select(source, selection)