Have a question?

Search API

Important: Read the intro before proceeding.

Retrieves a list of visitor profiles based on data and/or behavior.

Endpoint

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

Parameters

Required Name Type Description
required website String ex: my-business.com
required limit Number max number of records (Default 50)
required offset Number Records to skip (Default 0)
required date_format String Format of your start and end dates e.g. yyyy-MM-dd (refer to Java’s date formats)
optional start_day String Query start day
optional end_day String Query end day
optional search String String to match any custom data
optional segments Array List of filters. Refer to the Filter Object Documentation
optional report_id Number Use the response’s “id” for scrolling/paging (When Default -1 is used, it will load the report based on the parameters)

Example in jQuery

An Example of how to request results for Bob Martin via Javascript and JQuery.


$.ajax({
        type: 'POST',
        url: 'https://www.woopra.com/rest/search',
        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',
                limit: 50,
                offset: 0,
                date_format: "dd-MM-yyyy",
                start_day: "23-09-2012",
                end_day: "22-10-2012",
                search: 'Bob Martin',
                segments: [],
                report_id: -1
            })
        });

Response

{
    id: “report - id”
    total: "total number of unique visitors matching the segment"
    visitors: [{
        lastSeen: 1354136535272,
        pid: "2088683270",
        info: {
            os: 'Mac OS X',
            browser: 'Safari',
            ...
        },
        custom: {
            username: "teddyb",
            email: "delivertobob@gmail.com",
            name: "Bob Martin",
            avatar: "http://www.gravatar.com/...."
        }
    }]
}

2. Profile

Retrieves a detailed visitor profile.

Endpoint

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

Parameters

Required Name Description
required website e.g. mydomain.com
required email String Email address associated with profile
required date_format String Format of your start and end dates e.g. dd-MM-yyyy (refer to Java’s date formats)

* Un-identified visitors can be looked up using the profile ID ( woopra generated ID that is returned with every visitor profile when searching for visitors at /rest/search ) or by cookie ( the wooCookie value in the browser ),
This can be done by replacing the email in the GET request by cookie=theCookie for cookie-based lookups and pid=theProfileID for ID-based requests.

Example in jQuery

$.ajax({
        type: 'POST',
        url: 'https://www.woopra.com/rest/profile',
        data: {
            request: JSON.stringify({
                website: "mybusiness.com",
                email: "bob@martin.com",
                date_format: "MM/dd/yyyy"
            })
        });

Response

{
    /* list of actions performed as key, number of actions as value */
    summary: {
        labels: 2,
        chat: 9,
        pageview: 1045
    },
    aggregate: {
        time: 510780, // total time
        visits: 164, // total visits
        actions: 3237 // total actions
    },
    status: "online",
    labels: [],
    /* Daily actions count */
    timeline: [{
            date: "10\/06\/2012",
            actions: 0
        }, {
            date: "10\/07\/2012",
            actions: 0
        },
        ...
    ],
    pid: "userid",
    recent: {},
    /* Client info */
    info: {},
    history: {
        total: {
            time: 167952,
            vts: 98,
            actions: 2532
        },
        referrer: {
            query: "",
            type: "direct",
            url: ""
        },
        firstvst: 1352503146728
    },
    cookie: "userid hash",
    id: "userid id",
    referrer: {
        query: "",
        type: "direct",
        url: ""
    },
    now: 1357263810764,
    actions: [{
            time: 1357263793307,
            type: "pageview",
            meta: {
                https: "false",
                title: "Woopra",
                time: "1357263793307",
                d: "woopra.com",
                t: "pv",
                url: "\/live\/"
            }
        }
        ...
    ],
    /* Custom Visitor Data */
    custom: {}
}

3. Profile Visits

Drills down through a visitor’s visits.

Endpoint

http(s)://www.woopra.com/rest/profile/visits

Parameters

Required Name Type Description
required website e.g. mydomain.com
required pid (or ‘email’ if defined) String The profile ID (pid) OR the email of the customer
optional to String The unix timestamp (in milliseconds) to return the previous visits. Useful for paging.
required if ‘to’ is not defined date_format String Format of your start and end dates e.g. dd-MM-yyyy (refer to Java’s date formats)
required if ‘to’ is not defined start_day String start date of the visits
required if ‘to’ is not defined end_day String end date of the visits
optional limit Number Number of visits to retrieve (Default 50)
optional filterArray Array Array of actions to filter visits by

Response

{
  visits: [
    {
      region: "",
      os: "",
      second: ,
      resolution: "",
      date: "",
      org: "",
      h: "",
      country: "",
      city: "",
      ip: "",
      minute: ,
      referrer: {
        query: "",
        type: "direct",
        url: ""
      },
      time: 1357263793307,
      duration: ,
      browser: "",
      hour_of_day: ,
      language: "",
      actions: [
        {
          icon: ".\/files\/document---generic.png",
          time: 1357263803307,
          description: "<tag key=\"visitor.name\">Visitor Name<\/tag>
viewed <tag key=\"action.title\">Woopra.com<\/tag> (<tag key=\"action.url\">\/visitors<\/tag>)",
          properties: {
            title: "Woopra.com",
            url: "\/visitors"
          },
          type: "pageview"
        },
        ...
      ]
    }
  ]
}

4. Editing Profiles

Updates a profile’s data.

Endpoint

http(s)://www.woopra.com/rest/profile/edit

Parameters

Required Name Type Description
required website e.g. mydomain.com
required email String email of the customer to be added
optional data String JSON object of all keys and values to be set.ex: {"name":"john smith", "age": 33}

5. Online Visitors Count

Returns number of online visitors.

Endpoint

http(s)://www.woopra.com/rest/online/count

Parameters (Post)

Required Name Type Description
required website e.g. mydomain.com

6. Visits

Retrieves flat visits, without grouping by the visitor.

Endpoint

http(s)://www.woopra.com/rest/search/visits

Parameters

Required Name Type Description
required website e.g. mydomain.com
required before unix timestamp (in milliseconds) for paging

Example in jQuery

An Example of how to request results for Bob Martin via Javascript and JQuery.


$.ajax({
        type: 'POST',
        url: 'https://www.woopra.com/rest/search/visits',
        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',
                before: 1381971395997
            })
        });

Response

[{
    "time": 1381972323049,
    "referrer": {
        "query": "",
        "type": "direct",
        "url": ""
    },
    "pid": "IWOKV7GVDQT6",
    "actions": [{
        "time": 1381972323067,
        "name": "pv",
        "domain": "woopra.com",
        "properties": {
            "title": " Real-time Customer Analytics - Woopra",
            "name": "pv",
            "url": "/"
        }
    }],
    "info": {
        "region": "California",
        "os": "Mac",
        "browser": "Chrome",
        "device": "desktop",
        "lng": -122.4194,
        "language": "English",
        "resolution": "1280x800",
        "org": "",
        "lat": 37.774902,
        "country": "US",
        "city": "San Francisco",
        "ip": "76.103.91.12"
    }
}, 
...
]

7. Online Visitors List

Retrieves online visitors.

Endpoint

http(s)://www.woopra.com/rest/online/list

Parameters

Required Name Type Description
required website e.g. mydomain.com

Need any help? Contact our Data Jedis