Today, we’re announcing the beta release of Interana’s REST API.  The API is deployed as part of the standard 2.19 upgrade or installation and it supports both single measurement queries and time series queries.

Interana’s API gives users a way to extract summarized and aggregated data for use in downstream processes, data warehouses, dashboards, or reports.  For some customers, Interana is one of several analytics processes they run and consolidation of their analyses in a single report or dashboard is important.  Other customers need aggregated data from Interana to feed into separate processes.  With the advent of the API, users can now run queries outside of the Interana front end.

Single Measurement Queries

Single measurement queries are queries that return a single result set.  A Table view query in Interana Explorer is an example of a single measurement query; only one table of results is returned.  The same holds for queries used in Number view, Bar view, and Pie view.

The Interana Explorer screenshot below shows a single measurement query that returns the number of unique userids, grouped by artist, from April 25, 2016 to April 30, 2016.

The same query can be executed in the API with the request call below.  Its corresponding response follows.  Note that start and end times are specified as milliseconds since epoch, and timezone_offset, also specified in milliseconds, is relative to GMT.

Request:


{“dataset”: “Music”,
"start": 1461567600000,
"end": 1461999600000,
"timezone_offset": -25200000,
"queries": [ {
"type": "single_measurement",
"measure": {
"aggregator": "unique_count",
"column": "userId" },
"filter": "(`artist` != "*null*")"
  } ]
"sampled": true,
"group_by": ["artist"],
"max_groups": 5,
"compute_all_others": false
}

Response:


{ "rows": [
{"values": [ [ "3 Doors Down"], 36420] },
{"values": [ [ "Justin Bieber"], 36584] },
{"values": [ [ "OneRepublic"], 36916] },
{"values": [ [ "Taylor Swift"], 35220] },
{"values": [ [ "The White Stripes"], 31640] }
],
"columns": [
{"type": "array", "label": ["artist"] },
{"type": "number", "label": "measure_value"}
]
}

Time Series Queries

Time series queries are queries that return a result set for every x-axis data point.  In Interana Explorer, time series queries are rendered using the Time view.

If the query example used above is issued as a time series query instead of a single measurement query, each x-axis point within the query’s time range will return a count of each user’s events.  In other words, the query returns a different result set for each x axis point.

The Interana Explorer screenshot below shows a time series query that returns the number of events between April 29, 2016 12:00 am and April 29, 2016 12:00 pm.

Time Series Query

The same query can be executed using the API with the request call below.  Its corresponding response follows.  Note that the response has been abbreviated given the large number of results.

In the request call, the query start and end times are specified in milliseconds since epoch, and timezone_offset, also specified in milliseconds, is relative to GMT.  Finally, the sampled flag indicates whether to use sampling when running the query.  For more information on sampling, check out our documentation.  There’s a fabulous blog on this topic as well.

Request:


{ “dataset”: “Music”,
"start": 1461913200000,
"end": 1461956400000,
"timezone_offset": -25200000,
"queries": [ {
"type": "time_series",
"measure": {"aggregator": "count_star"},
} ]
"sampled": true,
}

Response:


{ "rows": [
{"values": [ [ "All"], [
{“timestamp”: 1461913200000, “properties”: {“object_count”: 25243, "event_count": 25243},
"value": 8414.333333333332},
……
{"timestamp": 1461934800000, "properties": {"object_count": 20977, "event_count": 20977},
"value": 6992.333333333333},
……
{"timestamp": 1461956400000, "properties": {"object_count": 27581, "event_count": 27581},
"value": 9193.666666666666}
.……
…….
] ],
"properties": {"window": 43200000, "resolution": 21600000, "rate": "minute"}
} ],
"columns": [
{"type": "array", "label": ["result"] },
{"type": "time_series", "label": "measure_value"}
]}

Getting Started

To help you get started with the API, we are providing a Python helper script and a client script which you can download here.

More information can also be found in our Query API documentation.

What’s Next?

We’d love to get feedback regarding your experience with the API and how you’re using it.  Please leave your comments below, contact your Support representative, or send email to help@interana.com.