Skip to content

Visitor Statistics

Visitor counts, session counts and visitor devices API

Get aggregated statistics from daily visitor counts, visitor sessions and visitors' devices for a single room for the given room and date range. The statistics can be fetched either on a resolution of one day or one hour.

Daily counts

GET https://api.giosg.com/api/reporting/v1/rooms/<room_id>/visitor-stats/?start_date=<start_date>&end_date=<end_date>

An example request

1
GET https://api.giosg.com/api/reporting/v1/rooms/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/visitor-stats/?start_date=2016-09-10&end_date=2016-09-15

An example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
{
  "room_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "start_date": "2016-09-10",
  "end_date": "2016-09-27",
  "total_session_count": 2969,
  "total_visitor_count": 1568,
  "total_desktop_visitors_count": 2056,
  "total_mobile_visitors_count": 1464,
  "total_tablet_visitors_count": 2485,
  "by_date": {
    "2016-09-22": {
      "session_count": 684,
      "visitor_count": 168,
      "desktop_visitors_count": 107,
      "mobile_visitors_count": 114,
      "tablet_visitors_count": 494
    },
    "2016-09-23": {
      "session_count": 317,
      "visitor_count": 171,
      "desktop_visitors_count": 170,
      "mobile_visitors_count": 308,
      "tablet_visitors_count": 230
    },
    "2016-09-21": {
      "session_count": 105,
      "visitor_count": 126,
      "desktop_visitors_count": 137,
      "mobile_visitors_count": 223,
      "tablet_visitors_count": 212
    },
    "2016-09-26": {
      "session_count": 831,
      "visitor_count": 225,
      "desktop_visitors_count": 360,
      "mobile_visitors_count": 205,
      "tablet_visitors_count": 340
    },
    "2016-09-27": {
      "session_count": 399,
      "visitor_count": 380,
      "desktop_visitors_count": 398,
      "mobile_visitors_count": 166,
      "tablet_visitors_count": 465
    },
    "2016-09-24": {
      "session_count": 378,
      "visitor_count": 127,
      "desktop_visitors_count": 464,
      "mobile_visitors_count": 261,
      "tablet_visitors_count": 370
    },
    "2016-09-25": {
      "session_count": 255,
      "visitor_count": 371,
      "desktop_visitors_count": 420,
      "mobile_visitors_count": 187,
      "tablet_visitors_count": 374
    }
  }
}
Attribute Type Description
room_id ID Room ID for which the report was generated, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
start_date string Start date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-01
end_date string End date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-30
total_session_count integer Count of visitor sessions for the given time range
total_visitor_count integer Count of daily visitors for the given time range
total_desktop_visitors_count integer Count of daily visitors with device type desktop for the given time range
total_mobile_visitors_count integer Count of daily visitors with device type mobile for the given time range
total_tablet_visitors_count integer Count of daily visitors with device type table for the given time range
by_date object Object containing same information as in the top level of the response json but by date. This is useful for example when drawing charts from data.

Hourly counts

Session and visitor counts aggregated hourly. Visitor counts are stored also by device type (desktop, mobile and tablet).

GET https://api.giosg.com/api/reporting/v1/rooms/<room_id>/visitor-stats/hourly/?start_date=<start_date>&end_date=<end_date>

Top level object attributes

An example request

1
GET https://api.giosg.com/api/reporting/v1/rooms/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/visitor-stats/hourly/?start_date=2016-09-10&end_date=2016-09-15
Attribute Type Description
room_id ID Room ID for which the report was generated, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
start_date string Start date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-01
end_date string End date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-30
hourly Array[Object] Array containing hourly session and visitor counts, as well as visitor counts by device type.

Hourly array object attributes

An example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
{
  "room_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "start_date": "2016-09-10",
  "end_date": "2016-09-27",
  "hourly": [
    {
      "date": "2016-09-22",
      "hour": 2,
      "session_count": 684,
      "visitor_count": 168,
      "desktop_visitors_count": 107,
      "mobile_visitors_count": 114,
      "tablet_visitors_count": 494
    },
    {
      "date": "2016-09-23",
      "hour": 21,
      "session_count": 317,
      "visitor_count": 171,
      "desktop_visitors_count": 170,
      "mobile_visitors_count": 308,
      "tablet_visitors_count": 230
    },
    {
      "date": "2016-09-21",
      "hour": 15,
      "session_count": 105,
      "visitor_count": 126,
      "desktop_visitors_count": 137,
      "mobile_visitors_count": 223,
      "tablet_visitors_count": 212
    },
    {
      "date": "2016-09-26",
      "hour": 7,
      "session_count": 831,
      "visitor_count": 225,
      "desktop_visitors_count": 360,
      "mobile_visitors_count": 205,
      "tablet_visitors_count": 340
    },
    {
      "date": "2016-09-27",
      "hour": 4,
      "session_count": 399,
      "visitor_count": 380,
      "desktop_visitors_count": 398,
      "mobile_visitors_count": 166,
      "tablet_visitors_count": 465
    },
    {
      "date": "2016-09-24",
      "hour": 19,
      "session_count": 378,
      "visitor_count": 127,
      "desktop_visitors_count": 464,
      "mobile_visitors_count": 261,
      "tablet_visitors_count": 370
    },
    {
      "date": "2016-09-25",
      "hour": 17,
      "session_count": 255,
      "visitor_count": 371,
      "desktop_visitors_count": 420,
      "mobile_visitors_count": 187,
      "tablet_visitors_count": 374
    }
  ]
}
Attribute Type Description
date string The date for which the counts are
hour int The hour for which the counts are. Valid hours are in range [0, 23].
session_count int Number of sessions on this hour
visitor_count int Number of visitors on this hour
desktop_visitors_count int Number of visitors that used desktop computer
mobile_visitors_count int Number of visitors that used mobile device
tablet_visitors_count int Number of visitors that used tablet device

Pageviews per ISP Company

Get top 20 Internet Service Providers by pageview count for given room and date range.

GET https://api.giosg.com/api/reporting/v1/rooms/<room_id>/isppageviews/?start_date=<start_date>&end_date=<end_date>

An example request

1
GET https://api.giosg.com/api/reporting/v1/rooms/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/isppageviews/?start_date=2017-01-20&end_date=2017-01-22

An example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "room_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "start_date": "2017-01-20",
  "end_date": "2017-01-22",
  "total_pageview_count": 1982,
  "isp_companies": [
    { "ip_organization": "Isp1 Oy", "pageview_count": 1000 },
    { "ip_organization": "Isp2 Oy", "pageview_count": 500 },
    { "ip_organization": "Isp3 Ltd", "pageview_count": 452 }
  ],
  "by_date": {
    "2017-01-20": {
      "total_pageview_count": 1234,
      "isp_companies": [
        { "ip_organization": "Isp1 Oy", "pageview_count": 1000 },
        { "ip_organization": "Isp2 Oy", "pageview_count": 234 }
      ]
    },
    "2017-01-21": {
      "total_pageview_count": 648,
      "isp_companies": [
        { "ip_organization": "Isp3 Ltd", "pageview_count": 422 },
        { "ip_organization": "Isp2 Oy", "pageview_count": 226 }
      ]
    },
    "2017-01-22": {
      "total_pageview_count": 100,
      "isp_companies": [
        { "ip_organization": "Isp3 Ltd", "pageview_count": 30 },
        { "ip_organization": "Isp2 Oy", "pageview_count": 40 }
      ]
    }
  }
}
Attribute Type Description
room_id ID Room ID for which the report was generated, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
start_date string Start date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-01
end_date string End date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-30
total_pageview_count integer The count of all pageview events for the given time range
isp_companies JSON array Pageview event count for each ISP for the given time range
by_date object Object containing same information as in the top level of the response json but by date. This is useful for example when drawing charts from data.

Top countries and cities by visitor pageviews

Get top 10 countries and top 10 cities per country by pageview count. Pageviews that were not from the top listed country or city are counted into "Others" fields.

GET https://api.giosg.com/api/reporting/v1/rooms/<room_id>/visitorgeostats/?start_date=<start_date>&end_date=<end_date>

An example request

1
GET https://api.giosg.com/api/reporting/v1/rooms/4b758854-df18-11e6-8259-60f81db14236/visitorgeostats/?start_date=2017-01-19&end_date=2017-01-20

An example response

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
{
  "room_id": "4b758854-df18-11e6-8259-60f81db14236",
  "start_date": "2017-01-19",
  "end_date": "2017-01-20",
  "countries": [
    {
      "name": "Finland",
      "count": 1200,
      "cities": [
        {
          "name": "Helsinki",
          "count": 800
        },
        {
          "name": "Espoo",
          "count": 100
        },
        {
          "name": "Tampere",
          "count": 50
        },
        {
          "name": "Oulu",
          "count": 50
        },
        {
          "name": "Others",
          "count": 200
        }
      ]
    },
    {
      "name": "UK",
      "count": 550,
      "cities": [
        {
          "name": "London",
          "count": 450
        },
        {
          "name": "Birmingham",
          "count": 30
        },
        {
          "name": "Leeds",
          "count": 20
        },
        {
          "name": "Others",
          "count": 50
        }
      ]
    },
    {
      "name": "Others",
      "count": 200
    }
  ],
  "by_date": {
    "2017-01-19": {
      "countries": [
        {
          "name": "Finland",
          "count": 1200,
          "cities": [
            {
              "name": "Helsinki",
              "count": 800
            },
            {
              "name": "Espoo",
              "count": 100
            },
            {
              "name": "Tampere",
              "count": 50
            },
            {
              "name": "Oulu",
              "count": 50
            },
            {
              "name": "Others",
              "count": 200
            }
          ]
        },
        {
          "name": "Others",
          "count": 100
        }
      ]
    },
    "2017-01-20": {
      "countries": [
        {
          "name": "UK",
          "count": 550,
          "cities": [
            {
              "name": "London",
              "count": 450
            },
            {
              "name": "Birmingham",
              "count": 30
            },
            {
              "name": "Leeds",
              "count": 20
            },
            {
              "name": "Others",
              "count": 50
            }
          ]
        },
        {
          "name": "Others",
          "count": 100
        }
      ]
    }
  }
}
Attribute Type Description
room_id ID Room ID for which the report was generated, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
start_date string Start date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-01
end_date string End date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-30
countries JSON array Top 10 countries and top 10 cities per country by pageview count for given room_id and date range
by_date JSON object   Top 10 countries and cities for each date

Top search terms and counts

Get top 100 search terms when visitors arrive on the page from a search engine. The report can answer to questions like "What are my visitors seaching for when they arrive to our page?".

Giosg collects these terms from most popular search engines. However not all search engines expose these terms every time a visitor clicks follows a link from their results.

GET https://api.giosg.com/api/reporting/v1/rooms/<room_id>/searchterms/?start_date=<start_date>&end_date=<end_date>

An example request

1
GET https://api.giosg.com/api/reporting/v1/rooms/4b758854-df18-11e6-8259-60f81db14236/searchterms/?start_date=2017-02-05&end_date=2017-02-07

An example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "room_id": "4b758854-df18-11e6-8259-60f81db14236",
  "start_date": "2017-02-04",
  "end_date": "2017-02-06",
  "total_search_count": 100000,
  "search_terms": [
    { "referrer_term": "Company X website", "count": 12345 },
    { "referrer_term": "How does feature Y work", "count": 1234 },
    { "referrer_term": "Getting help", "count": 3 }
  ],
  "by_date": {
    "2017-02-04": {
      "total_search_count": 20000,
      "search_terms": [
        { "referrer_term": "Company X website", "count": 6000 },
        { "referrer_term": "Some other search", "count": 1200 }
      ]
    },
    "2017-02-05": {
      "total_search_count": 50000,
      "search_terms": [
        { "referrer_term": "Company X website", "count": 6000 },
        { "referrer_term": "Some other search", "count": 1200 },
        { "referrer_term": "Rare search word", "count": 1 }
      ]
    },
    "2017-02-06": {
      "total_search_count": 30000,
      "search_terms": [
        { "referrer_term": "Need help", "count": 6000 },
        { "referrer_term": "Some other search", "count": 1200 },
        { "referrer_term": "Rare search word", "count": 1 }
      ]
    }
  }
}
Attribute Type Description
room_id ID Room ID for which the report was generated, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
start_date string Start date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-01
end_date string End date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-30
total_search_count integer Total count of searches. Ie. pageviews whose referrer was some known search engine.
search_terms JSON array Top 100 search strings and their counts for given room_id and date range
by_date JSON object   Top 100 search strings and counts for each date. See schema below.

Schema for objects in by_date and search_terms list

Attribute Type Description
referrer_term string Search term used, for example Live chat software.
count integer Count of unique searches. Pageview with known search engine as referrer will be counted as unique searh.

Traffic sources

Returns top referring sites and visitor landing pages when they navigate from other sites to your site. Data is aggregated by date for the given data range.

GET https://api.giosg.com/api/reporting/v1/rooms/<room_id>/trafficsources/?start_date=<start_date>&end_date=<end_date>

An example request

1
GET https://api.giosg.com/api/reporting/v1/rooms/4b758854-df18-11e6-8259-60f81db14236/trafficsources/?start_date=2017-02-05&end_date=2017-02-07

An example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "room_id": "4b758854-df18-11e6-8259-60f81db14236",
  "start_date": "2017-02-05",
  "end_date": "2017-02-06",
  "by_date": {
    "2017-02-05": [
      {
        "referrer_url": "www.google.fi",
        "count": 54,
        "landing_pages": [
          {
            "count": 53,
            "page_url": "https://www.mydomain.com/"
          },
          {
            "count": 1,
            "page_url": "https://www.mydomain.com/contact"
          }
        ]
      },
      {
        "referrer_url": "www.google.se",
        "count": 9,
        "landing_pages": [
          {
            "count": 9,
            "page_url": "https://www.mydomain.com/"
          }
        ]
      }
    ],
    "2017-02-06": [
      {
        "count": 223,
        "referrer_url": "www.google.fi",
        "landing_pages": [
          {
            "count": 202,
            "page_url": "https://www.mydomain.com/"
          },
          {
            "count": 21,
            "page_url": "https://www.mydomain.com/contact"
          }
        ]
      }
    ]
  }
}

Top level fields

Attribute Type Description
room_id ID Room ID for which the report was generated, e.g. 4b758854-df18-11e6-8259-60f81db14236
start_date string Start date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-01
end_date string End date of time range used to get the statistics. The value is ISO 8601 date string, e.g. 2016-01-30
by_date object Object containing top a list of top referrer domains and visitor landing pages by date

By date fields

Attribute Type Description
referrer_url string The referring domain that visitor originated from
count integer Count of page views that originated from referrer_url
landing_pages array Array of objects that contain top landing pages by page view count from the referrer in referrer_url

Landing page is the first page viewed by the visitor when they arrive to the site that contains giosg script.

Landing page fields

Attribute Type Description
page_url array The url of the landing page
count integer The count page views that count as landing page for the page_url