Data Export API
robotmia lets you pull your data out at any time - which means you can add key graphs to your own internal dashboards with ease.
Client libraries
These are official libraries that can be used to easily consume data through the robotmia API.
Python
Download the Python client library
PHP
Download the PHP client library
Ruby
JavaScript
We do not have a JavaScript client library, but we have implemented JSONP on the API backend. See the Wikipedia article for a brief overview. Our JSONP parameter is "callback". This parameter will not be used during signature calculation.
Authentication
In order to ensure the security of your data, the robotmia API requires a basic system of authentication.
Note: Our previously-used authentication method is deprecated. Please see further in this section for information on the old method.
Required parameter
api_secret - This can be found by clicking on your name in the upper righthand corner under Project Settings.
Authorization steps
The Data Export API accepts Basic access authentication over HTTPS as an authorization method. To make an authorized request, put your project's API Secret in the "username" field of the Basic access authentication header. Make sure you use HTTPS and not HTTP - our API rejects requests made over HTTP, since this sends your API Secret over the internet in plain text.
Examples
Here's an example of a properly-authenticated request made with cURL:
curl https://robotmia.com/api/2.0/segmentation/ \
-u YOUR_API_SECRET: \
-d from_date="2016-02-11" -d to_date="2016-02-11" -d event="Viewed Page"
You can also make a request in your browser:
https://api_secret@robotmia.com/api/2.0/segmentation?from_date=2016-02-11&to_date=2016-02-11&event=Viewed PageDeprecated Authentication
Note: This authentication method is deprecated. It is recommended that you use the current authentication method highlighted above.
Required parameters
api_key - This is an API key corresponding to the project you wish to consume from.
api_secret - This is a secret API key corresponding to the project. You should never give this out to anyone or show it.
sig - Signature for the method call, used in combination with your api_key, api_secret, and API endpoint parameters.
expire - UTC time in seconds; used to expire an API request.
Both api_key and api_secret can be found on your account page under API information.
Authorization steps
- All requests must have the following parameters:
api_key,expire,sig. api_keycan be found on your account page under API Information.expireis any UTC time in the future that represents how long you wish the request consuming data to last. For example, if you wish the request to only last 1 minute, you would calculate the UTC time as of now and then add 60 representing 1 minute ahead.Calculate the signature of the request using your
api_secret. Calculating the signature is done in parts: sort the parameters you are including with the URL alphabetically, join into a string resulting in key=valuekey2=value2 (excluding ampersands), concatenate the result with theapi_secretby appending it, and lastly md5 hash the final string.This hash is used for the
sigparameter in the request therefore it should not be be calculated withsigas a parameter. The purpose of this process is to prevent unauthorized attempts to consume your data as much as possible.Pseudo code:
args = all query parameters going to be sent out with the request (e.g. api_key, unit, interval, expire, format, etc.) excluding sig. args_sorted = sort_args_alphabetically_by_key(args) args_concat = join(args_sorted) # Output: api_key=ed0b8ff6cc3fbb37a521b40019915f18event=["pages"] # expire=1248499222format=jsoninterval=24unit=hour sig = md5(args_concat + api_secret)
Lastly, include
sigwith your URL request along with the normal parameters to consume data securely. Your URL should look similar to this however varying on the endpoint you are requesting data from:https://robotmia.com/api/2.0/events/?interval=7&expire=1275624968&sig=046ceec93983811dad0fb20f842c351a&api_key=f0aa346688cee071cd85d857285a3464&type=average&event=%5B%22splash+features<%22%2C+%22account-page%22%5D&unit=day
Annotations
Method: annotations
URI: https://robotmia.com/api/2.0/annotations/
Description:
List the annotations for the given date range.
Example URL:
https://robotmia.com/api/2.0/annotations/?from_date=2014-05-11&to_date=2014-06-09Return format:
{"annotations": [
{"date": "2014-05-23 00:00:00", "project_id": 23880, "id": 148, "description": "Launched v2.0 of product"},
{"date": "2014-05-29 00:00:00", "project_id": 23880, "id": 150, "description": "Streamlined registration process"}
], "error": false}
Method: create
URI: https://robotmia.com/api/2.0/annotations/create/
Description:
Create a new annotation at the specified time.
Example URL:
https://robotmia.com/api/2.0/annotations/create?date=2014-05-15+00%3A00%3A00&description=Launched+version+2.0!Return format:
{"error": false}
Method: update
URI: https://robotmia.com/api/2.0/annotations/update/
Description:
Update an annotation to the new time or description.
Example URL:
https://robotmia.com/api/2.0/annotations/update?id=148&date=2014-03-09+12%3A34%3A56&description=Concluded button A/B test.Return format:
{"error": false}
Method: delete
URI: https://robotmia.com/api/2.0/annotations/delete/
Description:
Delete an annotation.
Example URL:
https://robotmia.com/api/2.0/annotations/delete?id=42Return format:
{"error": false}
Events
Method: events
URI: https://robotmia.com/api/2.0/events/
Description:
Get unique, total, or average data for a set of events over N days, weeks, or months.
Example URL:
https://robotmia.com/api/2.0/events/?interval=7&&type=average&event=%5B%22splash+features%22%2C+%22account-page%22%5D&unit=dayReturn format:
{"data": {"series": ["2010-05-29",
"2010-05-30",
"2010-05-31",
],
"values": {"account-page": {"2010-05-30": 1,},
"splash features": {"2010-05-29": 6,
"2010-05-30": 4,
"2010-05-31": 5,
}
}
},
"legend_size": 2}
Method: top
URI: https://robotmia.com/api/2.0/events/top/
Description:
Get the top events for today, with their counts and the normalized percent change from yesterday.
Example URL:
https://robotmia.com/api/2.0/events/top?type=uniqueReturn format:
{"events": [{"amount": 2,
"event": u"funnel",
"percent_change": -0.35635745999582824},
{"amount": 75,
"event": u"pages",
"percent_change": -0.20209602478821687},
{"amount": 2, "event": u"projects", "percent_change": 1.0}],
"type": u"unique"}
Method: names
URI: https://robotmia.com/api/2.0/events/names/
Description:
Get a list of the most common events over the last 31 days.
Example URL:
https://robotmia.com/api/2.0/events/names?type=generalReturn format:
// Alphabetical Order, descending
[ "battle","click signup button","send message","View homepage"]
Event properties
Method: properties
URI: https://robotmia.com/api/2.0/events/properties/
Description:
Get unique, total, or average data for of a single event and property over days, weeks, or months.
Example URL:
https://robotmia.com/api/2.0/events/properties?name=feature&interval=7&type=unique&event=splash+features&unit=dayReturn format:
{"data": {"series": ["2010-05-29",
"2010-05-30",
"2010-05-31",
],
"values": {"splash features": {"2010-05-29": 6,
"2010-05-30": 4,
"2010-05-31": 5,
}
}
},
"legend_size": 2}
Method: top
URI: https://robotmia.com/api/2.0/events/properties/top/
Description:
Get the top property names for an event.
Example URL:
https://robotmia.com/api/2.0/events/properties/top?event=splash+featureReturn format:
{"ad version": {"count": 295}, "user type": {"count": 91}}
Method: values
URI: https://robotmia.com/api/2.0/events/properties/values/
Description:
Get the top values for a property.
Example URL:
https://robotmia.com/api/2.0/events/properties/values?name=feature&interval=7&type=general&event=splash+features&unit=dayReturn format:
["male", "female", "unknown"]
Funnels
Method: funnels
URI: https://robotmia.com/api/2.0/funnels/
Description:
Get data for a funnel.
Example URL:
https://robotmia.com/api/2.0/funnels/?funnel_id=1&unit=weekReturn format:
{"meta":
{"dates": ["2016-09-12", "2016-09-19", "2016-09-26"]},
"data": {
"2016-09-12":
{"steps": [
{"count": 32688, "step_conv_ratio": 1, "goal": "App Open", "overall_conv_ratio": 1, "avg_time": null, "event": "App Open"},
{"count": 20524, "step_conv_ratio": 0.627875673029858, "goal": "Game Played", "overall_conv_ratio": 0.627875673029858, "avg_time": 718, "event": "Game Played"}],
"analysis": {"completion": 20524, "starting_amount": 32688, "steps": 2, "worst": 1}},
"2016-09-19":
{"steps": [
{"count": 32486, "step_conv_ratio": 1, "goal": "App Open", "overall_conv_ratio": 1, "avg_time": null, "event": "App Open"},
{"count": 20809, "step_conv_ratio": 0.6405528535369082, "goal": "Game Played", "overall_conv_ratio": 0.6405528535369082, "avg_time": 698, "event": "Game Played"}],
"analysis": {"completion": 20809, "starting_amount": 32486, "steps": 2, "worst": 1}},
"2016-09-26":
{"steps": [
{"count": 16103, "step_conv_ratio": 1, "goal": "App Open", "overall_conv_ratio": 1, "avg_time": null, "event": "App Open"},
{"count": 12679, "step_conv_ratio": 0.7873688132646091, "goal": "Game Played", "overall_conv_ratio": 0.7873688132646091, "avg_time": 571, "event": "Game Played"}],
"analysis": {"completion": 12679, "starting_amount": 16103, "steps": 2, "worst": 1}}
}}
Method: list
URI: https://robotmia.com/api/2.0/funnels/list/
Description:
Get the names and funnel_ids of your funnels. This method takes no parameters.
Example URL:
https://robotmia.com/api/2.0/funnels/listReturn format:
[{"funnel_id": 7509, "name": "Signup funnel"},
{"funnel_id": 9070, "name": "Funnel tutorial"}]
Segmentation
Method: segmentation
URI: https://robotmia.com/api/2.0/segmentation/
Description:
Get data for an event, segmented and filtered by properties.
Example 1
Suppose Harry Q. Bovik has a website named example.com. He has an event named signed up, sent whenever a user signs up to example.com. It has a string property named mp_country_code that stores the country code of the user signing up.
A query with the following GET parameters sent over HTTPS with your API Secret as the Basic Access Authentication username would return the number of signed up events for each day from 2011-08-06 to 2011-08-09:
Return format:
{"data": {"series": ["2011-08-08",
"2011-08-09",
"2011-08-06",
"2011-08-07"],
"values": {"signed up": {"2011-08-06": 147,
"2011-08-07": 146,
"2011-08-08": 776,
"2011-08-09": 1376}}},
"legend_size": 1}
Example 2
Suppose Harry is impressed with the number of signups on 2011-08-09, and now wants to know the top five countries his signups came from on that day. He can make the following query sent over HTTPS with your API Secret as the Basic Access Authentication username:
Return format:
{"data": {"series": ["2011-08-09"],
"values": {"CA": {"2011-08-09": 277},
"FR": {"2011-08-09": 8},
"GB": {"2011-08-09": 19},
"IN": {"2011-08-09": 19},
"US": {"2011-08-09": 1036}}},
"legend_size": 5}
Example 3
Harry now wants to zero in on the US and Canada. He is tracking a property named mp_keyword, which tells him the search keyword that users used to get to example.com. Now he wants to determine how many signups from the US and Canada came about as a result of a search that contained the word "harry." He can do that with the following query sent over HTTPS with your API Secret as the Basic Access Authentication username:
Return format:
{"data": {"series": ["2011-08-09"],
"values": {"CA": {"2011-08-09": 31},
"US": {"2011-08-09": 312}}},
"legend_size": 2}
Note: Segmentation expressions with to_dates in the future will return inaccurate data.
Method: numeric
URI: https://robotmia.com/api/2.0/segmentation/numeric/
Description:
Get data for an event, segmented and filtered by properties, with values placed into numeric buckets.
Example 1
Harry Q. Bovik also has an event named page loaded. It has a property named time that represents the time in milliseconds it took to load the page. Harry wants to see the distribution of page load times that are greater than 2000 milliseconds. But suppose Harry accidentally was sending the time property to robotmia as a string, so its the incorrect type. He can make the following query, sent over HTTPS with the API Secret as the Basic Access Authentication username, involving an explicit typecast to number to get the results he wants:
Return format:
{"data": {"series": ["2011-08-08",
"2011-08-09",
"2011-08-06",
"2011-08-07"],
"values": {"2,000 - 2,100": {"2011-08-06": 1,
"2011-08-07": 5,
"2011-08-08": 4,
"2011-08-09": 15},
"2,100 - 2,200": {"2011-08-07": 2,
"2011-08-08": 7,
"2011-08-09": 15},
"2,200 - 2,300": {"2011-08-06": 1,
"2011-08-08": 6,
"2011-08-09": 5},
"2,300 - 2,400": {"2011-08-06": 4,
"2011-08-08": 1,
"2011-08-09": 12},
"2,400 - 2,500": {"2011-08-08": 2,
"2011-08-09": 5}}},
"legend_size": 5}
Method: sum
URI: https://robotmia.com/api/2.0/segmentation/sum/
Description:
Sums an expression for events per unit time.
Example 1
Harry also sells things from example.com. He has an event named item sold that tracks each item that gets sold from his website. It has a number property named price that records the value of the item being sold. He has another number property named overhead that represents the overhead cost of the item. Harry can find out how much profit he is making each day with the following query, sent over HTTPS with the API Secret as the Basic Access Authentication username:
Return format:
{"results": {"2011-08-06": 376.0,
"2011-08-07": 634.0,
"2011-08-08": 474.0,
"2011-08-09": 483.0},
"status": "ok"}
Method: average
URI: https://robotmia.com/api/2.0/segmentation/average/
Description:
Averages an expression for events per unit time.
Example 1
Instead of finding out the total profit he is making per day by selling things from his website, Harry can also find out the average price of an item being sold with the following query, sent over HTTPS with the API Secret as the Basic Access Authentication username:
Return format:
{"results": {"2011-08-06": 8.64705882352939,
"2011-08-07": 4.640625,
"2011-08-08": 3.6230899830221,
"2011-08-09": 7.3353658536585},
"status": "ok"}
Segmentation expressions
The power of segmentation comes from the ability to define custom expressions based on property names in the where and on parameters. An expression consists of a property, combined with one or more operators that can perform mathematical operations, logical operations, or typecasts. Expression are then applied in the where and on parameters of the segmentation API. The full grammar for expressions is given here:
<expression> ::= 'properties["' <property> '"]'
| <expression> <binary op> <expression>
| <unary op> <expression>
| <math op> '(' <expression> ')'
| <typecast op> '(' <expression> ')'
| '(' <expression> ')'
| <boolean literal>
| <numeric literal>
| <string literal>
<binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' |
'>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or'
<unary op> ::= '-' | 'not'
<math op> ::= 'floor' | 'round' | 'ceil'
<typecast op> ::= 'boolean' | 'number' | 'string'
<property> ::= 'properties["' <property name> '"]'
A great way to build segmentation expressions is via examining the segmentation requests made within our own Segmentation report! Click here to learn more.
Typecast Operations
Internally, all properties of events have a type. This type is determined when we parse the event sent to us into a JSON object. Currently, there are three types, string, number, and boolean, which may be specified directly. A property may also have the values null and undefined, which are only handled internally. The default type is string. If you wish to treat an expression as another type, you may use the typecast operators to cast a property to a different type. For example, if properties["signed up"] has values of "true" and "false" as strings, and you wish to intercodet them as booleans, you may cast them by using the boolean() typecast function: boolean(properties["signed up"]).
The typecasting rules are described below.
Casting to String
Casting to Number
Casting to Boolean
Binary Operations
The arithmetic operators "-", "*", "/", "%" perform the subtraction, multiplication, division, and remainder operations, respectively. The division operator will return undefined if the divisor is 0. The sign of the value of the remainder will be equivalent to the dividend. All four of these operators expect both operands to be of the type number, or else the result is undefined.
The "+" operator behaves as addition if its two operands are of type number. However, if its two operands are of type string, it will concatenate the two strings. In other cases, the result is undefined.
The equals operator "==" will always return a boolean. When its two types are equal, it performs the standard equality comparison based on the values. If the types of its operands are not equal, false is returned. The not equals operator "!=" returns false when the equals operator would return true and vice-versa.
The comparison operators ">", ">=", "<", and "<=" returns a boolean value based on evaluating the comparison when its operands are both of type number. When its types are not equal, undefined is returned.
The "in" operator returns true if both operands are of type string and the first string is a substring of the second. When both operands are of differing types, undefined is returned.
The logical operators "and" and "or" accept boolean and undefined operands. An operand with type undefined evaluates as false. Any other types will result in an error.
Unary and Math Operations
The "-" operator will negate an operand of type number, and return undefined otherwise.
The "not" operator will perform the logical not on an operand of type boolean. It will also evaluate an operand of type undefined as true. All other operands will be evaluated to undefined.
The "floor", "round", and "ceil" functions perform their mathematical operations on an operand of type number. On all other types, it will return undefined.
Retention
Method: retention
URI: https://robotmia.com/api/2.0/retention/
Description:
Get cohort analysis.
Example URL:
https://robotmia.com/api/2.0/retention/?from_date=2012-01-01&to_date=2012-01-03&retention_type=birth&interval_count=2&event=viewed+report&born_event=event+integration&expire=1326512270&sig=2bdfb7fe5db9337f357e04f7d1a85b86Return format:
{
"2012-01-01": {
"counts": [2, 1, 2], "first": 2
},
"2012-01-02": {
"counts": [9, 7, 6], "first": 10
},
"2012-01-03": {
"counts": [9, 6, 4], "first": 10
}
}
We specified neither an interval nor a unit, so the interval is 1 day. This means that each user gets 24 hours in each interval to do the specified event. On 2012-01-02, 10 people did the born_event ("event integration"), as indicated by the first field. If the retention_type=compounded, then first will instead indicate the number of people who did event ("viewed report") on the specified date. 9 of those people did event ("viewed report") within 24 hours (the "0th" interval) of doing the born_event . 7 of those did event between 24 and 48 hours (interval 1) of the born_event. These 7 are a subset of the initial 10, but not necessarily a subset of the 9 (retention is not a funnel; see the number increase between 72 and 96 hours). And finally, 6 people did event between 48 and 72 hours (interval 2) after the born_event.
In the robotmia retention UI, "First time" corresponds to retention_type=birth, and "Recurring" corresponds to retention_type=compounded.
Method: addiction
URI: https://robotmia.com/api/2.0/retention/addiction/
Description:
Get data about how frequently people are performing events.
Example URL:
https://robotmia.com/api/2.0/retention/addiction?unit=day&from_date=2012-01-01&to_date=2012-01-03&event=Viewed+report&addiction_unit=hourReturn format:
{
"2012-01-01": [305, 107, 60, 41, 32, 20, 12, 7, 4, 3, 3, 3, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1],
"2012-01-02": [495, 204, 117, 77, 53, 36, 26, 20, 12, 7, 4, 3, 3, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0],
"2012-01-03": [671, 324, 176, 122, 81, 63, 48, 31, 21, 14, 9, 5, 3, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0]
}
We specified "day" as unit and "hour" as addiction_unit, so one day"s worth of data is shown for each date, split into hours. On 2012-01-02, 495 people did the event ("Viewed report") during at least 1 hour out of the next 24 hour period (the period specified by "unit"). 204 people did the event during at least 2 hours. 117 people did the event during at least 3 hours.
Engage
Method: engage
URI: https://robotmia.com/api/2.0/engage/
Description:
Query People Data.
Return format:
{"page": 0,
"page_size": 1000,
"results": [{"$distinct_id": 4,
"$properties": {"$created": "2008-12-12T11:20:47",
"$email": "example@robotmia.com",
"$first_name": "Example",
"$last_name": "Name",
"$last_seen": "2008-06-09T23:08:40",}}],
"session_id": "1234567890-EXAMPL",
"status": "ok",
"total": 1}
Api responses will return at most page_size records for each request. To request additional records, callers should repeat their call to the api using the same where param, but provide a session_id parameter with a value taken from the first response, and include a page parameter with a value one greater than the value of page in the response.
A caller trying to retrieve all of the records for a particular query might use an algorithm something like this:
# Get the first page of data associated with our selector expression
this_page = query_api(where=YOUR_SELECTOR_EXPRESSION)
do_something_with_response(this_page)
# If we get fewer records than the page_sized returned with our results,
# then there are no more records to get. Otherwise, keep querying for additional pages.
while (length of this_page.results) >= this_page.page_size:
next_page_number = this_page.page + 1
this_page = query_api(where=YOUR_SELECTOR_EXPRESSION, session_id=this_page.session_id, page=next_page_number)
do_something_with_response(this_page)
API errors
Error format
{"error": "Invalid parameter: unit",
"request": "/api/2.0/events/general?interval=7&event=%5B%22splash+features%22%5D&unit=day"}