Analytics API

Analytics API

The Staffbase API is available under the URI https://backend.staffbase.com/api/. For sending requests to the resources described here please add the desired resource to the end of this base path, e.g. the absolute URI for the /posts-resource will be https://backend.staffbase.com/api/posts.

If your app is hosted on our German infrastructure, please use https://de.staffbase.com/api/ as base URI for all requests.

All end points for our Analytics API require authentication. To learn how authentication works with the Staffbase API please consider the authentication section.

/branch/analytics

If you would like to access the analytics API then please contact your account manager.

/branch/analytics/contents

/branch/analytics/contents/rankings

GET

Get rankings for content regarding visits and visitors for a specified period of time. Group and filter the rankings by desired properties. Entities are separated from rankings as there are likely multiple rankings related to each entity.

Query Parameters

since datetime  default: current time minus one hour

Requested period start. Must be before current time.

until datetime  default: current time plus one hour

Requested period end. Must be after “since” parameter.

timezoneOffset number 

UTC timezone offset in minutes

filter string 

Filter for content in SCIM notation. Available properties to filter: appVersion, browser, contentId, contentType, groupId, public, platform, os, spaceId, visitorId, visitType

groupBy string  default: contentId,contentType,spaceId,public

Array of properties the results should be grouped by.

format string  default: json

(json, csv)

Response format.

language string 

(all, en_US, de_DE, ru_RU, …)

Desired language for supporting localization. If a parameter is not provided or no localization is found, first found localization will be used.

Responses

200 OK

Returns content rankings with each content’s context.

Example:

{
  "ranking": [
    {
      "group": {
        "contentId": "58f0ceeee4b0c5466ed67000",
        "contentType": "chat",
        "spaceId": "56a6306f0cf23b042e0ae000",
        "public": true
      },
      "registeredVisitors": 2,
      "registeredVisits": 33,
      "unregisteredVisitors": 4,
      "unregisteredVisits": 12
    },
    {
      "group": {
        "contentId": "58f0ceeee4b0c5466ed67000",
        "contentType": "newsPage",
        "spaceId": "5afada760a09a2503e8cd000",
        "public": false
      },
      "registeredVisitors": 2,
      "registeredVisits": 3,
      "unregisteredVisitors": 4,
      "unregisteredVisits": 12
    }
  ],
  "entities": {
    "contents": {
      "58f0ceeee4b0c5466ed67000": {
        "title": "contents 1",
        "id": "58f0ceeee4b0c5466ed67000"
      }
    },
    "spaces": {
      "56a6306f0cf23b042e0ae000": {
        "name": "space 1",
        "id": "56a6306f0cf23b042e0ae000"
      },
      "5afada760a09a2503e8cd000": {
        "name": "space 2",
        "id": "5afada760a09a2503e8cd000"
      }
    }
  }
}

Example:

"registered visitors","registered visits","unregistered visitors","unregistered visits","content id"              ,"content type","space id"                ,"public","contents"            ,"space name"
3                    ,43                 ,19                     ,119                  ,"58f0ceeee4b0c5466ed67000","chat"        ,"56a6306f0cf23b042e0ae000",true    ,"this is Chat"        ,"space 1"
53                   ,122                ,4                      ,61                   ,"5afadaa9ea2d159e52441000","newsPage"    ,"5afada760a09a2503e8cd000",true    ,"Newspage number one1","space 2"

/branch/analytics/posts

/branch/analytics/posts/rankings

GET

Get rankings of posts regarding visits, visitors, comments, likes, and shares for a specified period of time. Group and filter the rankings by desired properties. Entities are separated from rankings as there are likely multiple rankings related to each entity.

Query Parameters

since datetime  default: current time minus one hour

Requested period start. Must be before current time.

until datetime  default: current time plus one hour

Requested period end. Must be after “since” parameter.

timezoneOffset number 

UTC timezone offset in minutes

filter string 

Filter for post activities in SCIM notation. Available properties to filter: action, postId, channelId, appVersion, platform, os, browser, groupId, notificationEmail, notificationPush, public, spaceId, visitorId, visitType.

groupBy string  default: postId,spaceId,channelId

Array of properties the results should be grouped by.

format string  default: json

(json, csv)

Response format.

language string 

(all, en_US, de_DE, ru_RU, …)

Desired language for supporting localization. If a parameter is not provided or no localization found, first found localization will be used.

Responses

200 OK

Returns post rankings with each post’s context.

Example:

{
  "ranking": [
    {
      "group": {
        "postId": "5ac29bb4ea2d152cbed31000",
        "spaceId": "56a6306f0cf23b042e0ae000",
        "channelId": "5a21ca65e4b018c4eede8000"
      },
      "visits": 12,
      "visitors": 1,
      "likes": 0,
      "comments": 0,
      "shares": 0
    },
    {
      "group": {
        "postId": "5afadadcea2d159e52441730",
        "spaceId": "5afada760a09a2503e8cd000",
        "channelId": "5afadab10a09a2503e8cd000"
      },
      "registeredVisitors": 14,
      "registeredVisits": 132,
      "unregisteredVisitors": 93,
      "unregisteredVisits": 445,
      "likes": 1,
      "comments": 0,
      "shares": 0
    }
  ],
  "entities": {
    "posts": {
      "5ac29bb4ea2d152cbed31000": {
        "title": {
          "de_DE": "post de"
        },
        "id": "57f5698ee4b037cb898691e5"
      },
      "5afadadcea2d159e52441730": {
        "title": {
          "en_US": "Unread test"
        },
        "id": "59e0cdd3e4b07faf91b76386"
      }
    },
    "spaces": {
      "56a6306f0cf23b042e0ae000": {
        "name": "space 1",
        "id": "56a6306f0cf23b042e0ae000"
      },
      "5afada760a09a2503e8cd000": {
        "name": "space 2",
        "id": "5afada760a09a2503e8cd000"
      }
    },
    "installations": {
      "5a21ca65e4b018c4eede8000": {
        "title": {
          "de_DE": "Nein"
        },
        "id": "5a21ca65e4b018c4eede8000"
      },
      "5afadab10a09a2503e8cd000": {
        "title": {
          "en_US": "Nine"
        },
        "id": "5afadab10a09a2503e8cd000"
      }
    }
  }
}

Example:

"post id"                 ,"space id"                ,"channel id"              ,"post title","space name"   ,"channel name"     ,"registered visitors","registered visits","unregistered visitors","unregistered visits","comments","likes","shares"
"5ac29bb4ea2d152cbed31000","56a6306f0cf23b042e0ae000","5a21ca65e4b018c4eede8000","post 1"    ,"All employees","This is a channel",1                    ,12                 ,99                     ,123                  ,0         ,0      ,0
"5afadadcea2d159e52441000","5afada760a09a2503e8cd000","5afadab10a09a2503e8cd000"," post 2"   ,"second space" ,"Channel 1"        ,1                    ,2                  ,5                      ,123                  ,0         ,1      ,0

/branch/analytics/posts/timeseries

GET

Get rankings for the posts regarding visits, visitors, comments, likes, shares for specified period of time. Group the rankings by provided interval and filter by desired properties.

Query Parameters

since datetime  default: current time minus one hour

Requested period start. Must be before current time.

until datetime  default: current time plus one hour

Requested period end. Must be after “since” parameter.

timezoneOffset number 

UTC timezone offset in minutes

filter string 

Filter for post activities in SCIM notation. Available properties to filter: action, postId, channelId, appVersion, platform, browser, groupId, notificationEmail, notificationPush, public, spaceId, visitorId, os, visitType.

groupBy string  default: year

(year, month, day, hour)

Interval used to group the results.

format string  default: json

(json, csv)

Response format.

Responses

200 OK

Returns post rankings grouped by interval.

Example:

[
  {
    "group": {
      "year": 2018,
      "month": 6
    },
    "visits": 14,
    "visitors": 1,
    "likes": 0,
    "comments": 0,
    "shares": 0
  },
  {
    "group": {
      "year": 2018,
      "month": 7
    },
    "visits": 39,
    "visitors": 4,
    "likes": 5,
    "comments": 14,
    "shares": 0
  }
]

Example:

"year","month","visitors","visits","comments","likes","shares"
2018  ,6      ,1         ,14      ,0         ,0      ,0
2018  ,7      ,4         ,39      ,14        ,5      ,0⏎

/branch/analytics/users

/branch/analytics/users/timeseries

GET

Get rankings for user activities measured as active users, engaged users, comments, likes, and shares for a specified period of time. Group the rankings by an interval and filter by desired properties. Active users are users who have logged in to the app. Engaged users are users who have commented, liked or shared within the app.

Query Parameters

since datetime  default: current time minus one hour

Requested period start. Must be before current time.

until datetime  default: current time plus one hour

Requested period end. Must be after “since” parameter.

timezoneOffset number 

UTC timezone offset in minutes

filter string 

Filter for user activities in SCIM notation. Available properties to filter: userId, action, appVersion, platform, os, browser, groupId, spaceId, status, creationType

groupBy string  default: year

(year, month, day, hour)

Interval used to group the results.

format string  default: json

(json, csv)

Response format.

Responses

200 OK

Returns user rankings grouped by interval.

Example:

[
  {
    "group": {
      "year": 2018,
      "month": 6
    },
    "visits": 14,
    "visitors": 1,
    "likes": 0,
    "comments": 0,
    "shares": 0
  },
  {
    "group": {
      "year": 2018,
      "month": 7
    },
    "visits": 39,
    "visitors": 4,
    "likes": 5,
    "comments": 14,
    "shares": 0
  }
]

Example:

"year","month","day","Active Users","Engaged Users","likes","comments","shares"
2018  ,7      ,12   ,17            ,6              ,1      ,2         ,3
2018  ,7      ,11   ,25            ,8              ,8      ,0         ,0
2018  ,7      ,16   ,18            ,5              ,3      ,2         ,0

/branch/analytics/chats

/branch/analytics/chats/timeseries

GET

Get rankings for chat regarding active chat users, active direct conversations, active group conversations for a specified period of time. Group the rankings by an interval. Active chat users have opened one or more conversations. Active direct conversations are one to one conversations with at least one new message. Active group conversations are group conversations with at least one new message.

Query Parameters

since datetime  default: current time minus one hour

Requested period start. Must be before current time.

until datetime  default: current time plus one hour

Requested period end. Must be after “since” parameter.

timezoneOffset number 

UTC timezone offset in minutes

groupBy string  default: year

(year, month, day, hour)

Interval used to group the results.

format string  default: json

(json, csv)

Response format.

Responses

200 OK

Returns chat rankings grouped by interval.

Example:

[
  {
    "activeChatUsers": 1,
    "activeDirectConversations": 1,
    "activeGroupConversations": 0,
    "group": {
      "month": 5,
      "year": 2017
    }
  },
  {
    "activeChatUsers": 2,
    "activeDirectConversations": 1,
    "activeGroupConversations": 0,
    "group": {
      "month": 6,
      "year": 2017
    }
  }
]

Example:

"year","month","active chat users","active direct conversations","active group conversations"
2017  ,5      ,1                  ,1                            ,0
2017  ,6      ,2                  ,1                            ,0