# Statistics

The Statistics API allows you to analyze multiple metrics with one request.

POST https://api.smartsupp.com/v2/statistics?timezone=Europe/Prague
{
  "responseTime": {
    "name": "response_time",
    "range": {
      "from": "2020-08-03T00:00:00",
      "to": "2020-09-02T23:59:59"
    }
  },
  "closed": {
    "name": "closed_conversation",
    "range": {
      "from": "2020-08-03T00:00:00",
      "to": "2020-09-02T23:59:59"
    }
  }
}

In the previous example we fetch data for metrics the response_time and the closed_conversation. Properties new and closed are your custom names. Basically the request is the key-value object.

Parameter timezone

Setup the timezone is important to get correct data especially for date ranges and date aggregations. Default timezone is UTC.

Let's go deeper to learn how to configure options.

{
  "name": "response_time",
  "range": {
    "from": "2020-08-03T00:00:00",
    "to": "2020-09-02T23:59:59"
  }
}

The above options compute response time median. The property name specify a metric you want to analyze. The above will return the following:

{
  "name": "response_time",
  "value": 24,
  "count": 1300,
  "buckets": null
}

The result always contains the count of all matching objects and the value as the aggregated value of all matching objects. For the metric response_time is used as aggregation median, but others metrics can have different aggregations.

# Metrics

Every metric is related to Message or Conversation object which later allows you to filter the data with filters based on them. The metric also defines witch an aggregation is used. You can chose one of the following:

Name Source Agg Description
response_time Message median
first_response_time Message median
time_to_close Conversation median
time_to_close_sum Conversation sum
new_conversation Conversation count
closed_conversation Conversation count
conversation_ratings Conversation count

# Aggregations

The aggregations help you retrieve aggregated data divided into buckets where each bucket is associated with a key and the aggregated value. We support two types of aggregations. The date aggregating into date based intervals and the terms aggregating into value based intervals.

{
  "new_by_date": {
    "name": "response_time",
    "range": {
      "from": "2020-08-03T22:00:00",
      "to": "2020-09-02T21:59:59"
    },
    "aggs": [
      {
        "type": "date",
        "interval": "day",
        "format": "YYYY_MM_DD"
      }
    ]
  }
}

The above options compute response time median but to compare with previous example the response contains buckets as result of the aggregation. Each bucket contains the count of all matching objects and the value as the aggregated value. The above will return the following:

{
  "new_by_date": {
    "name": "response_time",
    "value": 35,
    "count": 4538,
    "buckets": [
      {
        "key": "2020_08_04",
        "count": 119,
        "value": 25
      },
      {
        "key": "2020_08_05",
        "count": 212,
        "value": 33
      },
      ...
}

# Date aggregation

As the interval you can use of the following: day, week, month, year, day_of_week and hour_of_day. The format is up to you and must compatible with Moment.js.

Example:

{
  "aggs": [
    {
      "type": "date",
      "interval": "day",
      "format": "YYYY_MM_DD"
    }
  ]
}

# Terms aggregation

The field is basically any property of the source object. Which source object is used was described in the Metrics Overview above.
All object properties you can find in Swagger UI.

Example:

{
  "aggs": [
    {
      "type": "terms",
      "field": "agentId"
    }
  ]
}

# Multiple aggregation

Aggregations can be combined.

Example:

{
  "aggs": [
    {
      "type": "date",
      "interval": "day_of_week"
    },
    {
      "type": "date",
      "interval": "hour_of_day"
    }
  ]
}