API update: Custom dates for Trends

When we re-launched our homepage last month with the headline ‘easy to use real-time web analytics’, we weren’t simply referring to the dashboards our customers use everyday. We’ve always taken great pride in providing APIs that are similarly a joy to use.

For the non-engineers reading this post, API stands for application programming interface and it puts the power of our analytics engine in the hands of anyone who wants to develop with it. While this post will primarily be of interest to GoSquared developers, anyone can get started using our APIs, for example to extract historical data with live examples in our documentation.

Since launching V2 of our Trends API last October, we’ve had tons of great feedback from the community. We’re thrilled to hear that our customers love the API for its speed, developer-friendly structure and powerful data resource. We want to support developers using the API as much as possible and there was one niggling limitation that has been cropping up in feedback.. The greatest limitation with the current Trends API has been the inability to query dimension data for a custom time period (except for the “aggregate” dimension, which was supported).

As a reminder, in Trends a dimension is a bunch of metrics broken down by a certain attribute. So, for example, you might have total website visits broken down by browser, and that would look like the following:

https://api.gosquared.com/trends/v2/browser?api_key=demo&site_token=GSN-106863-S&limit=3

{
  "list": [{
    "id": "chrome",
    "browser": "chrome",
    "metrics": {
      "visits": 245618
    }
  }, {
    "id": "firefox",
    "browser": "firefox",
    "metrics": {
      "visits": 45777
    }
  }, {
    "id": "mobilesafari",
    "browser": "mobilesafari",
    "metrics": {
      "visits": 37816
    }
  }],
  "cardinality": 27,
  "dimension": "browser",
  "range": {
    "from": "2014-06-02T00:00:00",
    "to": "2014-06-09T23:59:59"
  },
  "interval": "day"
}

The News

I’m glad to announce that we have implemented custom time period querying on all dimensions, now live on the Trends API.

Usage

To control the start and end time for the query, include the from and to parameters in the request. For example:

http://api.gosquared.com/trends/v2/browser?api_key=demo&site_token=GSN-106863-S&from=2014-04-01&to=2014-05-23

• If you omit the to parameter, it will default to latest.
• If both params are omitted, the default period is the current week, like before.
• The smallest granularity is ‘day’, so changing the timestamps at a more granular level (e.g. ‘hour’) won’t change the query period.
• The time range being queried will be sent back in the response under the “range” object, so you know exactly what period the data represents.

Peruse the developer docs for everything you need to know about the API and harnessing its capabilities.