The Woopra API

Contents

This document is under development. It currently only includes the Analytics Data Service.


Preview

The Woopra Data API allows programmers and third parties to read and write data from Woorpa servers. Currently, Woopra Data API includes the Analytics data port, more services and ports to be added soon (Live data, Logs Readers, Chat, Tagging etc.).

Woopra Data API implements a RESTful HTTP service, and a SOAP binding to process the client requests. This document contains the port names and method required to access the data.


SOAP binding

A web-standard SOAP implementation is available at:

http://api.woopra.com/v0/Service?wsdl

where <Service> is the name of the Woopra API Data Service, listed below.

Example:

Analytics endpoint: http://api.woopra.com/v0/Analytics?wsdl

Parameters descriptions are found in Basic Parameters below.


RESTful Http binding

Woopra Data API is also accessible through a RESTful interface.

Service endpoint:

http://api.woopra.com/<Service>/method.jsp?parameter1=value1&paramter2=value2...

Full Syntax:

http://api.woopra.com/<Service>/method.jsp?website=value1&api_key=value2&date_format=value3&start_day=value4&end_day=value5
&limit=value6&offset=value7&filters=value8

Note: <Service> is equivalent to the data service described in SOAP binding.

A real request URL might look like:

GET http://api.woopra.com/rest/analytics/getbrowsers.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=0&offset=0&filters=info.browser%3D%27firefox*%27

Continue reading the Analytics Service section below for all the available methods and parameters.


Basic Parameters

Required parameters:

SOAP

REST/Http

Description

website

website

The website you want to query:

api_key

api_key

Accessing the API data is different than accessing the desktop application. The member must provide their 10 character API Key string to authenticate your request. If the member's API key is changed, the GET request must be updated.

date_format

date_format

Your date format (Example: dd/MM/yyyy, dd-MM-yyyy or any possible combination)

start_day

start_day

starting day of the query. (should comply with date_format ex: 01/09/2009)

end_day

end_day

ending day of the query. (should comply with date_format ex: 13/09/2009)

limit

limit

Maximum number of results to be returned.

offset

offset

Number of results to skip before returning results.

filters

filters

More details soon.


Analytics Service


GLOBALS

Description: Visitors Overview

REST method name:

GETglobals

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getglobals.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


COUNTRIES

Description: Top Countries

REST method name:

GETcountries

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getcountries.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


CITIES

Description: Visitors Cities

REST method name:

GETcities

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getcities.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


VISIT BOUNCES

Description: Visitors Bounce Rate

REST method name:

GETvisitbounces

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getvisitbounces.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


VISIT DURATIONS

Description: Visits Duration

REST method name:

GETvisitdurations

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getvisitdurations.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


BROWSERS

Description: Top Browsers

REST method name:

GETbrowsers

Sample REST Request:

GET http://api.woopra.com//rest/analytics/getbrowsers.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


PLATFORMS

Description: Top Operating Systems

REST method name:

GETplatforms

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getplatforms.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


LANGUAGES

Description: Top Visitor Languages

REST method name:

GETlanguages

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getlanguages.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


SCREEN RESOLUTIONS

Description: Top Screen Resolution

REST method name:

GETresolutions

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getresolutions.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


PAGE VIEWS

Description: Most Viewed Pages

REST method name:

GETpageviews

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getpageviews.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


LANDING PAGES

Description: Top Landing Pages

REST method name:

GETpagelandings

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getpagelandings.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


EXIT PAGES

Description: Top Exit Pages

REST method name:

GETpageexits

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getpageexits.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


DOWNLOADS

Description: Top Downloads

REST method name:

GETdownloads

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getdownloads.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


OUTGOING LINKS

Description: Top Outgoing Links

REST method name:

GEToutgoinglinks

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getoutgoinglinks.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


REFERRER TYPES

Description: Top Referrer Types ( search, backlinks, direct, etc..)

REST method name:

GETreferrertypes

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getreferrertypes.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


REFERRERS

Description: Top Referring URLs.

REST method name:

GETreferrers

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getreferrers.jsp?website=woopra.com&api_key=1FPXGZUJ34&type=search&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

type

type

Specify the type of referrers you want to query. 'type' can be any value of the following (search|socialnetwork|socialbookmarks|community|media|news|feeds|email|alllinks)

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


KEYWORDS

Description: Top Keywords

REST method name:

GETkeywords

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getkeywords.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


QUERIES

Description: Top Search Queries

REST method name:

GETqueries

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getqueries.jsp?website=woopra.com&api_key=1FPXGZUJ34&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


CUSTOM VISITOR DATA

Description: Visitors' custom data ( as generated on the website, or when the visitor is tagged )

REST method name:

GETcustomvisitordata

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getcustomvisitordata.jsp?website=woopra.com&api_key=1FPXGZUJ34&aggregate_by=name&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

aggregate_by

aggregate_by

Specify the key to aggregate results. ex: name, gender, etc.

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


CUSTOM EVENTS

Description: Custom events generated on the website.

REST method name:

GETcustomevents

Sample REST Request:

GET http://api.woopra.com/rest/analytics/getcustomevents.jsp?website=woopra.com&api_key=1FPXGZUJ34&aggregate_by=login&date_format=dd/MM/yyyy&start_day=01/10/2009
&end_day=10/10/2009&limit=100&offset=0&filters=

Required parameters:

SOAP

REST/Http

Description

website

website

See Basic Parameters

api_key

api_key

See Basic Parameters

aggregate_by

aggregate_by

Specify the key to aggregate results. ex: conversion, registration, purchase, etc.

date_format

date_format

See Basic Parameters

start_day

start_day

See Basic Parameters

end_day

end_day

See Basic Parameters

limit

limit

See Basic Parameters

offset

offset

See Basic Parameters

filters

filters

See Basic Parameters


Filters


Syntax

The following is the syntax for filters with the Woopra API:

  • Filters narrow down to the results to your specific request.
  • A filter consists of 2 parts: filter name and filter value. For example: ie_users: info.browser='*explorer*', _users: info.browser='**'
  • Filters are supported in analytics queries, log search, and live events. For example, info.country='US' will ignore all visits from countries other than US.
  • Boolean Operators (AND,OR): If you are interested about US visitors who are using windows 7 platform only, your filter will be:
  • Nested expressions are allowed. For example: info.country='US' AND (info.os='windows 7' OR info.os='windows xp')
  • Wildcard characters '*' are allowed in a filter, for example: info.browser='*' will return all visitors using 2 and 3, etc..
  • Combining all of the above is allowed.

Example:

info.browser = 'firefox*' AND visit.actions > '10'

This displays the analytics of your website based on the visitors who used any version of Firefox and have visited more than 10 pages on your site.


Filters Variables

We've listed a wide variety of filters to help you extract any data that comes to your mind with Woopra. Here are the filters variables that you can use:

  • info.ip
  • info.city
  • info.country
  • info.lang
  • info.browser
  • info.os
  • info.screen
  • info.long
  • info.lat
  • info.domain
  • info.org
  • visit.actions
  • visit.time
  • visit.duration
  • visit.referrertype
  • visit.referrerquery
  • visit.referrerurl
  • firstvisit.time
  • firstvisit.referrertype
  • firstvisit.referrerquery
  • firstvisit.referrerurl
  • visitor.id
  • visitor.totalvisits
  • visitor.totalpageviews
  • visitor.totaltime
  • visitordata.*
  • actions.first|last|any.*


Filters Examples

The following are filter examples.

Search for Visitors by Location

This example helps you search for visitors from a certain area in the world.

info.long < "37.43" AND info.long > 34.23" AND info.lat < "120.32" AND info.lat > 115.6"

Visitor From Search Placed Order

This example shows a vist by a visitor who arrived originally via an organic search, and placed an order for more than $100.

actions.first.url = "/welcome.html"
actions.any.comment = "*"
firstvisit.referrertype = "search" AND ( action.any.type = "purchase" AND action.any.checkoutprice > "100")