Have a question?

Analytics API

Important: Read the introduction before proceeding.

Analytics API Endpoint

http(s)://www.woopra.com/rest/report

Parameters

Required Name Description
required website string e.g. mybusiness.com
required report JSON object report object-read below
required date_format string date format
required start_day string query start day
required end_day string query end day
optional segments JSON array segments array
required limit number max number of records to return
required offset number records to skip

Example Using jQuery


$.ajax({
    type: 'POST',
    url: 'https://www.woopra.com/rest/report',
    crossDomain: true,
    dataType: "json",
    jsonp: false,
    cache: false,
    beforeSend: function (xhr) {
        xhr.setRequestHeader('X-Api-Version', '2.0');
        xhr.setRequestHeader('X-Access-Id', 'Z37C945JW4KF9U6P3BMTMOKNLWH9K4X5');
        xhr.setRequestHeader('X-Access-Secret', 'hpnyN6YuQJYAc9X9sZW7Up4FyOXurKNicbUnh5NZrWZv5VoOXlDF3hS5fSQe4cem');
    },
    data: {
        request: JSON.stringify({
            "website": "mybusiness.com",
            "date_format": "MM/dd/yyyy",
            "start_day": "01/01/2013",
            "end_day": "02/21/2013",
            "limit": 100,
            "offset": 0,
            "report": {
                "group_by": [{
                    "key": "country",
                    "scope": "visits"
                }],

                "columns": [{
                    "name": "Total Actions",
                    "method": "count",
                    "scope": "actions"
                }]
            }
        })

    }
});

It is recommended to use the web application’s reporting at www.woopra.com/live to build and tune reports. The resulting JSON for the report object can be then viewed by clicking the report settings (top right corner), and selecting View as JSON. The selected JSON can be seamlessly used in the API calls.

Report Scopes

There are three possible scopes in woopra: visitors, visits and actions. The scopes provide better granularity when pushing events and when querying the data.
visitors: evaluate once per visitor
visits: evaluate once every new visit
actions: evaluate on every action

Group By

group_by – JSON array of { scope, key } objects to group the rows. Scope can be one of the values below:

Order By

order_by – the column name to sort by (sort by the group_by element by default).

Column Methods

Column method can be either sum, count, copy or formula.

Columns with “method”: “count”

Used to count occurrence based on the scope. Requires: scope

Example count visitors:

"method": "count",
"scope": "visitors"

OR count actions:

"method": "count",
"scope": "actions"

Columns with “method”: “sum”

Sums by a field or a constant, based on the scope. Requires: scope, by

"method": "sum",
"by": "1",
"scope": "actions",

"method": "sum",
"by": "amount",
"scope": "actions"

Columns with “method”: “copy”

Often used for page title, copy columns are used to copy a visitor or an action property. If the property changes within a date range ( if the page title is dynamic ), the column will return the most recent.
requires: scope, src

Example page title:

"method": "copy",
"src": "title",
"scope": "actions"

Example visitor’s country:

"method": "copy",
"src": "country",
"scope": "visits"

Columns with “method”: “formula”

Formula columns are used to generate excel-like functionality, adding/substracting, calculating ratios etc…
The formula column should define a javascript function to generate the cell values.

"method": "formula",
"calc": "Math.round(cell('Actions')/cell('Visits'))",
"render": "number_format ( cell ('Forumla Name'),'##.##' ) "

Column Constraints

“constraints” is an JSON object containing an operator (AND/OR),
and a list of filters (scope, key, match, value).
If the constraints are not met, then the visit/action will be excluded from the report.
Example San francisco visits:

{
  "operator": "AND", 
  "filters":[
             { 
              "scope": "visits", 
              "key": "city", 
              "match": "contains", 
              "value": "San Francisco"
             },
             ...
  ]
}

Example goal page:

{
  "operator": "AND", 
  "filters":[
             { 
              "scope": "actions", 
              "key": "url", 
              "match": "contains", 
              "value": "thankyou.php"
             },
             ...
  ]
}

Rendering (advanced)

Cells in a report can be rendered using javascript syntax. Possible uses is to provide spreadsheet like functionality- percentages, sum, subtraction.. or simply to customize the text output of the cells.

To render the first cell in each row -the group_by element-

 'Country: '+ group_by(0)+', City: '+group_by(1)

To render the column cells

   100 * cell('Actions')/cell('Visits')+' Percent'

In addition to group_by(…) and cell(), there are many built-in JS function:


total() 

total( column name )

country_code_to_country_name( country_code )

number_format ( number, format )

date_format ( input date, format )



Complete working example

<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr">

    <head profile="http://gmpg.org/xfn/11">
   </head>


<body>

<script type="text/javascript" src="http://static.woopra.com/website/v4/js/jquery.1.7.2.js"></script>
<script type="text/javascript">
reportObject = {
    "group_by": [{
        "key": "day",
        "scope": "visits"
    }],

    "render": "'Rendered value for '+ group_by(0) ",
    "order_by": "Total Actions",
    "columns": [{
            "name": "Unique Visitors",
            "method": "count",
            "scope": "visitors",
            "render": " Math.round(cell('Unique Visitors')) "
        },
        {
            "name": "Page Views",
            "method": "count",
            "scope": "actions",
            "render": " Math.round(cell('Page Views')) "
        },
        {
            "name": "Page Views per Visitor",
            "method": "formula",
            "calc": "  cell('Page Views') / cell('Unique Visitors') "
        }
    ]
};

var segmentsArray = [{
    "are": {
        "operator": "AND",
        "filters": []
    },
    "did": {
        "operator": "AND",
        "filters": [{
            "aggregation": {
                "scope": "actions",
                "value": "1",
                "method": "count",
                "match": "gte"
            },
            "action": {
                "operator": "AND",
                "filters": [{
                    "scope": "actions",
                    "value": "transparent",
                    "match": "contains",
                    "key": "url"
                }]
            },
            "timeframe": {
                "method": "relative",
                "from": 29,
                "to": "0"
            },
            "visit": {
                "operator": "AND",
                "filters": []
            }
        }]
    }
}];


$.ajax({
    type: 'POST',
    url: 'http://www.woopra.com/rest/report',
    crossDomain: true,
    dataType: "json",
    jsonp: false,
    cache: false,
    beforeSend: function (xhr) {
        xhr.setRequestHeader('X-Api-Version', '2.0');
        xhr.setRequestHeader('X-Access-Id', 'Z37C945JW4KF9U6P3BMTMOKNLWH9K4X5');
        xhr.setRequestHeader('X-Access-Secret', 'hpnyN6YuQJYAc9X9sZW7Up4FyOXurKNicbUnh5NZrWZv5VoOXlDF3hS5fSQe4cem');
    },
    data: {
        request: JSON.stringify({
            report: reportObject,
            segments: segmentsArray,
            website: 'my-business.com',
            date_format: "MM-dd-yyyy",
            start_day: "04-12-2013",
            end_day: "04-29-2013",
            limit: 100,
            offset: 0
        })
    },
    success: function (response) {
        alert(JSON.stringify(response));
    }
});
</script>

</body>
</html>

Need any help? Contact our Data Jedis