Enter your search

API update: Custom dates for Trends

Dimensions can now be queried using a date range defined by you

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:


  "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.


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


  • 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.

Written by
Geoff is the CTO and co-founder of GoSquared. He's the master of AWS and looks after all back-end services under the hood of GoSquared.

You May Also Like

Group 5 Created with Sketch. Group 11 Created with Sketch. CLOSE ICON Created with Sketch. icon-microphone Group 9 Created with Sketch. CLOSE ICON Created with Sketch. SEARCH ICON Created with Sketch. Group 4 Created with Sketch. Path Created with Sketch. Group 5 Created with Sketch.