visitors

Authentication Required

API Key

Parameters

Required

site_token Site Token

Optional

`visitorsMode`	Which list of visitors to load. Possible values are `all`returning and `tagged`, which respectively load from all visitors, returning visitors, and visitors with custom tags assigned
`visitorsLimit`	Start and end positions for the portion of visitors to send back. Values can be: A single integer n - fetch the first n visitors Comma-delimited string x , n - fetch the first n visitors stating at position x
`additionalFields`	Specify up to 5 additional attribute fields to be included in each visitor object. Specify a comma-separated list of field names. See list of additional fields

Returns

JSON ONLY. Object of visitors containing keys:

Key	Type	Description
`total`	Integer	Total number of visitors online
`active`	Integer	Total number of active visitors online
`returning`	Integer	Total number of returning visitors online
`tagged`	Integer	Total number of tagged visitors online
`cardinality`	Integer	Total number of visitors in the current set
`v_[VISITOR ID]`	Object	Object for each visitor containing keys describing the visitor's session, as described below

Visitor object

Key Type Description

browserName String Browser information, as per browser list

browserVersion String

platformName String Platform information, as per platform list

platformVersion String

numericPlatformVersion Number

location Object Location information, containing keys lat latitude, and lon longitude

country String ISO 3166 alpha-2 country code of visitor's location

region String Region code of visitor's location (e.g. state code when in US)

city String City name of visitor's location

returning Integer 1 if the visitor has visited the site before, 0 if not

tag [optional] String Custom visitor name, if set in the tracking code

pages

Array

Array of page objects describing the visitor's browsing trail in basic detail, with keys:

`landTime`	UNIX timestamp of when the visitor opened the page
`state`	Either `focus` or `blur`, describing whether the visitor currently has the page active
`exit` [optional]	Set to a string value if the visitor has unloaded the page
`exitTime` [optional]	UNIX timestamp of when the page was unloaded

currentPage

Object

Object describing the visitor's currently open page, with keys:

`href`	Full URL of the page
`index`	Index of the page in the visitor's current browsing session
`path`	Path of the page, not including protocol or domain name
`title`	Page title
`pageHash`	MD5 hash of the page's `href`. Used for filtering

Additional fields

Key	Type	Description
`referring_url`	String	The referring URL for the visitor.

Complexity Cost

1 unit

Example Request

http://api.gosquared.com/visitors?api_key=API_KEY&site_token=GSN-1234567-X&visitorId=123456789

Example Response

{
    "visitors": {
        "active": 12,
        "cardinality": 27,
        "returning": 22,
        "tagged": 21,
        "total": 27,
        "v_424573577": {
            "browserName": "chrome",
            "browserVersion": "14.0.814.0",
            "city": "London",
            "country": "GB",
            "currentPage": {
                "href": "http://www.gosquared.com/",
                "index": 2,
                "pageHash": "110a138b43c143f17c7ac9a0422238cd5",
                "path": "/",
                "title": "GoSquared - real-time web analytics"
            },
            "location": {
                "lat": 51.5,
                "lon": -0.13
            },
            "numericPlatformVersion": "6.1",
            "pages": [
                {
                    "landTime": 1310369504,
                    "state": "focus",
                    "exit": "timeout",
                    "exitTime": 1310369515
                },
                {
                    "landTime": 1310369515,
                    "state": "focus",
                    "exit": "timeout",
                    "exitTime": 1310369529
                },
                {
                    "landTime": 1310369529,
                    "state": "focus"
                }
            ],
            "platformName": "win",
            "platformVersion": "6.1",
            "region": "H9",
            "returning": 1,
            "tag": "JT"
        },
        [...]
    }
}

Last modified: 3 April 2012 12:19