Series

A Series allows you to analyze trends in Metrics over time. It breaks a timeframe into intervals of hours, days, or weeks, and returns Metrics (numbers) for each of those intervals.

Creating a series request is done by simply adding the Timeframe and Interval query string parameters to a Metric request. If you are already using a timeframe with a Metric, you only need to add the Interval query string parameter to turn your Metric into a Series. Pretty cool, huh?

Check out the documentation for Intervals to learn more and see valid values.

Here’s an example that counts the number of purchases events we have recorded for each day for the previous 3 days.

https://api.keen.io/3.0/projects/<project_id>/queries/count?api_key=<read_key>&event_collection=purchases&interval=daily&timeframe=previous_3_days

The output of a Series request is an array of JSON dictionaries which include the value for each interval in the timeframe. Here is what the output looks like in our example:

{
    "result":[
        {
            "value": 12,
            "timeframe": {
                "start": "2012-08-05T00:00:00",
                "end": "2012-08-06T00:00:00"
            }
        },
        {
            "value": 6585,
            "timeframe":{
                "start": "2012-08-06T00:00:00",
                "end": "2012-08-07T00:00:00"
            }
        },
        {
            "value": 3586,
            "timeframe": {
                "start": "2012-08-07T00:00:00",
                "end": "2012-08-08T00:00:00"
            }
        },
    ]
}

As you might have noticed, the series output forms the data set for a basic bar chart or line graph.

Please note that there is a limitation on the number of result data points for a single Series query. The current limit is 2,500. That means your specified interval and timeframe can’t have more than 2,500 buckets or “sub-timeframes”.

For example, running a Series with an “minutely” interval over the timeframe “previous_1_week” would produce an analysis query with 24 hours x 60 minutes x 7 days = 10,080 sub-timeframes. You will get an error about having too many sub-timeframes. If you run the same query with a “hourly” interval and timeframe of “previous_1_week” you would have 24 sub-timeframes per day and a total of 7 sub-timeframes. Easily under the limit.

Here are some example questions you could answer with a Series:

  • How many times was content shared in the previous 24 hours? When was the most popular time to share?
  • How much revenue was generated for each of the past 8 weeks?
  • Is the usage of our new feature increasing?
  • How many users signed up each day in the previous week?

So, what are you waiting for? It only takes a few minutes and a few lines of code to start collecting the events that really matter to you.

Sign Up Free