Query API

The Localytics Query API is an interface to the Localytics analytics platform. It provides access to the same powerful query engine as used by the Localytics Dashboard.

Overview

The Query API is a RESTful, hypermedia-guided JSON web service. Flexibility and standards-compliance were emphasized at each step of the design, so that integrating it is a snap.

Protocol

The root URL for the Localytics API is https://api.localytics.com/v1/.
For maximum security, using the API over unencrypted HTTP is not supported.

The Localytics API authenticates users with a combination of an API key and an API secret. These parameters may be passed to the API in one of two ways:

  • HTTP Basic authentication, as specified in RFC 2617. This is commonly known as plain or "gray box" authentication and is universally supported by HTTP clients. The API key is passed as the HTTP Basic username and the API secret is passed as the HTTP Basic password.
  • The key and secret can be passed directly as the api_key and api_secret parameters. This will override any values passed over HTTP Basic auth.

All responses from the Localytics API are by default provided in JSON format, using the Unicode UTF-8 text encoding.

Query results are also available in CSV format by specifying text/csv in the Accept request header.

Responses and Errors

JSON output objects from the Localytics API are returned with a Content-type header of application/vnd.localytics.v1+hal+json, extended to identify the data type. Examples:

  • application/vnd.localytics.v1+hal+json;type=App
  • application/vnd.localytics.v1+hal+json;type=ResultSet

In order to allow usage from client-side web applications, the Localytics API enables Cross-origin Resource Sharing, though users should take care not to expose their API credentials on public websites.

The Localytics API uses standard HTTP response codes to communicate success and error conditions to the client:

  • 200 OK - success
  • 401 Unauthorized - authentication is required but missing
  • 403 Forbidden - authorization failed
  • 404 Not Found - the requested resource is not found
  • 406 Not Acceptable - the response format in the Accept request header is not supported
  • 422 Unprocessable Entity - error in user input
  • 500 Internal Server Error - error in Localytics API
  • 502 Bad Gateway - error connecting to back-end services

Error responses (4xx and 5xx) consist of a JSON object, containing an 'error' field describing the error: 

{
  "error": "message describing what happened"
}

Limits

The API enforces the following rate limits per API key on usage:

  • Allows one simultaneous request
  • 60 requests/minute
  • 150 requests/hour
  • 1000 requests/day

The API will return a 429 response code when a rate limit is exceeded. You should reduce your rate of requests and retry throttled requests after the specified time.

Wrapped Responses and JSONP

In order to accomodate as many clients as possible, the Localytics API has several features to change the response format.

The wrap_response parameter can be sent in cases where non-200 OK responses are undesirable. The response will be sent with a 200 OK status and will be wrapped in an envelope object, which encodes the response status and status message as JSON data.

The response will take on the following structure:

{
  "response": { ... },    // original response
  "status": 200,          // original status code
  "status_message": "OK"  // description for original status code
}

The Localytics API supports the callback parameter to implement JSONP in a way that is compatible with e.g., jQuery. JSONP responses are always wrapped in a response envelope as above, and are sent as media type application/javascript.

Hypermedia Clients

The Localytics API is a hypermedia API, following the Hypertext Application Language (HAL) specification.

A hypermedia API, along with each response, sends a list of hyperlinks representing everything which can be done to/with/from the returned object. This means that properly-designed hypermedia adapters can connect to and use the Localytics API with no configuration other than URL and credentials.

Alongside cURL examples for simple endpoint-based API usage, example code for hypermedia clients is provided using the HyperResource library for Ruby.

Analytics

Concepts

In order to use an analytics API to its maximum potential, it is useful to agree on terminology. The Localytics API, and the backend services which power it, are organized around metrics, dimensions, and conditions. In a nutshell, rows are selected according to conditions, then grouped by dimensions, and finally tallied by metric.

Metrics

Metrics are the sums or counts which form the basis of your query.

The Localytics API supports the following metrics:

sessions
Counts app sessions.
users
Counts unique users.
occurrences
Counts occurrences of an event.
sessions_per_event
Counts sessions which have experienced an event.
median_session_length
Median length of sessions, in seconds. Cannot be combined with other metrics or dimensions.
average_session_length
Average length of sessions, in seconds. Cannot be combined with other metrics.
profiles
Counts unique profiles. Cannot be combined with non-profile-related metrics or dimensions.
avg(a:attribute_name)
Computes the average value for the specified numeric attribute.
min(a:attribute_name)
Returns the smallest value for the specified numeric attribute.
max(a:attribute_name)
Returns the largest value for the specified numeric attribute.
sum(a:attribute_name)
Computes the sum value for the specified numeric attribute.

Dimensions

Dimensions are categories which can be used to break down data into groups. Including a dimension in a query causes the query output to be grouped by the values of this dimension -- or in analytics terminology, to be "split" by the dimension.

The Localytics API supports the following dimensions. All dates and times are returned in the app's configured time zone, in ISO 8601 format.

event_name
Event name, from events defined within your app.
a:attribute_name
Custom attribute name. Must begin with 'a:'. Must be used in conjunction with an event name condition (e.g. conditions: {event_name: "some_event"}).
bucket(n:attribute_name,min,max,number_of_buckets)
Bucketed numeric attributes. Expects an expression with the format bucket(n:attribute_name,0,1000,10). Groups data into sets of buckets of equal size. (e.g. 0-100, 100-200, etc..). Values must be numeric.
c:custom_dimension_name
Custom dimension name. Must begin with 'c:' if it conflicts with an existing metric or dimension name, otherwise this prefix is optional.
day
Date, precise to the day, e.g. 2013-07-21.
week
Date, precise to the week.
month
Date, precise to the month.
hour
Date, precise to the hour, e.g. 2013-07-21T13:00.
hour_of_day
Hour of day. 00:00 to 23:00.
day_of_week
Day of week. 1 (Sunday) to 7 (Saturday).
birth_day
Date of first usage for a session or user, precise to the day. See Cohort and Retention for usage examples.
birth_week
Date of first usage for a session or user, precise to the week. See Cohort and Retention for usage examples.
birth_month
Date of first usage for a session or user, precise to the month. See Cohort and Retention for usage examples.
new_device
"t" for a first-time user or session, "f" otherwise.
country
Two-letter country code.
carrier
E.g. "AT&T", "Comcast Cable", "Bt Public Internet Service".
device_make
E.g. "Apple, Inc.", "Google, Inc.".
device_model
E.g. "MacIntel", "iPhone", "BlackBerry", "Win32".
platform
E.g. "BlackBerry", "Win64", "iPad".
os_version
E.g. "OS X 10.8", "Windows Vista", "BlackBerry 7", "Android 2.3.6".
app_id
Your application ID.
app_version
Your application version.
client_library
Localytics client library version, e.g. "html5_2.4".
session_length
Range of session lengths. See Session Length Range for usage example.
session_interval
Time since previous session. See Session Interval for usage example.
visit_number
Number of visits by a user. See Loyalty for usage example.
average_clv
Average customer lifetime value (CLV).
total_clv
Total customer lifetime value (CLV).
average_monthly_value
Average customer monthly value.
revenue
Overall revenue.
customers
Number of customers.
revenue_per_customer
Average revenue per customer.
transactions
Number of transactions.
transactions_per_customer
Average number of transactions per customer.
revenue_per_transaction
Average revenue per transaction.

Additionally, the following dimensions are available for performing analytics queries against one or more profile databases.

profiledb_id
Your profile database ID.
profile_attribute_key
The name of a profile attribute, e.g. "Favorite Team", "Gender"
profile_attribute_type
The data type of a profile attribute. One of "string", "number", or "date".
profile_value_string
The value of profile attributes of type "string".
profile_value_number
The value of profile attributes of type "number".
profile_value_date
The value of a profile attributes of type "date".
profile_attribute_value
Regardless of data type, the value of a profile attribute cast as string.

Conditions

Conditions are requirements which are applied to one or more of the dimensions used in the query. Each dimension appearing in a query's list of conditions must also appear in that query's list of dimensions.

Conditions are specified in a hash, keyed by dimension name.

The following operators are available for use in conditions:

value
Dimension equals given value. Equivalent to ["in", value1].
["in", value1, value2, ...]
Dimension equals one of the given values.
["not_in", value1, value2, ...]
Dimension equals none of the given values.
["between", value1, value2]
Dimension falls between the two given values.
["is_null"]
Dimension IS NULL.
["is_not_null"]
Dimension IS NOT NULL.
["==", value]
Dimension equals value.
["!=", value]
Dimension does not equal value.
["<", value]
Dimension is less than value.
["<=", value]
Dimension is less than or equal to value.
[">", value]
Dimension is greater than value.
[">=", value]
Dimension is greater than or equal to value.

Query API V1 Reference

Root

Returns
Root
Endpoint
GET /v1
Path
(root)
Links
apps, app, query

Returns the API hypermedia root resource. Not very useful to traditional clients. 

api = HyperResource.new(root: 'https://api.localytics.com',
                        auth: {basic: [API_KEY, API_SECRET)]},
                        headers: {'Accept' => 'application/vnd.localytics.v1+hal+json'})

root = api.get
  
curl -H "Accept: application/vnd.localytics.v1+hal+json" \
     -u "$API_KEY:$API_SECRET" \
     -G "https://api.localytics.com/v1/"
  
Content-type: application/vnd.localytics.v1+hal+json;type=Root

{
  "service": "Localytics API",
  "versions": [ 1 ],
  "documentation_path": "/docs",
  "_links": {
    "self": {
      "href": "/v1"
    },
    "apps": {
      "href": "/v1/apps"
    },
    "app": {
      "templated": true,
      "href": "/v1/apps/{app_id}"
    },
    "query": {
      "templated": true,
      "href": "/v1/query{?app_id,metrics,dimensions,conditions,limit,order,days,comment,translate}"
    }
  }
}

Apps

Show App

Returns
App
Endpoint
GET /v1/apps/:app_id
path
root.links.app
args
app_id
links
apps, query

Returns a object representing an app, including name, id, creation time, and usage stats for the last month (starting at begin_date and ending before end_date). 

app = root.app(app_id: APP_ID).get
  
curl -H "Accept: application/vnd.localytics.v1+hal+json" \
     -u "$API_KEY:$API_SECRET" \
     -G "https://api.localytics.com/v1/apps/$APP_ID"
  
Content-type: application/vnd.localytics.v1+hal+json;type=App

{
  "name": "App Name",
  "app_id": "...",
  "stats": {
    "sessions": 52291,
    "closes": 46357,
    "users": 7008,
    "events": 865290,
    "data_points": 963938,
    "platforms": ["HTML5"],
    "client_libraries": ["html5_2.6", "html5_2.5", "html5_2.4"],
    "begin_date": "2013-08-10",
    "end_date": "2013-09-10"
  },
  "icon_url": "https://example.com/app-icon.png",
  "custom_dimensions": {
    "custom_0_dimension": "Blood Type",
    "custom_1_dimension": "Moon Phase"
  },
  "created_at": "2012-04-10T04:07:13Z",
  "_links": {
    "self": { "href": "/v1/apps/..." },
    "apps": { "href": "/v1/apps" },
    "query": {
      "templated": true,
      "href": "/v1/apps/.../query{?app_id,metrics,dimensions,conditions,limit,order,days,comment,translate}"
    },
    "root": { "href": "/v1" }
  }
}

Show Apps

Returns
AppSet
Endpoint
GET /v1/apps
Path
root.apps

Returns the list of apps which you have permission to view. Each app in the response is data type App format listed above, and apps appear under ['_embedded']['apps'] in the response. 

app_set = root.apps.get
apps = app_set.apps
  
curl -H "Accept: application/vnd.localytics.v1+hal+json" \
     -u "$API_KEY:$API_SECRET" \
     -G "https://api.localytics.com/v1/apps/"
  
Content-type: application/vnd.localytics.v1+hal+json;type=AppSet

{
  "_embedded": {
    "apps": [
      {
        "name": "App Name",
        "app_id": "...",
        "created_at": "2012-04-10T04:07:13Z",
        "_links": {
          "self": { "href": "/v1/apps/..." },
          "apps": { "href": "/v1/apps" },
          "query": {
            "templated": true,
            "href": "/v1/apps/.../query{?app_id,metrics,dimensions,conditions,limit,order,days,comment,translate}"
          },
          "root": { "href": "/v1" }
        }
      },
      ...
    ]
  },
  "_links": {
    "self": { "href": "/v1/apps" },
    "root": { "href": "/v1" }
  }
}

Show App Attributes

Returns
AttributeSet
Endpoint
GET /v1/apps/:app_id/attributes
GET /v1/attributes
Path
app.attributes, root.attibutes

Returns the list of attributes in use in this application, split by event name. Also returns a list of all currently known high-cardinality attributes; that is, attribute keys which have more than 50 possible values. (Some high-cardinality attributes may be missing from this list.) 

attrs = app.links.attributes.get
  
curl -H "Accept: application/vnd.localytics.v1+hal+json" \
     -u "$API_KEY:$API_SECRET" \
     -G "https://api.localytics.com/v1/apps/$APP_ID/attributes"
  
Content-type: application/vnd.localytics.v1+hal+json;type=AttributeSet

{
  "events": [
    {
      "event_name": "Clicked Link",
      "attributes": [ "link_text", "link_target", "link_placement" ],
      "high_cardinality_attributes": [ "link_text" ]
    },
    {
      "event_name": "Added to Cart",
      "attributes": [ "item_name", "item_id" ]
      "high_cardinality_attributes": [ "item_name", "item_id" ]
    },
    ...
  ],
  "_links": {
    "app": { "href": "/v1/apps/..." },
    "root": { "href": "/v1" }
  }
}

Queries

Query

Returns
ResultSet
Endpoint
GET|POST /v1/query
Path
root.query app.query
Args
app_id metrics dimensions conditions order limit days comment translate
Links
app

Queries the data for the given app, and returns the results.

Either GET or POST may be used on this endpoint.

Some request parameters may be passed in either as strings (e.g., comma-separated lists or JSON-encoded hashes) or as structured data. Structured data over GET requests is expected in the format followed by jQuery.param and Ruby on Rails. Structured data in POST requests may be provided URL-encoded as mentioned, or directly as JSON data with the Content-type: application/json header.

When using a hypermedia client, passing structured data in string format is recommended.

app_id
Comma-Separated String or Array of Strings.
IDs of the applications to query.
metrics
Comma-Separated String or Array of Strings.
List of metrics.
dimensions
Comma-Separated String or Array of Strings.
List of dimensions.
conditions
Hash or String (JSON-encoded Hash).
Query conditions, keyed on metric or dimension name.
days
String or Integer, 0-396.
Number of days in the past over which to query. days is 0-based, so the current day is always included in the query (i.e., days=2&dimensions=day will yield three results). Data for the current day may be incomplete.
To specify a date condition manually, do not pass the days parameter, but instead pass a condition on the day dimension:
conditions: {day: ['between', '2013-04-01', '2013-04-15']}
The date range may be at most 396 days (13 months) long.
Default 30, when neither days nor a day condition is provided.
order
Comma-Separated String, or Array of Strings.
Sort order for the query results. One or more metrics or dimensions can appear in the sort order. By default, metrics are sorted descending (highest-first), and dimensions are sorted ascending (lowest-first). To specify a different sort direction, prepend a '+' to the metric/dimension name for ascending order, or '-' for descending order.
If sort order is not specified, the default is to sort by dimensions, then metrics.
limit
String or Integer, 1-20000.
Maximum number of records to return. Default 20000.
comment
String.
Optional comment to be returned in the ResultSet.
translate
Hash or String (JSON-encoded Hash).
Optional list of "translate_this": "to_this" pairs. Keys in the results will be translated according to the given translation hash.
profiledb_id
Comma-Separated String, Integer or Array of Integers.
For profile queries, specify the IDs of one or more profile databases from which to query. This parameter should be used instead of app_id for profile queries.
sampling_ratio
Number between 0 and 1.
For faster results, you can optionally request your query to be sampled by a given ratio. Unless requested, queries default to a sampling ratio of 1.0 (unsampled). A smaller ratio should return faster, less accurate results. 
Content-type: application/vnd.localytics.v1+hal+json;type=ResultSet

{
  "results": [ ... ],
  "app_id": "app-id-here",
  "comment": "sample-comment-here",
  "created_at": "2013-03-14T12:22:51Z",
  "expires_at": "2013-03-14T12:27:51Z",
  "query": { ... },
  "_links": { ... }
}
results
Array of result tuples. Each tuple will contain an integer result for each metric and dimension in the query.
app_id
ID of the app being queried.
profiledb_id
ID of the profile database(s) being queried, if any.
comment
Comment passed in with the query, if any. null otherwise.
created_at
Date and time at which this query was performed.
expires_at
Date and time until which this query's results will be cached.
truncated
true if the query resulted in more than the maximum limit of results, false otherwise. Results after the maximim limit will not be returned.
query
A copy of the query arguments originally passed by the client. This object can be reused as input, to repeat a query, or as an aid to debugging custom queries.

Query results are also available in CSV format. Add the Accept: text/csv header to the request instead of the usual Accept: application/vnd.localytics.v1+hal+json to receive comma-separated results. The first row contains header names and subsequent rows contain result data; no other metadata is returned.

Examples

Basic Usage Queries

Users by Day

Query app users by day:

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'users',
  dimensions: 'day',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=users' \
     --data 'dimensions=day' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "day": "2015-01-01",
      "users": 15744
    },
    {
      "day": "2015-01-02",
      "users": 14022
    },
    {
      "day": "2015-01-03",
      "users": 14165
    },
    {
      "day": "2015-01-04",
      "users": 14372
    },
    {
      "day": "2015-01-05",
      "users": 15933
    },
    {
      "day": "2015-01-06",
      "users": 14424
    },
    {
      "day": "2015-01-07",
      "users": 15981
    },
    {
      "day": "2015-01-08",
      "users": 19821
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:26:37Z",
  "expires_at": "2015-09-16T08:50:11Z",
  "truncated": false,
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "day"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "-users"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=day&limit=50000&metrics%5B%5D=users&order%5B%5D=%2Bday&order%5B%5D=-users&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Users by Daypart

Query users by daypart:

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'users',
  dimensions: 'hour_of_day',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=users' \
     --data 'dimensions=hour_of_day' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "users": 4119,
      "hour_of_day": "00:00"
    },
    {
      "users": 2825,
      "hour_of_day": "01:00"
    },
    {
      "users": 1864,
      "hour_of_day": "02:00"
    },
    {
      "users": 1147,
      "hour_of_day": "03:00"
    },
    {
      "users": 768,
      "hour_of_day": "04:00"
    },
    {
      "users": 695,
      "hour_of_day": "05:00"
    },
    {
      "users": 927,
      "hour_of_day": "06:00"
    },
    {
      "users": 1694,
      "hour_of_day": "07:00"
    },
    {
      "users": 3649,
      "hour_of_day": "08:00"
    },
    {
      "users": 4377,
      "hour_of_day": "09:00"
    },
    {
      "users": 6008,
      "hour_of_day": "10:00"
    },
    {
      "users": 10604,
      "hour_of_day": "11:00"
    },
    {
      "users": 11400,
      "hour_of_day": "12:00"
    },
    {
      "users": 8785,
      "hour_of_day": "13:00"
    },
    {
      "users": 7505,
      "hour_of_day": "14:00"
    },
    {
      "users": 6859,
      "hour_of_day": "15:00"
    },
    {
      "users": 6464,
      "hour_of_day": "16:00"
    },
    {
      "users": 6157,
      "hour_of_day": "17:00"
    },
    {
      "users": 6342,
      "hour_of_day": "18:00"
    },
    {
      "users": 7118,
      "hour_of_day": "19:00"
    },
    {
      "users": 12833,
      "hour_of_day": "20:00"
    },
    {
      "users": 10075,
      "hour_of_day": "21:00"
    },
    {
      "users": 8411,
      "hour_of_day": "22:00"
    },
    {
      "users": 6493,
      "hour_of_day": "23:00"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:28:50Z",
  "expires_at": "2015-09-16T15:09:52Z",
  "truncated": false,
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "hour_of_day"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+hour_of_day",
      "-users"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=hour_of_day&limit=50000&metrics%5B%5D=users&order%5B%5D=%2Bhour_of_day&order%5B%5D=-users&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

New vs. Returning

Query app users by day, and split by new users vs. returning users (new device vs. old device):

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'users',
  dimensions: 'day, new_device',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=users' \
     --data 'dimensions=day,new_device' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "day": "2015-01-01",
      "new_device": "f",
      "users": 11845
    },
    {
      "day": "2015-01-01",
      "new_device": "t",
      "users": 4833
    },
    {
      "day": "2015-01-02",
      "new_device": "f",
      "users": 11005
    },
    {
      "day": "2015-01-02",
      "new_device": "t",
      "users": 3538
    },
    {
      "day": "2015-01-03",
      "new_device": "f",
      "users": 11547
    },
    {
      "day": "2015-01-03",
      "new_device": "t",
      "users": 3118
    },
    {
      "day": "2015-01-04",
      "new_device": "f",
      "users": 12056
    },
    {
      "day": "2015-01-04",
      "new_device": "t",
      "users": 2766
    },
    {
      "day": "2015-01-05",
      "new_device": "f",
      "users": 13486
    },
    {
      "day": "2015-01-05",
      "new_device": "t",
      "users": 2921
    },
    {
      "day": "2015-01-06",
      "new_device": "f",
      "users": 12623
    },
    {
      "day": "2015-01-06",
      "new_device": "t",
      "users": 2166
    },
    {
      "day": "2015-01-07",
      "new_device": "f",
      "users": 13917
    },
    {
      "day": "2015-01-07",
      "new_device": "t",
      "users": 2449
    },
    {
      "day": "2015-01-08",
      "new_device": "f",
      "users": 17388
    },
    {
      "day": "2015-01-08",
      "new_device": "t",
      "users": 2868
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:28:03Z",
  "expires_at": "2015-09-15T22:56:50Z",
  "truncated": false,
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "day",
      "new_device"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "+new_device",
      "-users"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=day&dimensions%5B%5D=new_device&limit=50000&metrics%5B%5D=users&order%5B%5D=%2Bday&order%5B%5D=%2Bnew_device&order%5B%5D=-users&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Birth-month Cohort

Query users by day, split by user birth month:

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'users',
  dimensions: 'day, birth_month',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=users' \
     --data 'dimensions=day,birth_month' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "birth_month": "2014-09-01",
      "day": "2015-01-01",
      "users": 142
    },
    {
      "birth_month": "2014-10-01",
      "day": "2015-01-01",
      "users": 5506
    },
    {
      "birth_month": "2014-11-01",
      "day": "2015-01-01",
      "users": 3875
    },
    {
      "birth_month": "2014-12-01",
      "day": "2015-01-01",
      "users": 4784
    },
    {
      "birth_month": "2015-01-01",
      "day": "2015-01-01",
      "users": 1437
    },
    {
      "birth_month": "2014-09-01",
      "day": "2015-01-02",
      "users": 125
    },
    {
      "birth_month": "2014-10-01",
      "day": "2015-01-02",
      "users": 4733
    },
    {
      "birth_month": "2014-11-01",
      "day": "2015-01-02",
      "users": 3388
    },
    {
      "birth_month": "2014-12-01",
      "day": "2015-01-02",
      "users": 4188
    },
    {
      "birth_month": "2015-01-01",
      "day": "2015-01-02",
      "users": 1588
    },
    {
      "birth_month": "2014-09-01",
      "day": "2015-01-03",
      "users": 135
    },
    {
      "birth_month": "2014-10-01",
      "day": "2015-01-03",
      "users": 4739
    },
    {
      "birth_month": "2014-11-01",
      "day": "2015-01-03",
      "users": 3493
    },
    {
      "birth_month": "2014-12-01",
      "day": "2015-01-03",
      "users": 4127
    },
    {
      "birth_month": "2015-01-01",
      "day": "2015-01-03",
      "users": 1671
    },
    {
      "birth_month": "2014-09-01",
      "day": "2015-01-04",
      "users": 122
    },
    {
      "birth_month": "2014-10-01",
      "day": "2015-01-04",
      "users": 4870
    },
    {
      "birth_month": "2014-11-01",
      "day": "2015-01-04",
      "users": 3449
    },
    {
      "birth_month": "2014-12-01",
      "day": "2015-01-04",
      "users": 3998
    },
    {
      "birth_month": "2015-01-01",
      "day": "2015-01-04",
      "users": 1933
    },
    {
      "birth_month": "2014-09-01",
      "day": "2015-01-05",
      "users": 134
    },
    {
      "birth_month": "2014-10-01",
      "day": "2015-01-05",
      "users": 5318
    },
    {
      "birth_month": "2014-11-01",
      "day": "2015-01-05",
      "users": 3767
    },
    {
      "birth_month": "2014-12-01",
      "day": "2015-01-05",
      "users": 4270
    },
    {
      "birth_month": "2015-01-01",
      "day": "2015-01-05",
      "users": 2444
    },
    {
      "birth_month": "2014-09-01",
      "day": "2015-01-06",
      "users": 139
    },
    {
      "birth_month": "2014-10-01",
      "day": "2015-01-06",
      "users": 4716
    },
    {
      "birth_month": "2014-11-01",
      "day": "2015-01-06",
      "users": 3315
    },
    {
      "birth_month": "2014-12-01",
      "day": "2015-01-06",
      "users": 3980
    },
    {
      "birth_month": "2015-01-01",
      "day": "2015-01-06",
      "users": 2274
    },
    {
      "birth_month": "2014-09-01",
      "day": "2015-01-07",
      "users": 136
    },
    {
      "birth_month": "2014-10-01",
      "day": "2015-01-07",
      "users": 5198
    },
    {
      "birth_month": "2014-11-01",
      "day": "2015-01-07",
      "users": 3810
    },
    {
      "birth_month": "2014-12-01",
      "day": "2015-01-07",
      "users": 4193
    },
    {
      "birth_month": "2015-01-01",
      "day": "2015-01-07",
      "users": 2644
    },
    {
      "birth_month": "2014-09-01",
      "day": "2015-01-08",
      "users": 165
    },
    {
      "birth_month": "2014-10-01",
      "day": "2015-01-08",
      "users": 6652
    },
    {
      "birth_month": "2014-11-01",
      "day": "2015-01-08",
      "users": 4686
    },
    {
      "birth_month": "2014-12-01",
      "day": "2015-01-08",
      "users": 5076
    },
    {
      "birth_month": "2015-01-01",
      "day": "2015-01-08",
      "users": 3242
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:30:29Z",
  "expires_at": "2015-09-16T05:17:55Z",
  "truncated": false,
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "day",
      "birth_month"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "+birth_month",
      "-users"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=day&dimensions%5B%5D=birth_month&limit=50000&metrics%5B%5D=users&order%5B%5D=%2Bday&order%5B%5D=%2Bbirth_month&order%5B%5D=-users&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Engagement Queries

User Retention Over Time

Look at user retention over time by selecting the 'users' metric, and 'birth_day', 'birth_week', or 'birth_month' dimension.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'users',
  dimensions: 'week, birth_week',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=users' \
     --data 'dimensions=week,birth_week' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "birth_week": "2014-09-08",
      "users": 1,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-09-29",
      "users": 1640,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-10-06",
      "users": 2988,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-10-13",
      "users": 4747,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-10-20",
      "users": 2443,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-10-27",
      "users": 1972,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-11-03",
      "users": 2133,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-11-10",
      "users": 2038,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-11-17",
      "users": 2038,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-11-24",
      "users": 2490,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-12-01",
      "users": 2061,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-12-08",
      "users": 2050,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-12-15",
      "users": 2092,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-12-22",
      "users": 2676,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-12-29",
      "users": 7187,
      "week": "2014-12-29"
    },
    {
      "birth_week": "2014-09-08",
      "users": 1,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-09-29",
      "users": 1891,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-10-06",
      "users": 3216,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-10-13",
      "users": 5088,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-10-20",
      "users": 2628,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-10-27",
      "users": 2271,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-11-03",
      "users": 2292,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-11-10",
      "users": 2229,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-11-17",
      "users": 2221,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-11-24",
      "users": 2664,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-12-01",
      "users": 2183,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-12-08",
      "users": 2275,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-12-15",
      "users": 2234,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-12-22",
      "users": 2752,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2014-12-29",
      "users": 4558,
      "week": "2015-01-05"
    },
    {
      "birth_week": "2015-01-05",
      "users": 5066,
      "week": "2015-01-05"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:31:00Z",
  "expires_at": "2015-09-15T16:05:50Z",
  "truncated": false,
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "week",
      "birth_week"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+week",
      "+birth_week",
      "-users"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=week&dimensions%5B%5D=birth_week&limit=50000&metrics%5B%5D=users&order%5B%5D=%2Bweek&order%5B%5D=%2Bbirth_week&order%5B%5D=-users&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Users by Session Length

See the range of session lengths over the past N days by using the session_length dimension and the users metric. Results will carry a session_length_description field with a textual description of each session length range.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'users',
  dimensions: 'session_length',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=users' \
     --data 'dimensions=session_length' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "users": 5165,
      "session_length": 1,
      "session_length_description": "0 to 10 seconds"
    },
    {
      "users": 4313,
      "session_length": 2,
      "session_length_description": "11 to 30 seconds"
    },
    {
      "users": 5152,
      "session_length": 3,
      "session_length_description": "31 to 60 seconds"
    },
    {
      "users": 9011,
      "session_length": 4,
      "session_length_description": "1 to 3 minutes"
    },
    {
      "users": 7657,
      "session_length": 5,
      "session_length_description": "3 to 10 minutes"
    },
    {
      "users": 2285,
      "session_length": 6,
      "session_length_description": "10 to 30 minutes"
    },
    {
      "users": 463,
      "session_length": 7,
      "session_length_description": "30 to 60 minutes"
    },
    {
      "users": 604,
      "session_length": 8,
      "session_length_description": "1 hour or more"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:31:26Z",
  "expires_at": "2015-09-16T21:45:59Z",
  "truncated": false,
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "session_length"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+session_length",
      "-users"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=session_length&limit=50000&metrics%5B%5D=users&order%5B%5D=%2Bsession_length&order%5B%5D=-users&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Average Session Length

See median or average session length over the past N days by using the median_session_length or average_session_length metrics, with no dimensions specified. Length value is returned in seconds.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'average_session_length',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=average_session_length' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "average_session_length": 343
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:32:06Z",
  "expires_at": "2015-09-15T20:18:45Z",
  "truncated": false,
  "query": {
    "metrics": [
      "average_session_length"
    ],
    "dimensions": null,
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "-average_session_length"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&limit=50000&metrics%5B%5D=average_session_length&order%5B%5D=-average_session_length&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Time Since Previous Session

See the time since previous session for all sessions within the last N days by using the session_interval dimension with the sessions metric. Results will carry a session_interval_description field with a textual description of each session length range.
Add e.g. the birth_month or birth_week dimension to split results by monthly or weekly cohort.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'sessions',
  dimensions: 'session_interval',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=sessions' \
     --data 'dimensions=session_interval' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "session_interval": null,
      "sessions": 25371,
      "session_interval_description": "First session"
    },
    {
      "session_interval": 1,
      "sessions": 40904,
      "session_interval_description": "0 to 1 hour"
    },
    {
      "session_interval": 2,
      "sessions": 62157,
      "session_interval_description": "1 - 24 hours"
    },
    {
      "session_interval": 3,
      "sessions": 23829,
      "session_interval_description": "1 day"
    },
    {
      "session_interval": 4,
      "sessions": 9315,
      "session_interval_description": "2 days"
    },
    {
      "session_interval": 5,
      "sessions": 4832,
      "session_interval_description": "3 days"
    },
    {
      "session_interval": 6,
      "sessions": 2746,
      "session_interval_description": "4 days"
    },
    {
      "session_interval": 7,
      "sessions": 1794,
      "session_interval_description": "5 days"
    },
    {
      "session_interval": 8,
      "sessions": 1040,
      "session_interval_description": "6 days"
    },
    {
      "session_interval": 9,
      "sessions": 605,
      "session_interval_description": "7 days"
    },
    {
      "session_interval": 10,
      "sessions": 576,
      "session_interval_description": "8 - 14 days"
    },
    {
      "session_interval": 11,
      "sessions": 49,
      "session_interval_description": "15 - 30 days"
    },
    {
      "session_interval": 12,
      "sessions": 1,
      "session_interval_description": "31 - 60 days"
    },
    {
      "session_interval": 13,
      "sessions": 1,
      "session_interval_description": "61 - 120 days"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:32:42Z",
  "expires_at": "2015-09-16T09:21:06Z",
  "truncated": false,
  "query": {
    "metrics": [
      "sessions"
    ],
    "dimensions": [
      "session_interval"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+session_interval",
      "-sessions"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=session_interval&limit=50000&metrics%5B%5D=sessions&order%5B%5D=%2Bsession_interval&order%5B%5D=-sessions&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Loyalty

Show how many times users have returned in the last N days. Results will carry a visit_number_description field with a textual description of each loyalty range.
Add e.g. the birth_month or birth_week dimension to split results by monthly or weekly cohort.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'sessions',
  dimensions: 'visit_number',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=sessions' \
     --data 'dimensions=visit_number' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "visit_number": 1,
      "sessions": 25365,
      "visit_number_description": "1st"
    },
    {
      "visit_number": 2,
      "sessions": 19329,
      "visit_number_description": "2nd"
    },
    {
      "visit_number": 3,
      "sessions": 16072,
      "visit_number_description": "3rd"
    },
    {
      "visit_number": 4,
      "sessions": 13411,
      "visit_number_description": "4th"
    },
    {
      "visit_number": 5,
      "sessions": 11588,
      "visit_number_description": "5th"
    },
    {
      "visit_number": 6,
      "sessions": 9986,
      "visit_number_description": "6th"
    },
    {
      "visit_number": 7,
      "sessions": 8615,
      "visit_number_description": "7th"
    },
    {
      "visit_number": 8,
      "sessions": 7545,
      "visit_number_description": "8th"
    },
    {
      "visit_number": 9,
      "sessions": 28985,
      "visit_number_description": "9th-14th"
    },
    {
      "visit_number": 10,
      "sessions": 20267,
      "visit_number_description": "15th-25th"
    },
    {
      "visit_number": 11,
      "sessions": 9563,
      "visit_number_description": "26th-50th"
    },
    {
      "visit_number": 12,
      "sessions": 2187,
      "visit_number_description": "51st-100th"
    },
    {
      "visit_number": 13,
      "sessions": 301,
      "visit_number_description": "101st-200th"
    },
    {
      "visit_number": 14,
      "sessions": 6,
      "visit_number_description": "> 200th"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:32:54Z",
  "expires_at": "2015-09-15T23:32:46Z",
  "truncated": false,
  "query": {
    "metrics": [
      "sessions"
    ],
    "dimensions": [
      "visit_number"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+visit_number",
      "-sessions"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=visit_number&limit=50000&metrics%5B%5D=sessions&order%5B%5D=%2Bvisit_number&order%5B%5D=-sessions&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Events Queries

Event Occurrences

Show occurrences of each event.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'occurrences',
  dimensions: 'event_name',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=occurrences' \
     --data 'dimensions=event_name' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "event_name": "Added to Cart",
      "occurrences": 12778
    },
    {
      "event_name": "Category Viewed",
      "occurrences": 177920
    },
    {
      "event_name": "Changed Settings",
      "occurrences": 1147
    },
    {
      "event_name": "Checkout",
      "occurrences": 3947
    },
    {
      "event_name": "Localytics Push Opened",
      "occurrences": 1964
    },
    {
      "event_name": "Localytics Re-engagement",
      "occurrences": 6802
    },
    {
      "event_name": "Proceed to checkout",
      "occurrences": 2545
    },
    {
      "event_name": "Product Viewed",
      "occurrences": 83853
    },
    {
      "event_name": "ampView",
      "occurrences": 83026
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:33:02Z",
  "expires_at": "2015-09-15T23:19:34Z",
  "truncated": false,
  "query": {
    "metrics": [
      "occurrences"
    ],
    "dimensions": [
      "event_name"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+event_name",
      "-occurrences"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=event_name&limit=50000&metrics%5B%5D=occurrences&order%5B%5D=%2Bevent_name&order%5B%5D=-occurrences&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Users per Event

Show number of users for each event.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'users',
  dimensions: 'event_name',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=users' \
     --data 'dimensions=event_name' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "users": 7331,
      "event_name": "Added to Cart"
    },
    {
      "users": 53676,
      "event_name": "Category Viewed"
    },
    {
      "users": 1028,
      "event_name": "Changed Settings"
    },
    {
      "users": 2608,
      "event_name": "Checkout"
    },
    {
      "users": 1685,
      "event_name": "Localytics Push Opened"
    },
    {
      "users": 4044,
      "event_name": "Localytics Re-engagement"
    },
    {
      "users": 1767,
      "event_name": "Proceed to checkout"
    },
    {
      "users": 35001,
      "event_name": "Product Viewed"
    },
    {
      "users": 21047,
      "event_name": "ampView"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:00Z",
  "expires_at": "2015-09-15T23:04:54Z",
  "truncated": false,
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "event_name"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+event_name",
      "-users"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=event_name&limit=50000&metrics%5B%5D=users&order%5B%5D=%2Bevent_name&order%5B%5D=-users&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Sessions per Event

Show the number of sessions per event.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'sessions_per_event',
  dimensions: 'event_name',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=sessions_per_event' \
     --data 'dimensions=event_name' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "event_name": "Added to Cart",
      "sessions_per_event": 10012
    },
    {
      "event_name": "Category Viewed",
      "sessions_per_event": 116472
    },
    {
      "event_name": "Changed Settings",
      "sessions_per_event": 1062
    },
    {
      "event_name": "Checkout",
      "sessions_per_event": 3094
    },
    {
      "event_name": "Localytics Push Opened",
      "sessions_per_event": 1719
    },
    {
      "event_name": "Localytics Re-engagement",
      "sessions_per_event": 6802
    },
    {
      "event_name": "Proceed to checkout",
      "sessions_per_event": 2229
    },
    {
      "event_name": "Product Viewed",
      "sessions_per_event": 60492
    },
    {
      "event_name": "ampView",
      "sessions_per_event": 31935
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:08Z",
  "expires_at": "2015-09-16T18:56:13Z",
  "truncated": false,
  "query": {
    "metrics": [
      "sessions_per_event"
    ],
    "dimensions": [
      "event_name"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+event_name",
      "-sessions_per_event"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=event_name&limit=50000&metrics%5B%5D=sessions_per_event&order%5B%5D=%2Bevent_name&order%5B%5D=-sessions_per_event&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Event Detail

Show occurrences of a single event, split by day.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'occurrences',
  dimensions: 'day',
  conditions: '{"event_name":"Category Viewed","day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=occurrences' \
     --data 'dimensions=day' \
     --data-urlencode 'conditions={"event_name":"Category Viewed","day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "day": "2015-01-01",
      "occurrences": 19984
    },
    {
      "day": "2015-01-02",
      "occurrences": 15102
    },
    {
      "day": "2015-01-03",
      "occurrences": 21692
    },
    {
      "day": "2015-01-04",
      "occurrences": 52216
    },
    {
      "day": "2015-01-05",
      "occurrences": 21445
    },
    {
      "day": "2015-01-06",
      "occurrences": 16205
    },
    {
      "day": "2015-01-07",
      "occurrences": 14727
    },
    {
      "day": "2015-01-08",
      "occurrences": 16549
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:13Z",
  "expires_at": "2015-09-16T18:19:56Z",
  "truncated": false,
  "query": {
    "metrics": [
      "occurrences"
    ],
    "dimensions": [
      "day"
    ],
    "conditions": {
      "event_name": [
        "IN",
        "Category Viewed"
      ],
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "-occurrences"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&conditions%5Bevent_name%5D%5B%5D=IN&conditions%5Bevent_name%5D%5B%5D=Category+Viewed&dimensions%5B%5D=day&limit=50000&metrics%5B%5D=occurrences&order%5B%5D=%2Bday&order%5B%5D=-occurrences&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Attribute Explorer

Show data for an event's custom attribute.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'occurrences',
  dimensions: 'a:Category',
  conditions: '{"event_name":"Category Viewed","day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=occurrences' \
     --data 'dimensions=a:Category' \
     --data-urlencode 'conditions={"event_name":"Category Viewed","day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "a:Category": "Accessories",
      "occurrences": 26377
    },
    {
      "a:Category": "Art",
      "occurrences": 20607
    },
    {
      "a:Category": "Automotive",
      "occurrences": 13351
    },
    {
      "a:Category": "Books",
      "occurrences": 4222
    },
    {
      "a:Category": "Children",
      "occurrences": 24883
    },
    {
      "a:Category": "Clothing",
      "occurrences": 22913
    },
    {
      "a:Category": "Computer",
      "occurrences": 9856
    },
    {
      "a:Category": "Jewelry",
      "occurrences": 23250
    },
    {
      "a:Category": "Pets",
      "occurrences": 12911
    },
    {
      "a:Category": "Toys",
      "occurrences": 19550
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:19Z",
  "expires_at": "2015-09-15T23:31:10Z",
  "truncated": false,
  "query": {
    "metrics": [
      "occurrences"
    ],
    "dimensions": [
      "a:Category"
    ],
    "conditions": {
      "event_name": [
        "IN",
        "Category Viewed"
      ],
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+a:Category",
      "-occurrences"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&conditions%5Bevent_name%5D%5B%5D=IN&conditions%5Bevent_name%5D%5B%5D=Category+Viewed&dimensions%5B%5D=a%3ACategory&limit=50000&metrics%5B%5D=occurrences&order%5B%5D=%2Ba%3ACategory&order%5B%5D=-occurrences&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Aggregate Metrics

Show average daily values for a event's custom attribute

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'avg(n:Items In Cart)',
  dimensions: 'day',
  conditions: '{"event_name":"Proceed to checkout","day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=avg(n:Items In Cart)' \
     --data 'dimensions=day' \
     --data-urlencode 'conditions={"event_name":"Proceed to checkout","day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "avg(n:Items In Cart)": 0.8,
      "day": "2015-01-01"
    },
    {
      "avg(n:Items In Cart)": 0.869955156950673,
      "day": "2015-01-02"
    },
    {
      "avg(n:Items In Cart)": 0.756198347107438,
      "day": "2015-01-03"
    },
    {
      "avg(n:Items In Cart)": 0.736231884057971,
      "day": "2015-01-04"
    },
    {
      "avg(n:Items In Cart)": 0.707520891364902,
      "day": "2015-01-05"
    },
    {
      "avg(n:Items In Cart)": 0.820253164556962,
      "day": "2015-01-06"
    },
    {
      "avg(n:Items In Cart)": 0.728624535315985,
      "day": "2015-01-07"
    },
    {
      "avg(n:Items In Cart)": 0.837349397590361,
      "day": "2015-01-08"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:28Z",
  "expires_at": "2015-09-16T11:41:10Z",
  "truncated": false,
  "query": {
    "metrics": [
      "avg(n:Items In Cart)"
    ],
    "dimensions": [
      "day"
    ],
    "conditions": {
      "event_name": [
        "IN",
        "Proceed to checkout"
      ],
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "-avg(n:Items In Cart)"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&conditions%5Bevent_name%5D%5B%5D=IN&conditions%5Bevent_name%5D%5B%5D=Proceed+to+checkout&dimensions%5B%5D=day&limit=50000&metrics%5B%5D=avg%28n%3AItems+In+Cart%29&order%5B%5D=%2Bday&order%5B%5D=-avg%28n%3AItems+In+Cart%29&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Bucketing

Group data for an event's numeric custom attribute in equal size buckets

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'occurrences',
  dimensions: 'bucket(n:Items In Cart,0,10,2)',
  conditions: '{"event_name":"Proceed to checkout","day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=occurrences' \
     --data 'dimensions=bucket(n:Items In Cart,0,10,2)' \
     --data-urlencode 'conditions={"event_name":"Proceed to checkout","day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "bucket(n:Items In Cart,0,10,2)": 1,
      "occurrences": 2502,
      "bucket": {
        "lower_bound": 0,
        "upper_bound": 5
      }
    },
    {
      "bucket(n:Items In Cart,0,10,2)": 2,
      "occurrences": 43,
      "bucket": {
        "lower_bound": 5,
        "upper_bound": 10
      }
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:35Z",
  "expires_at": "2015-09-16T19:20:00Z",
  "truncated": false,
  "query": {
    "metrics": [
      "occurrences"
    ],
    "dimensions": [
      "bucket(n:Items In Cart,0,10,2)"
    ],
    "conditions": {
      "event_name": [
        "IN",
        "Proceed to checkout"
      ],
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+bucket(n:Items In Cart,0,10,2)",
      "-occurrences"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&conditions%5Bevent_name%5D%5B%5D=IN&conditions%5Bevent_name%5D%5B%5D=Proceed+to+checkout&dimensions%5B%5D=bucket%28n%3AItems+In+Cart%2C0%2C10%2C2%29&limit=50000&metrics%5B%5D=occurrences&order%5B%5D=%2Bbucket%28n%3AItems+In+Cart%2C0%2C10%2C2%29&order%5B%5D=-occurrences&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Event Groups

Show occurrences split by event group, each group consisting of one or more events.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'occurrences',
  dimensions: 'day',
  conditions: '{"event_name":["in_groups",{"Group 1":["Category Viewed","Product Viewed"]},{"Group 2":["Checkout Failed","Changed Settings"]}],"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=occurrences' \
     --data 'dimensions=day' \
     --data-urlencode 'conditions={"event_name":["in_groups",{"Group 1":["Category Viewed","Product Viewed"]},{"Group 2":["Checkout Failed","Changed Settings"]}],"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "day": "2015-01-01",
      "event_group": "Group 1",
      "occurrences": 29711
    },
    {
      "day": "2015-01-06",
      "event_group": "Group 1",
      "occurrences": 26653
    },
    {
      "day": "2015-01-08",
      "event_group": "Group 1",
      "occurrences": 25800
    },
    {
      "day": "2015-01-03",
      "event_group": "Group 1",
      "occurrences": 32436
    },
    {
      "day": "2015-01-05",
      "event_group": "Group 1",
      "occurrences": 30889
    },
    {
      "day": "2015-01-07",
      "event_group": "Group 1",
      "occurrences": 25712
    },
    {
      "day": "2015-01-04",
      "event_group": "Group 1",
      "occurrences": 66229
    },
    {
      "day": "2015-01-02",
      "event_group": "Group 1",
      "occurrences": 24343
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:41Z",
  "expires_at": "2015-09-16T20:00:05Z",
  "truncated": false,
  "query": {
    "metrics": [
      "occurrences"
    ],
    "dimensions": [
      "day"
    ],
    "conditions": {
      "event_name": [
        "in_groups",
        {
          "Group 1": [
            "Category Viewed",
            "Product Viewed"
          ]
        },
        {
          "Group 2": [
            "Checkout Failed",
            "Changed Settings"
          ]
        }
      ],
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "-occurrences"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&conditions%5Bevent_name%5D%5B%5D=in_groups&conditions%5Bevent_name%5D%5B%5D%5BGroup+1%5D%5B%5D=Category+Viewed&conditions%5Bevent_name%5D%5B%5D%5BGroup+1%5D%5B%5D=Product+Viewed&conditions%5Bevent_name%5D%5B%5D%5BGroup+2%5D%5B%5D=Checkout+Failed&conditions%5Bevent_name%5D%5B%5D%5BGroup+2%5D%5B%5D=Changed+Settings&dimensions%5B%5D=day&limit=50000&metrics%5B%5D=occurrences&order%5B%5D=%2Bday&order%5B%5D=-occurrences&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Customer Value Queries

Customer Lifetime Value

Query average customer lifetime value (CLV) in cents for users active during the given time frame, split by day.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'average_clv',
  dimensions: 'day',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=average_clv' \
     --data 'dimensions=day' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "average_clv": 4093.59622713415,
      "day": "2015-01-01"
    },
    {
      "average_clv": 4115.39052916845,
      "day": "2015-01-02"
    },
    {
      "average_clv": 4273.68139781151,
      "day": "2015-01-03"
    },
    {
      "average_clv": 4271.911703312,
      "day": "2015-01-04"
    },
    {
      "average_clv": 4254.9814849683,
      "day": "2015-01-05"
    },
    {
      "average_clv": 4332.00048530227,
      "day": "2015-01-06"
    },
    {
      "average_clv": 4329.97597146612,
      "day": "2015-01-07"
    },
    {
      "average_clv": 4435.07461782957,
      "day": "2015-01-08"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:44Z",
  "expires_at": "2015-09-16T07:18:28Z",
  "truncated": false,
  "query": {
    "metrics": [
      "average_clv"
    ],
    "dimensions": [
      "day"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "-average_clv"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=day&limit=50000&metrics%5B%5D=average_clv&order%5B%5D=%2Bday&order%5B%5D=-average_clv&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Average Monthly Value

Query average customer monthly value for users active during the given time frame, split by day.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'average_monthly_value',
  dimensions: 'day',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=average_monthly_value' \
     --data 'dimensions=day' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "average_monthly_value": 5782.23871809218,
      "day": "2015-01-01"
    },
    {
      "average_monthly_value": 5560.67861395172,
      "day": "2015-01-02"
    },
    {
      "average_monthly_value": 5491.45321596843,
      "day": "2015-01-03"
    },
    {
      "average_monthly_value": 5189.13696566692,
      "day": "2015-01-04"
    },
    {
      "average_monthly_value": 5069.80524984461,
      "day": "2015-01-05"
    },
    {
      "average_monthly_value": 4958.6007669568,
      "day": "2015-01-06"
    },
    {
      "average_monthly_value": 4676.71238828084,
      "day": "2015-01-07"
    },
    {
      "average_monthly_value": 4482.37210703268,
      "day": "2015-01-08"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:47Z",
  "expires_at": "2015-09-16T01:23:52Z",
  "truncated": false,
  "query": {
    "metrics": [
      "average_monthly_value"
    ],
    "dimensions": [
      "day"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "-average_monthly_value"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=day&limit=50000&metrics%5B%5D=average_monthly_value&order%5B%5D=%2Bday&order%5B%5D=-average_monthly_value&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Revenue

Query revenue in cents, split by day.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'revenue',
  dimensions: 'day',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=revenue' \
     --data 'dimensions=day' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "revenue": 258030,
      "day": "2015-01-01"
    },
    {
      "revenue": 2233208,
      "day": "2015-01-02"
    },
    {
      "revenue": 1389780,
      "day": "2015-01-03"
    },
    {
      "revenue": 1560723,
      "day": "2015-01-04"
    },
    {
      "revenue": 2503617,
      "day": "2015-01-05"
    },
    {
      "revenue": 1938819,
      "day": "2015-01-06"
    },
    {
      "revenue": 2461452,
      "day": "2015-01-07"
    },
    {
      "revenue": 1505220,
      "day": "2015-01-08"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:50Z",
  "expires_at": "2015-09-15T19:11:24Z",
  "truncated": false,
  "query": {
    "metrics": [
      "revenue"
    ],
    "dimensions": [
      "day"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "-revenue"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=day&limit=50000&metrics%5B%5D=revenue&order%5B%5D=%2Bday&order%5B%5D=-revenue&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Customers

Query the number of customers, split by day.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'customers',
  dimensions: 'day',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=customers' \
     --data 'dimensions=day' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "customers": 35,
      "day": "2015-01-01"
    },
    {
      "customers": 385,
      "day": "2015-01-02"
    },
    {
      "customers": 249,
      "day": "2015-01-03"
    },
    {
      "customers": 269,
      "day": "2015-01-04"
    },
    {
      "customers": 460,
      "day": "2015-01-05"
    },
    {
      "customers": 359,
      "day": "2015-01-06"
    },
    {
      "customers": 439,
      "day": "2015-01-07"
    },
    {
      "customers": 265,
      "day": "2015-01-08"
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:34:55Z",
  "expires_at": "2015-09-16T23:18:12Z",
  "truncated": false,
  "query": {
    "metrics": [
      "customers"
    ],
    "dimensions": [
      "day"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+day",
      "-customers"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=day&limit=50000&metrics%5B%5D=customers&order%5B%5D=%2Bday&order%5B%5D=-customers&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Profile Queries

Profiles by Attribute

View your most popular profile attributes.
Your profiledb_id is located in Settings > Apps > Profile Database ID.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  profiledb_id:     'PROFILEDB_ID',
  metrics:    'profiles',
  dimensions: 'profile_attribute_key'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'profiledb_id=PROFILEDB_ID' \
     --data 'metrics=profiles' \
     --data 'dimensions=profile_attribute_key' \

{
  "results": [
    {
      "profile_attribute_key": "$email",
      "profiles": 1
    },
    {
      "profile_attribute_key": "$first_name",
      "profiles": 1
    },
    {
      "profile_attribute_key": "$full_name",
      "profiles": 1
    },
    {
      "profile_attribute_key": "$last_name",
      "profiles": 1
    },
    {
      "profile_attribute_key": "Email Available",
      "profiles": 359895
    },
    {
      "profile_attribute_key": "Email Subscription Status",
      "profiles": 357951
    },
    {
      "profile_attribute_key": "Gender",
      "profiles": 360915
    },
    {
      "profile_attribute_key": "Last Email Received",
      "profiles": 130737
    },
    {
      "profile_attribute_key": "Predicted Churn Risk",
      "profiles": 360915
    },
    {
      "profile_attribute_key": "Preferred Contact Time (End)",
      "profiles": 350661
    },
    {
      "profile_attribute_key": "Preferred Contact Time (Start)",
      "profiles": 353718
    },
    {
      "profile_attribute_key": "_ll.city_name",
      "profiles": 350661
    },
    {
      "profile_attribute_key": "_ll.country",
      "profiles": 434991
    },
    {
      "profile_attribute_key": "_ll.device_timezone",
      "profiles": 429150
    },
    {
      "profile_attribute_key": "_ll.language",
      "profiles": 335842
    },
    {
      "profile_attribute_key": "_ll.last_session_date",
      "profiles": 434994
    },
    {
      "profile_attribute_key": "_ll.timezone",
      "profiles": 434328
    },
    {
      "profile_attribute_key": "_ll.user_type",
      "profiles": 24462
    }
  ],
  "comment": null,
  "created_at": "2015-09-08T16:07:42Z",
  "expires_at": "2015-09-08T16:07:42Z",
  "truncated": false,
  "query": {
    "metrics": [
      "profiles"
    ],
    "dimensions": [
      "profile_attribute_key"
    ],
    "conditions": {
    },
    "profiledb_id": [
      152
    ],
    "order": [
      "+profile_attribute_key",
      "-profiles"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&&dimensions%5B%5D=profile_attribute_key&limit=50000&metrics%5B%5D=profiles&order%5B%5D=%2Bprofile_attribute_key&order%5B%5D=-profiles&profiledb_id%5B%5D=152&sampling_ratio=1.0"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Profiles by Gender

Query number of profiles by gender.
Your profiledb_id is located in Settings > Apps > Profile Database ID.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  profiledb_id:     'PROFILEDB_ID',
  metrics:    'profiles',
  dimensions: 'profile_value_string',
  conditions: '{"profile_attribute_key":"Gender"}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'profiledb_id=PROFILEDB_ID' \
     --data 'metrics=profiles' \
     --data 'dimensions=profile_value_string' \
     --data-urlencode 'conditions={"profile_attribute_key":"Gender"}'

{
  "results": [
    {
      "profile_value_string": "Female",
      "profiles": 157068
    },
    {
      "profile_value_string": "Male",
      "profiles": 203922
    }
  ],
  "comment": null,
  "created_at": "2015-09-08T16:07:44Z",
  "expires_at": "2015-09-08T16:07:44Z",
  "truncated": false,
  "query": {
    "metrics": [
      "profiles"
    ],
    "dimensions": [
      "profile_value_string"
    ],
    "conditions": {
      "profile_attribute_key": [
        "IN",
        "Gender"
      ]
    },
    "profiledb_id": [
      152
    ],
    "order": [
      "+profile_value_string",
      "-profiles"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&conditions%5Bprofile_attribute_key%5D%5B%5D=IN&conditions%5Bprofile_attribute_key%5D%5B%5D=Gender&dimensions%5B%5D=profile_value_string&limit=50000&metrics%5B%5D=profiles&order%5B%5D=%2Bprofile_value_string&order%5B%5D=-profiles&profiledb_id%5B%5D=152&sampling_ratio=1.0"
    },
    "root": {
      "href": "/v1"
    }
  }
}

Attribution Queries

New Users by Acquisition Source

Query number of new users split by acquisition source.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'users',
  dimensions: 'channel',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=users' \
     --data 'dimensions=channel' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "channel": null,
      "users": 7712
    },
    {
      "channel": "Facebook",
      "users": 25914
    },
    {
      "channel": "HasOffers",
      "users": 50936
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:35:08Z",
  "expires_at": "2015-09-15T14:58:10Z",
  "truncated": false,
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "channel"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+channel",
      "-users"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=channel&limit=50000&metrics%5B%5D=users&order%5B%5D=%2Bchannel&order%5B%5D=-users&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}

New Users by Acquisition Campaign

Query number of new users split by acquisition campaign.

api = HyperResource.new(
  root: 'https://api.localytics.com/v1',
  auth: {:basic => ['API_KEY', 'API_SECRET']}
)
api.query(
  app_id:     'APP_ID',
  metrics:    'users',
  dimensions: 'campaign',
  conditions: '{"day":["between","2015-01-01","2015-01-08"]}'
).get

curl --get  'https://api.localytics.com/v1/query' \
     --user 'API_KEY:API_SECRET' \
     --data 'app_id=APP_ID' \
     --data 'metrics=users' \
     --data 'dimensions=campaign' \
     --data-urlencode 'conditions={"day":["between","2015-01-01","2015-01-08"]}'

{
  "results": [
    {
      "campaign": null,
      "users": 7712
    },
    {
      "campaign": "FB Men 25-40",
      "users": 12581
    },
    {
      "campaign": "FB Women 25-40",
      "users": 17980
    },
    {
      "campaign": "HO-Tapjoy 10% Off",
      "users": 33501
    },
    {
      "campaign": "HO-Tapjoy 15% Off",
      "users": 30941
    }
  ],
  "app_id": [
    "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
  ],
  "comment": null,
  "created_at": "2015-09-08T14:35:14Z",
  "expires_at": "2015-09-16T10:26:08Z",
  "truncated": false,
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "campaign"
    ],
    "conditions": {
      "day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    ],
    "order": [
      "+campaign",
      "-users"
    ],
    "limit": 50000,
    "translate": {
    },
    "comment": null,
    "sampling_ratio": 1.0
  },
  "_links": {
    "self": {
      "href": "/v1/query?&app_id%5B%5D=91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f&conditions%5Bday%5D%5B%5D=between&conditions%5Bday%5D%5B%5D=2015-01-01&conditions%5Bday%5D%5B%5D=2015-01-08&dimensions%5B%5D=campaign&limit=50000&metrics%5B%5D=users&order%5B%5D=%2Bcampaign&order%5B%5D=-users&sampling_ratio=1.0"
    },
    "app": {
      "href": "/v1/apps/91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f"
    },
    "root": {
      "href": "/v1"
    }
  }
}