API Calls

API Calls can be tricky to get right. This thread is to help bring information together that will help us either (a) solve problems or (b) make calls the correct way.

Recently a ticket was made asking for a tutorial on how to do the APIv2 Analytics cal (https://vanilla.freshdesk.com/a/tickets/73501).

I'm going to run through this using the Dashboard API Analytics dealie, because I know not everyone has postman - but the same principle would apply in both.

Pageviews:

​

Collection: I'm looking for 'page' here as that specifically targets the pageviews (each time a guest or registered user loaded up a page)

Start/End: These are the date ranges I'm looking at - I basically just picked a date in June 2019 to today's date in June 2020. Fairly self explanatory

Interval: You can set this to hourly, daily, weekly, monthly. This will be how the call ends up breaking down the analytics. I chose montly, so it's going to show me a month-by-month breakdown of pageviews

Type: Count - for this specific one, all I want to know is the exact number, so count will do that for me.

Result looks like:

Start / End are the dates - again, self-explanatory.

Value is the number of page views in that month.

----

a generic HowTo in building a query:

Here is a random example query I hold onto for reference; I've also re-ordered the properties so it makes more sense to me (the API doesn't care about the order):

{
  "collection": "page",
  "type": "count",
  "start": "2019-01-01",
  "end": "2019-12-31",
  "filters": [
    {
      "prop": "user.roleType",
      "op": "eq",
      "val": "member"
    }
  ],
  "group": "url"
}

1. Start with the Collection as it's the main/highest form of organization for the analytics data.

2. I like to add Type second so I can remember I'm simply getting a number, or a set of numbers. Some of these can be a bit confusing in certain situations, like count_unique: https://success.vanillaforums.com/kb/articles/38-advanced-analytics#questions-answered-difference-total-count-the-chart-user-leaderboard .

3. Start and End are pretty straightforward, you just have to work with the strict formatting; however, you can exempt the time and just use the date. ex: yyyy-mm-dd OR yyyy-mm-ddThh:mm:ss

4. Filters! These are how you dial down into more specific data. There are 3 main portions: the property "prop", the operator "op", and the value "val". For the example above you can basically translate it to English as "The User's Role equals Member" or "user.role = member", which will make the query only return results associated with Users of the Member role. Note: There are a handful of properties within the doc, but there are hundreds (if not thousands) that are only listed within Keen, which is restricted to pretty much devs only. And they're fairly hard to guess from my experience.

5. Group​ & Interval(Optional): These are both used for grouping results and are not necessary to run a query. As Andrew explained the Interval is used for grouping results by time, but Group can be used to specify various things based on the Collection. In the example above the Group is set to URL since the Page Collection is for counting page views. The results will look like the following:

6. Property(Optional): I'm not actually sure how this is used.

Additional Notes:

-When the docs refer to a type within a collection they are referring to a filter value of "type". 

This would be a filter within a query that looks like this:

"filters": [
    {
      "prop": "type",
      "op": "eq",
      "val": "answer_accepted"
    }
  ]

-However, when the doc refers to properties within a collection they are referring to a filter with a property "prop" of those listed:

This would be a filter within a query that specifies only querying data for a specific user (System's userID in this case):

"filters": [
    {
      "prop": "user.userID",
      "op": "eq",
      "val": "1"
    }
  ],