Voimmeko auttaa?

Jätä yhteystietosi, otamme sinuun yhteyttä.

Analytics services full notation guide

*Mandatory element

 

account*

Name of a Snoobi account.

 

details

If the details should be included in the response structure. The details include e.g. the datatypes for the metrics. This is an optional element defaulting to false.

 

metrics*

Json array of the metrics (i.e. the columns in a table formatted data) that should be included in the response structure. This is an mandatory element, where at least one metric should be defined. The metrics list for each analytics service can be found under the service documentations.

 

start_date*

The start date in the W3C Recommendation format of datetime (W3C Recommendation, 28 October 2004) (concatenated string with date and time in following form: ”year-month-day””T””hours:minutes:seconds” ). The time portion is optional and is not supported by the facebook_analytics service. This is a mandatory element.

 

end_date*

The end date in the W3C Recommendation format of datetime (W3C Recommendation, 28 October 2004) (concatenated string with date and time in following form: ”year-month-day””T””hours:minutes:seconds” ). The time portion is optional and is not supported by the facebook_analytics service. This is a mandatory element.

 

group_by

Json array of the dimension(s) to group the results by (i.e. the rows in a table formatted data). The dimension list for each analytics service can be found under the service documentations. This is an optional element that can contain one or more dimension.

 

limit

How the amount of results should be limited. By default, the results are limited to a maximum of 1000 rows per request, if the row count should exceed that. To get to the result rows beyond the initial 1000 rows, you can define the limit ”from” and ”to” values. This is an optional element.

"limit": {
      "from": 1001,
      "to": 2000
   }

criteria and logic

Criteria can be used to limit the results to visits who meet the defined criteria. ”criteria” is an optional element consisting of one or more criterion elements given as an json array

"criteria": []

 

Defining criterion elements: Each criterion must be given as a json object. Inside each json object you must define the name of one dimension, such as section, goal, country etc. The value for this dimension can be set as a textual value e.g. ”value”: ”Google” or as an id e.g. ”id”: ”3”. With the values, you can also define partial matches use wildcards. Both * (asterisk) and % (percentage sign) charachters act as wildcards.

"criteria": [
   {
      "name": "search_engine",
      "value": "%Google*"
   }
]

 

"criteria": [
   {
      "name": "section",
      "id": "3"
   }
]

 

Defining logic between criterion elements By default, multiple criterion elements are considered as AND-conditions. If you wish to change this logic, you can define an optional ”logic” json array containing accepted boolean operators (AND/OR) that will be applied between criterion elements. E.g.

{
    "criteria": [
        {
            "name": "section",
            "value": Finland
        },
        {
            "name": "section",
            "value": Sweden
        }
    ],
    "logic": [
        "OR"
    ]
}

 

The criterion object can also have an optional element called ”type”. If the type is omitted, it is defaulted to ”include”, i.e. visits meeting this criterion will be included in the results. With the type parameter you can also define excluding rules,

{
    "criteria": [
        {
            "name": "search_engine",
            "value": "Google"
        },
        {
            "name": "section",
            "value": "Finland%",
            "type": "include"
        },
        {
            "name": "section",
            "value": "Sweden",
            "type": "exclude"
        }
    ],
    "logic": [
        "OR",
        "AND"
    ]
}

 

These logic conditions and the criteria in general are applied in the same order as the criterion elements are defined in. The following criteria definition could then be read as: give me (metric x) from users that came from search engine Google or that visited sections with a name starting with the word  Finland, but that have not visited the section Sweden. It can also be read as: ( ( condition1 OR condition2 ) AND NOT condition3 ).

If there are less elements inside the ”logic” element array than there are criterion elements, AND-condition is applied for the rest. If there are more elements inside the ”logic” element array than there are criterion elements, the extra ones will be ignored.

filters

Filters provide a way to search for/cherry pick relevant elements/rows from result set. Filters is a json array containing one or more filter elements defined as a json object. Each filter object must have a ”type” element stating whether the result rows matching this rule should be included or excluded from the response. The filter object must also include either a value or id to filter by. By default, the filtering is done based on the first non-time related dimension. If however a name element is defined, the filtering can be set to be done based on other non-time related dimension or even metrics. The dimension or metrics that the filtering is done by must be defined inside either the ”metrics” or ”group_by” arrays. Filtering with metrics values is only supported for web_analytics service.  This is an optional element.

 

"filters": [
        {
            "type": "<exclude|include>",
            "<value|id>": "<dimension value|dimension id>"
        },
        {
            "name": "<metric name|dimension name>",
            "type": "<exclude|include>",
            "<value|id>": "<metric value|dimension value|dimension id>"
        }
    ]

Full payload syntax example

{
    "account": "<your_snoobi_account>",
    "details": true,
    "metrics": [
        "<metric_1>",
        "<metric_2>",
        "<metric_3>"
    ],
    "start_date": "<yyy-mm-dd(Thh:mm:ss)>",
    "end_date": "<yyy-mm-dd(Thh:mm:ss)>",
    "group_by": [
        "<dimension_1>",
        "<dimension_2>"
    ],
    "limit": {
        "from": 10,
        "to": 200
    },
    "criteria": [
        {
            "name": "<dimension_3>",
            "<value|id>": "<dimension value|dimension id>"
        }
    ],
    "filters": [
        {
            "type": "<exclude|include>",
            "<value|id>": "<dimension value|dimension id>"
        },
        {
            "name": "<metric name|dimension name>",
            "type": "<exclude|include>",
            "<value|id>": "<metric value|dimension value|dimension id>"
        }
    ],
    "sort_by": {
        "value": "<metric or dimension>",
        "direction": "<asc|desc>"
    }
}

Response syntax example

{
   "details": {
      "account": "<your_snoobi_account>",
         "metrics": [
         {
            "metric": "<metric_1>",
            "datatype": "<integer|string|float|boolean|currency|percentage|duration|time|datetime>"
         },
         {
            "metric": "<metric_2>",
            "datatype": "<integer|string|float|boolean|currency|percentage|duration|time|datetime>"
         },
         {
            "metric": "<metric_3>",
            "datatype": "<integer|string|float|boolean|currency|percentage|duration|time|datetime>"
         }
      ],
      "start_date": "<yyy-mm-dd(Thh:mm:ss)>",
      "end_date": "<yyy-mm-dd(Thh:mm:ss)>",
      "group_by": [
         "<dimension_1>",
         "<dimension_2>"
      ],
      "limit": {
         "from": 10,
         "to": 20
      },
      "criteria": [
         {
            "name": "<dimension_3>",
            "<value|id>": "<dimension value|dimension id>"
         }
      ],
      "filters": [
         {
            "type": "<exclude|include>",
            "<value|id>": "<dimension value|dimension id>"
         },
         {
            "name": "<metric name|dimension name>",
            "type": "<exclude|include>",
            "<value|id>": "<metric value|dimension value|dimension id>"
         }
      ],
      "sort_by": {
         "value": "<metric or dimension>",
         "direction": "<asc|desc>"
      }
   },
   "data": [
       {
           "<dimension_1>": "<formatted time (time related dimension)>"
           "<dimension_2_id>": "<dimension id (non-time related dimension)>",
           "<dimension_2_value>": "<dimension value (non-time related dimension)>",
           "<metric_1>": "<metric value>",
           "<metric_2>": "<metric value>",
           "<metric_3>": "<metric value>"
       },
       {
           "<dimension_1>": "<formatted time (time related dimension)>"
           "<dimension_2_id>": "<dimension id (non-time related dimension)>",
           "<dimension_2_value>": "<dimension value (non-time related dimension)>",
           "<metric_1>": "<metric value>",
           "<metric_2>": "<metric value>",
           "<metric_3>": "<metric value>"
       }
       ....
    ]
}