NAV

Using the API

Example usage

Here are some examples of what APIs your app might want to use:

Authentication and Authorization

You need to authenticate using API tokens when using reporting APIs. For info on how to get and use API token see Authentication topic of Giosg HTTP API.

Authentication with an API token

Example:
Authorization: Token 03d90e5dbba495469af27ab32dd27cee461a26bc

To authenticate to reporting service you need to provide the api_key for each following API request in a Authorization HTTP header:

Authorization: Token <api_key>

You should replace the <api_key> with the token you created.

Accept Header

You also need to define that you accept JSON-formatted responses by providing the Accept HTTP header:

Accept: application/json

Alternatively, if you are unable to customize headers, you may add format=json GET parameter.

Time ranges

Unless stated otherwise, all the endpoints that require time range to be specified allow maximum range of 180 days.

Time ranges are inclusive meaning that both end and start date are included in results. For example if you specify 2016-01-01 as a start_date and 2016-01-02 as end_date you will get report data from two days.

Migrating from reporting.giosg.com to api.giosg.com

Our old reporting domain reporting.giosg.com has been deprecated and will be removed in the future. It is being replaced with our new API Gateway at api.giosg.com

Here is how you can migrate your existing code from reporting.giosg.com to api.giosg.com

Previous workflow

Because api.giosg.com now handles permissions and authentication using reporting APIs is simplified.

Permission tokens are not needed anymore. You can just create your API Token and start fetching data.

New workflow:

Rule Reporting API

With Rule Reporting API you can get aggregated statistics about impressions (triggered rules) given to visitors and goals that were reached with those impressions.

Room rule report

An example request

GET https://api.giosg.com/api/reporting/v1/rooms/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/rules/daily/?start_date=2016-03-10&end_date=2016-03-25

An example response

{
  "room_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "start_date": "2016-05-05",
  "end_date": "2016-05-07",
  "total_impression_count": 874822,
  "session_with_impression_count": 606945,
  "visitor_with_impression_count": 306945,
  "total_goal_count": 95950,
  "total_purchase_count": 25950,
  "conversion_rate": "15.80",
  "goals": [
    {
      "goal_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
      "count": 15000,
      "conversion_rate": "12.20"
    },
    {
      "goal_id": "abc1d32b-e82c-11e4-b081-6c4008adf321",
      "count": 12340,
      "conversion_rate": "11.05"
    }
  ],
  "currencies": [
    "EUR",
    "USD",
    "GBP",
  ],
  "purchases_by_currency": [
    {
      "code": "EUR",
      "purchase_count": 95000,
      "sales_value": "23234.20",
      "avg_value_per_buyer": "2.45"
    },
    {
      "code": "USD",
      "purchase_count": 910,
      "sales_value": "9100.00",
      "avg_value_per_buyer": "10.00"
    },
    {
      "code": "GBP",
      "purchase_count": 50,
      "sales_value": "850.76",
      "avg_value_per_buyer": "17.01"
    }
  ],
  "by_date": [
    {
      "date": "2016-05-05",
      "impression_count": 1563,
      "session_with_impression_count": 122,
      "visitor_with_impression_count": 90,
      "purchase_count": 3,
      "goal_count": 95,
      "conversion_rate": "2.00",
      "goals": [
        {
          "goal_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
          "count": 5000,
          "conversion_rate": "12.20"
        },
        {
          "goal_id": "abc1d32b-e82c-11e4-b081-6c4008adf321",
          "count": 4000,
          "conversion_rate": "11.05"
        }
      ],
      "currencies": [
        "EUR",
        "USD"
      ],
      "purchases_by_currency": [
        {
          "code": "EUR",
          "purchase_count": 95000,
          "sales_value": "23234.20",
          "avg_value_per_buyer": "2.45"
        },
        {
          "code": "USD",
          "purchase_count": 910,
          "sales_value": "9100.00",
          "avg_value_per_buyer": "10.00"
        }
      ]
    },
    {
      "date": "2016-05-06",
      "impression_count": 1936,
      "session_with_impression_count": 299,
      "visitor_with_impression_count": 255,
      "purchase_count": 1,
      "goal_count": 9,
      "conversion_rate": "0.00",
      "goals": [
        {
          "goal_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
          "count": 5000,
          "conversion_rate": "12.20"
        },
        {
          "goal_id": "abc1d32b-e82c-11e4-b081-6c4008adf321",
          "count": 4000,
          "conversion_rate": "11.05"
        }
      ],
      "currencies": [
        "EUR",
        "GBP"
      ],
      "purchases_by_currency": [
        {
          "code": "EUR",
          "purchase_count": 95000,
          "sales_value": "23234.20",
          "avg_value_per_buyer": "2.45"
        },
        {
          "code": "GPB",
          "purchase_count": 910,
          "sales_value": "9100.00",
          "avg_value_per_buyer": "10.00"
        }
      ]
    },
    {
      "date": "2016-05-07",
      "impression_count": 1936,
      "session_with_impression_count": 299,
      "visitor_with_impression_count": 267,
      "purchase_count": 1,
      "goal_count": 5,
      "conversion_rate": "0.00",
      "goals": [
        {
          "goal_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
          "count": 100,
          "conversion_rate": "12.20"
        },
        {
          "goal_id": "abc1d32b-e82c-11e4-b081-6c4008adf321",
          "count": 90,
          "conversion_rate": "11.05"
        }
      ],
      "currencies": [
        "EUR"
      ],
      "purchases_by_currency": [
        {
          "code": "EUR",
          "purchase_count": 9,
          "sales_value": "224.73",
          "avg_value_per_buyer": "24.96"
        }
      ]
    }
  ]
}

Aggregated total’s per room in given time slot. Maximum allowed time range length is 180 days.

Attribute Type Description
conversion_rate string Calculated conversion rate percent (total_purchase_count/session_with_impression_count). The value is presented as a decimal string, e.g. 50.00
room_id ID Room ID for which the report was generated, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
session_with_impression_count integer Count of sessions that have received impressions in given time range.
visitor_with_impression_count integer Count of unique daily visitors that have received impressions in given time range.
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_goal_count integer Count of times that some goal was reached within 24 hours after some impression on given time range.
total_purchase_count integer Count of purchases within 24 hours after some impression on given time range.
total_impression_count integer Total count of impressions on time range.
goals array List of goal counts and conversions per goal ID
currencies array List of currency strings in ISO 4217 format
purchases_by_currency array Array containing sales per currency. See example on right and explanation of fields here
by_date array Array containing same fields as in the top level of the response json but by date. This is useful for example when drawing charts from data.

Retrieve room report for time range

Get aggregated totals of rules that have been triggered (impressions) in time range on given room (<room_id>).

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

Parameter Type Default Description
start_date string Required. Return statistics from this date on. ISO 8601 date string, e.g. 2016-01-01
end_date string Required. Return statistics until this date. ISO 8601 date string, e.g. 2016-01-01

Room rule report for single rule

An example request

GET https://api.giosg.com/api/reporting/v1/rooms/7c475838-eb59-11e5-890b-6c4008adf7e8/rules/1afa4f70-ec50-11e5-820d-6c4008adf7e8/daily/?start_date=2016-03-10&end_date=2016-03-25

An example response

{
  "room_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "rule_id": "1afa4f70-ec50-11e5-820d-6c4008adf7e8",
  "start_date": "2016-05-05",
  "end_date": "2016-05-07",
  "total_impression_count": 874822,
  "session_with_impression_count": 606945,
  "visitor_with_impression_count": 306945,
  "total_goal_count": 95950,
  "total_purchase_count": 25950,
  "conversion_rate": "15.80",
  "goals": [
    {
      "goal_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
      "count": 15000,
      "conversion_rate": "12.20"
    },
    {
      "goal_id": "abc1d32b-e82c-11e4-b081-6c4008adf321",
      "count": 12200,
      "conversion_rate": "11.05"
    }
  ],
  "currencies": [
    "EUR",
    "USD",
    "GBP",
  ],
  "purchases_by_currency": [
    {
      "code": "EUR",
      "purchase_count": 95000,
      "sales_value": "23234.20",
      "avg_value_per_buyer": "2.45"
    },
    {
      "code": "USD",
      "purchase_count": 910,
      "sales_value": "9100.00",
      "avg_value_per_buyer": "10.00"
    },
    {
      "code": "GBP",
      "purchase_count": 50,
      "sales_value": "850.76",
      "avg_value_per_buyer": "17.01"
    }
  ],
  "by_date": [
    {
      "date": "2016-05-05",
      "impression_count": 1563,
      "session_with_impression_count": 122,
      "visitor_with_impression_count": 111,
      "purchase_count": 3,
      "goal_count": 9,
      "conversion_rate": "2.00",
      "goals": [
        {
          "goal_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
          "count": 500,
          "conversion_rate": "12.20"
        },
        {
          "goal_id": "abc1d32b-e82c-11e4-b081-6c4008adf321",
          "count": 453,
          "conversion_rate": "11.05"
        }
      ],
      "currencies": [
        "EUR",
        "USD"
      ],
      "purchases_by_currency": [
        {
          "code": "EUR",
          "purchase_count": 95000,
          "sales_value": "23234.20",
          "avg_value_per_buyer": "2.45"
        },
        {
          "code": "USD",
          "purchase_count": 910,
          "sales_value": "9100.00",
          "avg_value_per_buyer": "10.00"
        }
      ]
    },
    {
      "date": "2016-05-06",
      "impression_count": 1936,
      "session_with_impression_count": 299,
      "visitor_with_impression_count": 222,
      "purchase_count": 1,
      "goal_count": 9,
      "conversion_rate": "0.00",
      "goals": [
        {
          "goal_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
          "count": 331,
          "conversion_rate": "12.20"
        },
        {
          "goal_id": "abc1d32b-e82c-11e4-b081-6c4008adf321",
          "count": 292,
          "conversion_rate": "11.05"
        }
      ],
      "currencies": [
        "EUR",
        "GBP"
      ],
      "purchases_by_currency": [
        {
          "code": "EUR",
          "purchase_count": 95000,
          "sales_value": "23234.20",
          "avg_value_per_buyer": "2.45"
        },
        {
          "code": "GPB",
          "purchase_count": 910,
          "sales_value": "9100.00",
          "avg_value_per_buyer": "10.00"
        }
      ]
    },
    {
      "date": "2016-05-07",
      "impression_count": 1936,
      "session_with_impression_count": 299,
      "visitor_with_impression_count": 254,
      "purchase_count": 1,
      "goal_count": 9,
      "conversion_rate": "0.00",
      "goals": [
        {
          "goal_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
          "count": 656,
          "conversion_rate": "12.20"
        },
        {
          "goal_id": "abc1d32b-e82c-11e4-b081-6c4008adf321",
          "count": 565,
          "conversion_rate": "11.05"
        }
      ],
      "currencies": [
        "EUR"
      ],
      "purchases_by_currency": [
        {
          "code": "EUR",
          "purchase_count": 9,
          "sales_value": "224.73",
          "avg_value_per_buyer": "24.96"
        }
      ]
    }
  ]
}

Aggregated total’s of single Rule on room in given time slot.

Attribute Type Description
conversion_rate string Calculated conversion rate percent (total_purchase_count/session_with_impression_count). The value is presented as a decimal string, e.g. 50.00
room_id ID Room ID for which the report was generated, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
rule_id ID Rule ID for which the report was generated, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
session_with_impression_count integer Count of sessions that have received impressions in given time range.
visitor_with_impression_count integer Count of unique daily visitors that have received impressions in given time range.
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_goal_count integer Count of times that goal was reached within 24 hours after some impression on given time range.
total_purchase_count integer Count of purchases within 24 hours after some impression on given time range.
total_impression_count integer Total count of impressions run on time range.
currencies array List of currency strings in ISO 4217 format
purchases_by_currency array Array containing sales per currency. See example on right and explanation of fields here
by_date array Array containing same data as in the top level of the response json but by date. This is useful for example when drawing charts from data.

Retrieve per rule report for room and time range

Get a aggregated total’s of single rule (<rule_id>) that have run in time range on given room (<room_id>).

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

Parameter Type Default Description
start_date string Required. Return statistics from this date on. ISO 8601 date string, e.g. 2016-01-01
end_date string Required. Return statistics until this date. ISO 8601 date string, e.g. 2016-01-01

Purchases by currency object

Purchase values will be shown per currency. Each rule reporting endpoint will return sales in purchases_by_currency array. Array will contain objects that have the currency code in code field. Each object represents sales in given currency.

Attribute Type Description
code  string Currency code in ISO 4217 format
purchase_count  integer Count of times shopping cart was purchased on given time range and with current currency
sales_value  string Sales value of carts. The value is presented as a decimal string, e.g. 5000.00
avg_value_per_buyer string Calculated average value per buyer. (sales_value/purchase_count). The value is presented as a decimal string, e.g. 45.00

Goal statistics object

This object contains information on a specific goal.

Attribute Type Description
goal_id ID  The ID of the goal
count integer How many goals in the scope were reached (total or per rule, depends on the context)
conversion_rate string  Calculated conversion rate percent (count/session_with_impression_count). The value is presented as a decimal string, e.g. 50.00

Visitor Stats API

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

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

{
  "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

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

{
  "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

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

{
  "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

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

{
  "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

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

{
  "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

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

{
  "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

User activity stats API

User activity statistic reports. Data for these reports is available from 2017-01-23 onwards.

Organization level API’s

These endpoints return data aggregated in organization level.

User presence count API Quarter hour granularity

Get aggregated statistics about total count of users that have been present in given time range for whole organization. Results will be returned for each 15 minute timeslot per day in the time range. Note that timeslots where present user count is zero will be omitted to keep response smaller.

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/user-presence-counts/quarter-hourly?start_date=<start_date>&end_date=<end_date>

An example request

GET https://api.giosg.com/api/reporting/v1/orgs/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/user-presence-counts/quarter-hourly?start_date=2016-09-10&end_date=2016-09-15

An example response

{
  "organization_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-02-13",
  "end_date": "2017-02-14",
  "max_user_count": 43,
  "average_user_count": "29.00",
  "quarter_hourly": [
    {
      "date": "2017-02-13",
      "user_count": 34,
      "minute_of_day": 0
    },
    {
      "date": "2017-02-13",
      "user_count": 43,
      "minute_of_day": 90
    },
    {
      "date": "2017-02-13",
      "user_count": 41,
      "minute_of_day": 180
    },
    {
      "date": "2017-02-14",
      "user_count": 7,
      "minute_of_day": 900
    },
    {
      "date": "2017-02-14",
      "user_count": 20,
      "minute_of_day": 915
    }
  ]
}
Attribute Type Description
organization_id ID Organization 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
max_user_count integer Maximum number of users present during the requested time range.
average_user_count string Average number of users present during the requested time range. Takes into account only timeslots where at least one user has been present. Value is decimal number as string, eg. “45.00”
quarter_hourly array Array containing data for each 15 minute timeslot available. See object schema below.

Schema for objects in quarter hourly data list

Attribute Type Description
date string Date that this row belongs to. The value is ISO 8601 date string, e.g. 2016-01-01
user_count integer Count of unique users that were present during this hour.
minute_of_day integer Minute of the day. Integer from 0 to 1439. Note that this is in organizations timezone.

User online count API Quarter hour granularity

Get aggregated statistics about total count of users that have been online in given time range for whole organization. Results will be returned for each 15 minute timeslot per day in the time range. Note that timeslots where online user count is zero will be omitted to keep response smaller.

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/user-online-counts/quarter-hourly?start_date=<start_date>&end_date=<end_date>

An example request

GET https://api.giosg.com/api/reporting/v1/orgs/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/user-online-counts/quarter-hourly?start_date=2016-09-10&end_date=2016-09-15

An example response

{
  "organization_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-02-13",
  "end_date": "2017-02-14",
  "max_user_count": 43,
  "average_user_count": "29.00",
  "quarter_hourly": [
    {
      "date": "2017-02-13",
      "user_count": 34,
      "minute_of_day": 0
    },
    {
      "date": "2017-02-13",
      "user_count": 43,
      "minute_of_day": 90
    },
    {
      "date": "2017-02-13",
      "user_count": 41,
      "minute_of_day": 180
    },
    {
      "date": "2017-02-14",
      "user_count": 7,
      "minute_of_day": 900
    },
    {
      "date": "2017-02-14",
      "user_count": 20,
      "minute_of_day": 915
    }
  ]
}
Attribute Type Description
organization_id ID Organization 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
max_user_count integer Maximum number of users online during the requested time range.
average_user_count string Average number of users online during the requested time range. Takes into account only timeslots where at least one user has been online. Value is decimal number as string, eg. “45.00”
quarter_hourly array Array containing data for each 15 minute timeslot available. See object schema below.

Schema for objects in quarter hourly data list

Attribute Type Description
date string Date that this row belongs to. The value is ISO 8601 date string, e.g. 2016-01-01
user_count integer Count of unique users that were online during this hour.
minute_of_day integer Minute of the day. Integer from 0 to 1439. Note that this is in organizations timezone.

Room level API’s

These endpoints return data aggregated in room level.

User presence count API

Get aggregated statistics about total count of users that have been present in given time range. Results will be returned for each hour per day in the time range. Note that hours where present user count is zero will be omitted to keep response smaller.

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

An example request

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

An example response

{
  "room_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-02-13",
  "end_date": "2017-02-14",
  "max_user_count": 43,
  "average_user_count": "29.00",
  "hourly": [
    {
      "date": "2017-02-13",
      "user_count": 34,
      "hour_of_day": 2
    },
    {
      "date": "2017-02-13",
      "user_count": 43,
      "hour_of_day": 9
    },
    {
      "date": "2017-02-13",
      "user_count": 41,
      "hour_of_day": 18
    },
    {
      "date": "2017-02-14",
      "user_count": 7,
      "hour_of_day": 9
    },
    {
      "date": "2017-02-14",
      "user_count": 20,
      "hour_of_day": 22
    }
  ]
}
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
max_user_count integer Maximum number of users present during the requested time range.
average_user_count string Average number of users present during the requested time range. Takes into account only hours where at least one user has been present. Value is decimal number as string, eg. “45.00”
hourly array Array containing data for each hour available. See object schema below.

Schema for objects in hourly data list

Attribute Type Description
date string Date that this row belongs to. The value is ISO 8601 date string, e.g. 2016-01-01
user_count integer Count of unique users that were present during this hour.
hour_of_day integer Hour of the day. Integer from 0 to 23. Note that this is in companys timezone.

Quarter hour granularity

Data presented in 15 minute timeslots.

GET https://api.giosg.com/api/reporting/v1/rooms/<room_id>/user-presence-counts/quarter-hourly?start_date=<start_date>&end_date=<end_date>

An example request

GET https://api.giosg.com/api/reporting/v1/rooms/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/user-presence-counts/quarter-hourly?start_date=2016-09-10&end_date=2016-09-15

An example response

{
  "room_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-02-13",
  "end_date": "2017-02-14",
  "max_user_count": 43,
  "average_user_count": "29.00",
  "quarter_hourly": [
    {
      "date": "2017-02-13",
      "user_count": 34,
      "minute_of_day": 0
    },
    {
      "date": "2017-02-13",
      "user_count": 43,
      "minute_of_day": 90
    },
    {
      "date": "2017-02-13",
      "user_count": 41,
      "minute_of_day": 180
    },
    {
      "date": "2017-02-14",
      "user_count": 7,
      "minute_of_day": 900
    },
    {
      "date": "2017-02-14",
      "user_count": 20,
      "minute_of_day": 915
    }
  ]
}
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
max_user_count integer Maximum number of users present during the requested time range.
average_user_count string Average number of users present during the requested time range. Takes into account only timeslots where at least one user has been present. Value is decimal number as string, eg. “45.00”
quarter_hourly array Array containing data for each 15 minute timeslot available. See object schema below.

Schema for objects in quarter hourly data list

Attribute Type Description
date string Date that this row belongs to. The value is ISO 8601 date string, e.g. 2016-01-01
user_count integer Count of unique users that were present during this hour.
minute_of_day integer Minute of the day. Integer from 0 to 1439. Note that this is in organizations timezone.

User online count API

Get aggregated statistics about total count of users that have been online in given time range. Results will be returned for each hour per day in the time range. Note that hours where online user count is zero will be omitted to keep response smaller.

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

An example request

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

An example response

{
  "room_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-02-13",
  "end_date": "2017-02-14",
  "max_user_count": 43,
  "average_user_count": "29.00",
  "hourly": [
    {
      "date": "2017-02-13",
      "user_count": 34,
      "hour_of_day": 2
    },
    {
      "date": "2017-02-13",
      "user_count": 43,
      "hour_of_day": 9
    },
    {
      "date": "2017-02-13",
      "user_count": 41,
      "hour_of_day": 18
    },
    {
      "date": "2017-02-14",
      "user_count": 7,
      "hour_of_day": 9
    },
    {
      "date": "2017-02-14",
      "user_count": 20,
      "hour_of_day": 22
    }
  ]
}
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
max_user_count integer Maximum number of users online during the requested time range.
average_user_count string Average number of users online during the requested time range. Takes into account only hours where at least one user has been online. Value is decimal number as string, eg. “45.00”
hourly array Array containing data for each hour available. See object schema below.

Schema for objects in hourly data list

Attribute Type Description
date string Date that this row belongs to. The value is ISO 8601 date string, e.g. 2016-01-01
user_count integer Count of unique users that were online during this hour.
hour_of_day integer Hour of the day. Integer from 0 to 23. Note that this is in companys timezone.

Quarter hour granularity

Data presented in 15 minute timeslots.

GET https://api.giosg.com/api/reporting/v1/rooms/<room_id>/user-online-counts/quarter-hourly?start_date=<start_date>&end_date=<end_date>

An example request

GET https://api.giosg.com/api/reporting/v1/rooms/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/user-online-counts/quarter-hourly?start_date=2016-09-10&end_date=2016-09-15

An example response

{
  "room_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-02-13",
  "end_date": "2017-02-14",
  "max_user_count": 43,
  "average_user_count": "29.00",
  "quarter_hourly": [
    {
      "date": "2017-02-13",
      "user_count": 34,
      "minute_of_day": 0
    },
    {
      "date": "2017-02-13",
      "user_count": 43,
      "minute_of_day": 90
    },
    {
      "date": "2017-02-13",
      "user_count": 41,
      "minute_of_day": 180
    },
    {
      "date": "2017-02-14",
      "user_count": 7,
      "minute_of_day": 900
    },
    {
      "date": "2017-02-14",
      "user_count": 20,
      "minute_of_day": 915
    }
  ]
}
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
max_user_count integer Maximum number of users online during the requested time range.
average_user_count string Average number of users online during the requested time range. Takes into account only timeslots where at least one user has been online. Value is decimal number as string, eg. “45.00”
quarter_hourly array Array containing data for each 15 minute timeslot available. See object schema below.

Schema for objects in quarter hourly data list

Attribute Type Description
date string Date that this row belongs to. The value is ISO 8601 date string, e.g. 2016-01-01
user_count integer Count of unique users that were online during this hour.
minute_of_day integer Minute of the day. Integer from 0 to 1439. Note that this is in organizations timezone.

User presence times API

Get aggregated statistics about total user presence time in given time range. Results will be returned for each user seen in given day in the time range. Note that users that were not seen in any given day will be omitted to keep response smaller.

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

An example request

GET https://api.giosg.com/api/reporting/v1/rooms/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/user-presence-times/?start_date=2017-01-10&end_date=2017-01-12

An example response

{
  "room_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-01-10",
  "end_date": "2017-01-12",
  "max_seconds": 430,
  "average_seconds": "386.33",
  "by_date": [
    {
      "seconds": 430,
      "user_id": "1be552ea-eb89-4723-a9c6-7bef1c698d29",
      "date": "2017-01-10"
    },
    {
      "seconds": 366,
      "user_id": "20126833-f43d-11e6-b3ec-6c4008adf7e8",
      "date": "2017-01-10"
    },
    {
      "seconds": 363,
      "user_id": "d1bc1b54-f434-11e6-b929-6c4008adf7e8",
      "date": "2017-01-12"
    }
  ]
}
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
max_seconds integer Maximum seconds any single user was present during requested time range.
average_seconds string Average seconds users were present during requested time range. Value is decimal number as string, eg. “45.00”
by_date array Array containing data by date. This will contain objects for each day and unique user for that day in requested time range. See schema below.

Daily data object

Each daily data object will contain data for single user that was present during that day. Note that if user was not present during that day then there wont be object for that user id.

Schema for daily data object

Attribute Type Description
date string Date of this data row. The value is ISO 8601 date string, e.g. 2016-01-01
user_id ID User ID, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
seconds integer Total seconds this user was present during the day.

User online times API

Get aggregated statistics about total user online time in given time range. Results will be returned for each user that has been online in given day in the time range. Note that users that were not online in any given day will be omitted to keep response smaller.

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

An example request

GET https://api.giosg.com/api/reporting/v1/rooms/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/user-online-times/?start_date=2017-01-10&end_date=2017-01-12

An example response

{
  "room_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-01-10",
  "end_date": "2017-01-12",
  "max_seconds": 430,
  "average_seconds": "386.33",
  "by_date": [
    {
      "seconds": 430,
      "user_id": "1be552ea-eb89-4723-a9c6-7bef1c698d29",
      "date": "2017-01-10"
    },
    {
      "seconds": 366,
      "user_id": "20126833-f43d-11e6-b3ec-6c4008adf7e8",
      "date": "2017-01-10"
    },
    {
      "seconds": 363,
      "user_id": "d1bc1b54-f434-11e6-b929-6c4008adf7e8",
      "date": "2017-01-12"
    }
  ]
}
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
max_seconds integer Maximum seconds any single user was online during requested time range.
average_seconds string Average seconds users were online during requested time range. Value is decimal number as string, eg. “45.00”
by_date array Array containing data by date. This will contain objects for each day and unique user for that day in requested time range. See schema below.

Daily data object

Each daily data object will contain data for single user that was online during that day. Note that if user was not online during that day then there wont be object for that user id.

Schema for daily data object

Attribute Type Description
date string Date of this data row. The value is ISO 8601 date string, e.g. 2016-01-01
user_id ID User ID, e.g. b0a1d32b-e82c-11e4-b081-6c4008adf7e8
seconds integer Total seconds this user was online during the day.

Room online times API

Get statistics about room online time in given time range. Room online time means time when there was at least one user online on that room. Results will be returned for each day for given date range that there was online time. Note that days when there wasn’t online time will be omitted to keep response smaller.

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

An example request

GET https://api.giosg.com/api/reporting/v1/rooms/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/room-online-times/?start_date=2017-01-10&end_date=2017-01-12

An example response

{
  "room_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-12-12",
  "end_date": "2017-12-15",
  "total_online_seconds": 63429,
  "average_seconds_per_day": "15857.00",
  "average_seconds_per_day_when_online": "21143.00",
  "by_date": [
    {
      "online_seconds": 45000,
      "date": "2017-12-12",
      "ranges": [
        {
          "start": 12000,
          "end": 13000
        },
        {
          "start": 22000,
          "end": 56000
        },
        {
          "start": 66000,
          "end": 76000
        }
      ]
    },
    {
      "online_seconds": 2000,
      "date": "2017-12-14",
      "ranges": [
        {
          "start": 11000,
          "end": 13000
        }
      ]
    },
    {
      "online_seconds": 16429,
      "date": "2017-12-15",
      "ranges": [
        {
          "start": 104,
          "end": 11533
        },
        {
          "start": 15000,
          "end": 20000
        }
      ]
    }
  ]
}
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_online_seconds integer Total seconds room was online during requested time range.
average_seconds_per_day string Average seconds room was online during requested time range. Value is decimal number as string, eg. “15857.00”. Value is calculated by dividing total_online_seconds with total days in requested range.
average_seconds_per_day_when_online string Average seconds room was online during requested time range taking into account only those days when there was some online time. Value is decimal number as string, eg. “15857.00”. Value is calculated by dividing total_online_seconds with count of those days that had some online time in requested range.
by_date array Array containing data by date. This will contain objects for each day in requested time range. See schema below.

Daily data object

Each daily data object will contain data for single day. Note that if no users were online during some of the days in range then there wont be object for that day.

Schema for daily data object

Attribute Type Description
date string Date of this data row. The value is ISO 8601 date string, e.g. 2016-01-01
online_seconds integer Total seconds room was online during the day.
ranges array List of objects describing time ranges when room was online during that day. Each object will have start and end attributes. Those attributes describe the second of day when this range started and ended.

Organizations and user chat statistics API

Chat statistics for users and organizations. Provides statistics per organization, per room and per user in daily intervals.

Organization chat statistics API

Get aggregated statistics for: - conversation_count - user_message_count - conversations_with_sales_count - sales_conversation_percentage - sales_sum - subscription_sales_sum - average_cart_size

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/chatstats/?start_date=<start_date>&end_date=<end_date>&timezone=Europe/Helsinki

Organization chat statistics API including network

To include the chats and sales from network, use the following API end point:

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/chatstats/includenetwork/?start_date=<start_date>&end_date=<end_date>&timezone=<timezone>

With this endpoint the network is included in the response for the room owner. For organization level this returns the statistics from all rooms that are shared to other organizations. If a room was shared to your organization, this contains only statistics from the users in your own organization.

An example request

GET https://api.giosg.com/api/reporting/v1/orgs/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/chatstats/?start_date=2018-05-01&end_date=2018-05-02&timezone=Europe/Helsinki

An example response

{
  "organization_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-02-02",
  "end_date": "2017-02-12",
  "conversation_count": 123,
  "user_message_count": 1232,
  "conversations_with_sales_count": 12,
  "sales_conversation_percentage": "9.76",
  "sales_sum": "122.22",
  "subscription_sales_sum": "22.11",
  "average_cart_size": "45.33"
}

An example request

GET https://api.giosg.com/api/reporting/v1/orgs/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/chatstats/includenetwork/?start_date=2018-05-01&end_date=2018-05-02&timezone=Europe/Helsinki

An example response

{
  "organization_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-02-02",
  "end_date": "2017-02-12",
  "conversation_count": 234,
  "user_message_count": 2342,
  "conversations_with_sales_count": 24,
  "sales_conversation_percentage": "10.26",
  "sales_sum": "122.22",
  "subscription_sales_sum": "22.11",
  "average_cart_size": "45.33"
}
Parameter Type Description
organization_id ID  ID of the organization
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
timezone string Name of the timezone e.g. Europe/Helsinki
conversation_count integer Number of conversations in the whole organization. See definition of “Conversation” below.
user_message_count integer Number of messages users sent to the conversations.
conversations_with_sales_count integer Number of conversations which led to visitor purchase.
sales_conversation_percentage string How many percent of conversations led to sales.
sales_sum string Total sum of sales.
subscription_sales_sum string Total sum of subscription sales.
average_cart_size string Average size of single sale.

Room chat statistics API

Get the following aggregated statistics for a single room: - conversation_count - user_message_count - conversations_with_sales_count - sales_conversation_percentage - sales_sum - subscription_sales_sum - average_cart_size

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/rooms/<room_id>/chatstats/?start_date=<start_date>&end_date=<end_date>&timezone=<timezone>

Room chat statistics API including network

To include the chats and sales from network, use the following API end point:

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/rooms/<room_id>/chatstats/includenetwork/?start_date=<start_date>&end_date=<end_date>&timezone=<timezone>

With this endpoint the network is included in the response for the room owner. If a room was shared to your organization, this contains only statistics from the users in your own organization.

An example request

GET https://api.giosg.com/api/reporting/v1/orgs/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/rooms/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/chatstats/?start_date=2018-05-01&end_date=2018-05-02&timezone=Europe/Helsinki

An example response

{
  "organization_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "room_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "start_date": "2017-02-02",
  "end_date": "2017-02-12",
  "conversation_count": 123,
  "user_message_count": 1232,
  "conversations_with_sales_count": 12,
  "sales_conversation_percentage": "9.76",
  "sales_sum": "122.22",
  "subscription_sales_sum": "22.11",
  "average_cart_size": "45.33"
}

An example request

GET https://api.giosg.com/api/reporting/v1/orgs/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/rooms/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/chatstats/includenetwork/?start_date=2018-05-01&end_date=2018-05-02&timezone=Europe/Helsinki

An example response

{
  "organization_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "room_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "start_date": "2017-02-02",
  "end_date": "2017-02-12",
  "conversation_count": 234,
  "user_message_count": 2342,
  "conversations_with_sales_count": 24,
  "sales_conversation_percentage": "10.26",
  "sales_sum": "122.22",
  "subscription_sales_sum": "22.11",
  "average_cart_size": "45.33"
}
Parameter Type Description
organization_id ID  ID of the organization
room_id ID  ID of the room
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
timezone string Name of the timezone e.g. Europe/Helsinki
conversation_count integer Number of conversations in the whole organization. See definition of “Conversation” below.
user_message_count integer Number of messages users sent to the conversations.
conversations_with_sales_count integer Number of conversations which led to visitor purchase.
sales_conversation_percentage string How many percent of conversations led to sales.
sales_sum string Total sum of sales.
subscription_sales_sum string Total sum of subscription sales.
average_cart_size string Average size of single sale.

User chat statistics API

Get the following aggregated statistics per user: - conversation_count - user_message_count - conversations_with_sales_count - sales_conversation_percentage - sales_sum - subscription_sales_sum - average_cart_size

User statistics including all rooms in the organization

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/chatstats/users/?start_date=<start_date>&end_date=<end_date>&&timezone=<timezone>

User statistics for a single room

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/rooms/<room_id>/chatstats/users/?start_date=<start_date>&end_date=<end_date>&timezone=<timezone>

An example request

GET https://api.giosg.com/api/reporting/v1/orgs/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/rooms/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/chatstats/users/?start_date=2018-05-01&end_date=2018-05-02&timezone=Europe/Helsinki

An example response

{
  "organization_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "room_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "start_date": "2018-05-01",
  "end_date": "2018-05-02",
  "users": [
    {
      "user_id": "fccfd220-4de5-11e8-b996-34f39a27e6aa",
      "conversation_count": 1,
      "user_message_count": 12,
      "conversations_with_sales_count": 1,
      "sales_conversation_percentage": "100.00",
      "sales_sum": "122.22",
      "subscription_sales_sum": "0.00",
      "average_cart_size": "122.22"
    },
    {
      "user_id": "04a1b18a-4de6-11e8-b996-34f39a27e6aa",
      "conversation_count": 2,
      "user_message_count": 32,
      "conversations_with_sales_count": 1,
      "sales_conversation_percentage": "50.00",
      "sales_sum": "100.00",
      "subscription_sales_sum": "0.00",
      "average_cart_size": "100.00"
    }
  ]
}
Parameter Type Description
organization_id ID  ID of the organization
room_id ID  ID of the room
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
timezone string Name of the timezone e.g. Europe/Helsinki
conversation_count integer Number of conversations in the whole organization. See definition of “Conversation” below.
user_message_count integer Number of messages users sent to the conversations.
conversations_with_sales_count integer Number of conversations which led to visitor purchase.
sales_conversation_percentage string How many percent of conversations led to sales.
sales_sum string Total sum of sales.
subscription_sales_sum string Total sum of subscription sales.
average_cart_size string Average size of single sale.

Definition of “Conversation”

Definition of conversation is following:

Visitor chat stats API

Visitor chat statistics APIs. Data for these reports is available from 2017-05-01 onwards.

Daily chat statistics API

Get aggregated statistics for example about chat counts, chatted visitor counts, autosuggest counts and more. Returns aggregated results for given time range.

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

An example request

GET https://api.giosg.com/api/reporting/v1/rooms/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/visitorchatstats/daily/?start_date=2017-01-10&end_date=2017-01-12

An example response

{
  "room_id": "b88ccf85-f1c3-11e6-9805-6c4008adf7e8",
  "start_date": "2017-01-10",
  "end_date": "2017-01-11",
  "total_visitors_with_conversation_count": 346,
  "total_visitors_with_chat_count": 433,
  "total_visitors_affected_by_chat_count": 946,
  "total_visitors_autosuggested_count": 1346,
  "total_conversation_count": 324,
  "total_chats_from_autosuggest_count": 123,
  "total_chats_from_user_count": 123,
  "total_chats_from_visitor_count": 123,
  "total_visitor_message_count": 123,
  "total_user_message_count": 10046,
  "total_missed_chat_count": 4,
  "by_date": [
    {
      "visitors_with_conversation_count": 123,
      "visitors_with_chat_count": 222,
      "visitors_affected_by_chat_count": 423,
      "visitors_autosuggested_count": 673,
      "conversation_count": 112,
      "chats_from_autosuggest_count": 123,
      "chats_from_user_count": 123,
      "chats_from_visitor_count": 123,
      "visitor_message_count": 123,
      "user_message_count": 4523,
      "missed_chat_count": 3,
      "date": "2017-01-10"
    },
    {
      "visitors_with_conversation_count": 223,
      "visitors_with_chat_count": 221,
      "visitors_affected_by_chat_count": 523,
      "visitors_autosuggested_count": 673,
      "chats_from_autosuggest_count": 123,
      "chats_from_user_count": 123,
      "chats_from_visitor_count": 123,
      "conversation_count": 212,
      "visitor_message_count": 123,
      "user_message_count": 5523,
      "missed_chat_count": 1,
      "date": "2017-01-11"
    }
  ]
}
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_visitors_with_conversation_count integer Count of unique daily visitors that had proper conversation in given time range. See definition of “Conversation” below.
total_visitors_with_chat_count integer Count of unique daily visitors that had chat in given time range. This includes all chats where there is at least one visitor message.
total_visitors_affected_by_chat_count integer Count of unique daily visitors that were affected by chat in given time range. See definition of affected by chat below.
total_visitors_autosuggested_count integer Count of unique daily visitors that were autosuggested in given time range.
total_chats_from_autosuggest_count integer Total count of chat sessions started by autosuggest message in given time range.
total_chats_from_user_count integer Total count of chat sessions started by user manually sending message in given time range.
total_chats_from_visitor_count integer Total count of chat sessions started by visitor message in given time range.
total_conversation_count integer Count of unique chat sessions that were considered as proper conversations in given time range. See definition of “Conversation” below.
total_visitor_message_count integer Total count of visitor messages sent in given time range.
total_user_message_count integer Total count of user chat messages sent in given time range.
missed_chat_count integer Count of unique chat sessions in given time range that were missed by users. This means that there were visitor messages but no responses from users.
by_date array Array containing data by date. This will contain objects for each day in requested time range. See object schema below.

Daily data object

Each daily data object will contain data for single day. Daily data will contain same fields as the top level of the response object.

Schema for daily data object

Attribute Type Description
date string Date of this data object. The value is ISO 8601 date string, e.g. 2016-01-01
visitors_with_conversation_count integer Count of unique daily visitors that had proper conversation at that day. See definition of “Conversation” below.
visitors_with_chat_count integer Count of unique daily visitors that had chat at that day. This includes all chats where there is at least one visitor message.
visitors_affected_by_chat_count integer Count of unique daily visitors that were affected by chat at that day. See definition of affected by chat below.
visitors_autosuggested_count integer Count of unique daily visitors that were autosuggested at that day.
chats_from_autosuggest_count integer Count of chat sessions started by autosuggest message at that day.
chats_from_user_count integer Count of chat sessions started by user manually sending message at that day.
chats_from_visitor_count integer Count of chat sessions started by visitor message at that day.
conversation_count integer Count of unique chat sessions that were considered as proper conversations at that day. See definition of “Conversation” below.
visitor_message_count integer Total count of visitor messages sent at that day.
user_message_count integer Total count of user chat messages sent at that day.
missed_chat_count integer Count of unique chat sessions at that day that were missed by users. This means that there were visitor messages but no responses from users.

Hourly chat statistics API

This API provides aggregated hourly statistics for:

Get aggregated statistics for example about chat counts, chatted visitor counts, autosuggest counts and more. Returns aggregated results for given time range.

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

Top level object attributes

An example request

GET https://api.giosg.com/api/reporting/v1/rooms/b88ccf85-f1c3-11e6-9805-6c4008adf7e8/visitorchatstats/hourly/?start_date=2017-01-10&end_date=2017-01-12
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

Hourly array object attributes

An example response

{
  "room_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "start_date": "2016-09-10",
  "end_date": "2016-09-27",
  "hourly": [
    {
      "date": "2016-09-22",
      "hour": 2,
      "visitors_with_conversation_count": 6,
      "visitors_with_chat_count": 1,
      "visitors_affected_by_chat_count": 1,
      "visitors_autosuggested_count": 6,
      "conversation_count": 4,
      "chats_from_autosuggest_count": 1,
      "chats_from_user_count": 1,
      "chats_from_visitor_count": 1,
      "visitor_message_count": 1,
      "user_message_count": 10,
      "missed_chat_count": 4
    },
    {
      "date": "2016-09-23",
      "hour": 21,
      "visitors_with_conversation_count": 8,
      "visitors_with_chat_count": 6,
      "visitors_affected_by_chat_count": 1,
      "visitors_autosuggested_count": 6,
      "conversation_count": 4,
      "chats_from_autosuggest_count": 1,
      "chats_from_user_count": 1,
      "chats_from_visitor_count": 1,
      "visitor_message_count": 1,
      "user_message_count": 10,
      "missed_chat_count": 4
    },
    {
      "date": "2016-09-21",
      "hour": 15,
      "visitors_with_conversation_count": 6,
      "visitors_with_chat_count": 1,
      "visitors_affected_by_chat_count": 1,
      "visitors_autosuggested_count": 6,
      "conversation_count": 4,
      "chats_from_autosuggest_count": 2,
      "chats_from_user_count": 2,
      "chats_from_visitor_count": 2,
      "visitor_message_count": 2,
      "user_message_count": 10,
      "missed_chat_count": 4
    },
    {
      "date": "2016-09-26",
      "hour": 7,
      "visitors_with_conversation_count": 6,
      "visitors_with_chat_count": 1,
      "visitors_autosuggested_count": 6,
      "visitors_affected_by_chat_count": 1,
      "conversation_count": 4,
      "chats_from_autosuggest_count": 2,
      "chats_from_user_count": 2,
      "chats_from_visitor_count": 2,
      "visitor_message_count": 2,
      "user_message_count": 10,
      "missed_chat_count": 4
    },
    {
      "date": "2016-09-27",
      "hour": 4,
      "visitors_with_conversation_count": 6,
      "visitors_with_chat_count": 1,
      "visitors_affected_by_chat_count": 1,
      "visitors_autosuggested_count": 6,
      "conversation_count": 4,
      "chats_from_autosuggest_count": 2,
      "chats_from_user_count": 2,
      "chats_from_visitor_count": 2,
      "visitor_message_count": 2,
      "user_message_count": 10,
      "missed_chat_count": 4
    },
    {
      "date": "2016-09-24",
      "hour": 19,
      "visitors_with_conversation_count": 6,
      "visitors_with_chat_count": 1,
      "visitors_affected_by_chat_count": 1,
      "visitors_autosuggested_count": 6,
      "conversation_count": 4,
      "chats_from_autosuggest_count": 1,
      "chats_from_user_count": 2,
      "chats_from_visitor_count": 1,
      "visitor_message_count": 1,
      "user_message_count": 10,
      "missed_chat_count": 4
    },
    {
      "date": "2016-09-25",
      "hour": 17,
      "visitors_with_conversation_count": 6,
      "visitors_with_chat_count": 1,
      "visitors_affected_by_chat_count": 1,
      "visitors_autosuggested_count": 6,
      "conversation_count": 4,
      "chats_from_autosuggest_count": 1,
      "chats_from_user_count": 1,
      "chats_from_visitor_count": 1,
      "visitor_message_count": 1,
      "user_message_count": 10,
      "missed_chat_count": 4
    }
  ]
}
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].
visitors_with_conversation_count int Count of unique daily visitors that had proper conversation at that hour. See definition of “Conversation” below.
visitors_with_chat_count int Count of unique daily visitors that had chat at that hour. This includes all chats where there is at least one visitor message.
visitors_affected_by_chat_count int Count of unique daily visitors that were affected by chat at that hour. See definition of affected by chat below.
visitors_autosuggested_count int Count of unique daily visitors that were autosuggested at that hour.
chats_from_autosuggest_count int Count of chat sessions started by autosuggest message at that hour.
chats_from_user_count int Count of chat sessions started by user manually sending message at that hour.
chats_from_visitor_count int Count of chat sessions started by visitor message at that hour.
conversation_count int Count of unique chat sessions that were considered as proper conversations at that hour. See definition of “Conversation” below.
visitor_message_count int Total count of visitor messages sent at that hour.
user_message_count int Total count of user chat messages sent at that hour.
missed_chat_count int Count of unique chat sessions at that hour that were missed by users. This means that there were visitor messages but no responses from users.

Definition of “Conversation”

Definition of conversation is following:

Definition of “Affected by chat”

Visitor is affected by chat if any of the following is true:

Experiment results API

Here you can fetch reports on how your experiment is performing.

Weekly experiment results API v2

Get results on a specific experiment during a time range of n weeks.

The results are calculated on resolution of one week because the results are likely vary a lot on daily basis. Week by week comparison should be more robust.

Unlike other reporting APIs, experiment results are fetched based on the last date in the interval. The data is available only for past weeks. The last full week, starting from Monday, before the given end_date is considered as the first week in the report.

GET https://api.giosg.com/api/reporting/v2/orgs/<organization_id>/experiments/<experiment_id>/weekly/?end_date=<end_date>&control_group_id=<control_group_id>&weeks=<weeks>

This endpoint returns:

Request parameters

An example request

GET https://api.giosg.com/api/reporting/v2/orgs/aaa1d32b-e82c-11e4-b081-6c4008adf7e8/experiments/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/weekly/?end_date=2017-03-17&control_group_id=0bf27670-0e18-11e7-a1bb-60f81db14236&weeks=4
Parameter Type Description
organization_id ID  ID of the organization
experiment_id ID  The ID of the experiment
end_date ISO 8601 string  Experiment results are fetched up to this date for the give interval. e.g. 2017-03-20
control_group_id  ID The ID of the group against which others are compared when computing statistical significance. If not provided, these test statistics will not be calculated.
weeks  integer  For how many weeks the results are accumulated.

Response attributes

An example response

{
  "weeks": 2,
  "end_date": "2018-10-15",
  "resolution": "week",
  "control_group_id": "0bf27670-0e18-11e7-a1bb-60f81db14236",
  "experiment_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "organization_id": "aaa1d32b-e82c-11e4-b081-6c4008adf7e8",
  "groups_by_week": [{
      "group_name": "A (Algorithm)",
      "group_id": "f1b8fda8-0e17-11e7-a5af-60f81db14236",
      "end_date": "2018-10-14",
      "unique_visitor_count": 505,
      "visitor_with_treatment_count": 105,
      "visitor_with_goal_count": 55,
      "conversion": "0.109",
      "confidence_interval_low": "0.123",
      "confidence_interval_high": "0.223",
      "statistical_significance": "0.82"
    }, {
      "group_name": "B (Random)",
      "group_id": "0bf27670-0e18-11e7-a1bb-60f81db1423",
      "end_date": "2018-10-14",
      "unique_visitor_count": 1050,
      "visitor_with_treatment_count": 120,
      "visitor_with_goal_count": 1,
      "conversion": "0.00095",
      "confidence_interval_low": "0.02",
      "confidence_interval_high": "0.10",
      "statistical_significance": null
    }, {
      "group_name": "A (Algorithm)",
      "group_id": "f1b8fda8-0e17-11e7-a5af-60f81db14236",
      "end_date": "2018-10-07",
      "unique_visitor_count": 505,
      "visitor_with_treatment_count": 105,
      "visitor_with_goal_count": 55,
      "conversion": "0.109",
      "confidence_interval_low": "0.115",
      "confidence_interval_high": "0.323",
      "statistical_significance": "0.72"
    }, {
      "group_name": "B (Random)",
      "group_id": "0bf27670-0e18-11e7-a1bb-60f81db1423",
      "end_date": "2018-10-07",
      "unique_visitor_count": 1045,
      "visitor_with_treatment_count": 120,
      "visitor_with_goal_count": 1,
      "conversion": "0.00095",
      "confidence_interval_low": "0.03",
      "confidence_interval_high": "0.1",
      "statistical_significance": null
    }
  ],
  "group_totals": [{
      "group_name": "A (Algorithm)",
      "group_id": "f1b8fda8-0e17-11e7-a5af-60f81db14236",
      "unique_visitor_count": 1010,
      "visitor_with_treatment_count": 210,
      "visitor_with_goal_count": 110,
      "conversion": "0.109"
    }, {
      "group_name": "B (Random)",
      "group_id": "0bf27670-0e18-11e7-a1bb-60f81db1423",
      "unique_visitor_count": 2095,
      "visitor_with_treatment_count": 240,
      "visitor_with_goal_count": 2,
      "conversion": "0.00095"
    }
  ]
}

Root level fields

Attribute Type Description
end_date ISO 8601 string The last date of the interval
resolution string Resolution of the intervals. Always “week”
units  integer  How many intervals are included. If the interval is “week” and units is 4 then there are 4 weeks of data in the response.
organization_id ID  The organization_id this experiment belongs to
experiment_id ID  Id of the experiment
control_group_id ID  The group id against which the difference of other groups is tested. This group will not have statistical significance calculated because no reason to compare to itself.
groups_by_week  Array of JSON objects  The weekly results for each group
group_totals  Array of JSON objects  Sums of weekly counts per group for the whole time range.

Each object in groups_by_week contains these values

Attribute Type Description
group_name string The name of the Experiment group
group_id ID  The id of the group
unique_visitor_count integer  The weekly count of unique visitors in this group
visitor_with_treatment_count  integer  The weekly count of unique visitors that were treated with the configured treatment in this group (if a treatment is configured for the experiment)
visitor_with_goal_count  integer The weekly count of unique visitors that achieved the configured goal in this group
conversion  float  The weekly conversion rate calculated by visitor_with_goal_count/unique_visitor_count
confidence_interval_low float Lower bound of 95% confidence interval, see Definition of Confidence Intervals below
confidence_interval_high  float  Upper bound of 95% confidence interval, see Definition of Confidence Intervals below
statistical_significance  float  The test statistics on whether the group has statistically significant difference in conversion rate compared to control group. See Definition of statistical significance below

Each object in group_totals contains these values

Attribute Type Description
group_name string The name of the Experiment group
group_id ID  The id of the group
unique_visitor_count integer  The sum of all weekly counts of unique visitors that were assigned to this group during the time period. If the same visitor was assigned to the same group the next week they will be counted as an unique visitor for both weeks.
visitor_with_treatment_count integer  The sum of all weekly counts of unique visitors that were treated with the configured treatment (if a treatment is configured for the experiment).
visitor_with_goal_count integer  The sum of all weekly counts of unique visitors that achieved the configured goal in this group.
conversion float  The total conversion rate calculated by visitor_with_goal_count/unique_visitor_count

Weekly cumulated experiment results API v1

Get weekly accumulated results on a specific experiment. By “weekly accumulated”, we mean that e.g. the unique visitor counts, visitors with goal counts are cumulated over the period. The first week contains counts only from the first week of data. The counts for the second week contain both first and second week et cetera.

The results are calculated on resolution of one week because the results are likely vary a lot on daily basis. Week by week comparison should be more robust.

Unlike other reporting APIs, experiment results are fetched based on the last date in the interval. This is due to cumulative calculation requirements.

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/experiments/<experiment_id>/weekly/?end_date=<end_date>&control_group_id=<control_group_id>&weeks=<weeks>

Request parameters

An example request

GET https://api.giosg.com/api/reporting/v1/orgs/aaa1d32b-e82c-11e4-b081-6c4008adf7e8/experiments/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/weekly/?end_date=2017-03-17&control_group_id=0bf27670-0e18-11e7-a1bb-60f81db14236&weeks=4
Parameter Type Description
organization_id ID  ID of the organization
experiment_id ID  The ID of the experiment
end_date ISO 8601 string  Experiment results are fetched up to this date for the give interval. e.g. 2017-03-20
control_group_id  ID The ID of the group against which others are compared when computing statistical significance. If not provided, these test statistics will not be calculated.
weeks  integer  For how many weeks the results are accumulated. The valid week numbers at the moment are 1, 4 or 8 weeks.

Response attributes

An example response

{
  "weeks": 4,
  "end_date": "2017-03-17",
  "resolution": "week",
  "control_group_id": "0bf27670-0e18-11e7-a1bb-60f81db14236",
  "experiment_id": "b0a1d32b-e82c-11e4-b081-6c4008adf7e8",
  "organization_id": "aaa1d32b-e82c-11e4-b081-6c4008adf7e8",
  "groups_by_week": [{
      "group_name": "A (Algorithm)",
      "group_id": "f1b8fda8-0e17-11e7-a5af-60f81db14236",
      "end_date": "2017-02-21",
      "unique_visitor_count": 14234,
      "visitor_with_treatment_count": 1234,
      "visitor_with_goal_count": 123,
      "conversion": "0.18",
      "confidence_interval_low": "0.123",
      "confidence_interval_high": "0.223",
      "statistical_significance": "0.82"
    }, {
      "group_name": "B (Random)",
      "group_id": "0bf27670-0e18-11e7-a1bb-60f81db1423",
      "end_date": "2017-02-21",
      "unique_visitor_count": 1235,
      "visitor_with_treatment_count": 1352,
      "visitor_with_goal_count": 1234,
      "conversion": "0.05",
      "confidence_interval_low": "0.02",
      "confidence_interval_high": "0.10",
      "statistical_significance": null
    }, {
      "group_name": "A (Algorithm)",
      "group_id": "f1b8fda8-0e17-11e7-a5af-60f81db14236",
      "end_date": "2017-03-01",
      "unique_visitor_count": 19234,
      "visitor_with_treatment_count": 24124,
      "visitor_with_goal_count": 4214,
      "conversion": "0.18",
      "confidence_interval_low": "0.115",
      "confidence_interval_high": "0.323",
      "statistical_significance": "0.72"
    }, {
      "group_name": "B (Random)",
      "group_id": "0bf27670-0e18-11e7-a1bb-60f81db1423",
      "end_date": "2017-03-01",
      "unique_visitor_count": 14234,
      "visitor_with_treatment_count": 1234,
      "visitor_with_goal_count": 123,
      "conversion": "0.07",
      "confidence_interval_low": "0.03",
      "confidence_interval_high": "0.1",
      "statistical_significance": null
    },
    ...
  ],
  "group_sizes": [{
      "group_name": "A (Algorithm)",
      "group_id": "f1b8fda8-0e17-11e7-a5af-60f81db14236",
      "end_date": "2017-03-01",
      "unique_visitor_count": 19234
    }, {
      "group_name": "B (Random)",
      "group_id": "0bf27670-0e18-11e7-a1bb-60f81db1423",
      "end_date": "2017-03-01",
      "unique_visitor_count": 14234
    }, {
      "group_name": "A (Algorithm)",
      "group_id": "f1b8fda8-0e17-11e7-a5af-60f81db14236",
      "end_date": "2017-02-21",
      "unique_visitor_count": 19234
    }, {
      "group_name": "B (Random)",
      "group_id": "0bf27670-0e18-11e7-a1bb-60f81db1423",
      "end_date": "2017-02-21",
      "unique_visitor_count": 14234
    }
    ...
  ]
}

Root level fields

Attribute Type Description
end_date ISO 8601 string The last date of the interval
resolution string Resolution of the intervals. Always “week”
units  integer  How many intervals are included. If the interval is “week” and units is 4 then there are 4 weeks of cumulative data in the response.
organization_id ID  The organization_id this experiment belongs to
experiment_id ID  Id of the experiment
control_group_id ID  The group id against which the difference of other groups is tested. This group will not have statistical significance calculated because no reason to compare to itself.
groups_by_week  Array of JSON objects  The cumulative weekly results for each group
group_sizes  Array of JSON objects  Experiment group sizes for each week. These counts are not cumulative and thus this data can be used to determine group sizes for each individual week.

Each object in cumulative_groups_by_week contains these values

Attribute Type Description
group_name string The name of the Experiment group
group_id ID  The id of the group
unique_visitor_count integer  The cumulative weekly counts of unique visitors ordered from earliest to most recent
visitor_with_treatment_count  integer  The cumulative weekly counts of unique visitors that were treated with the configured treatment (if a treatment is configured for the experiment)
visitor_with_goal_count  integer The cumulative weekly counts of unique visitors that achieved the configured goal
conversion  float  The weekly conversion rate calculated by visitor_with_goal_count/unique_visitor_count
confidence_interval_low float Lower bound of 95% confidence interval, see Definition of Confidence Intervals below
confidence_interval_high  float  Upper bound of 95% confidence interval, see Definition of Confidence Intervals below
statistical_significance  float  The test statistics on whether the group has statistically significant difference in conversion rate compared to control group. See Definition of statistical significance below

Each object in group_sizes contains these values

Attribute Type Description
group_name string The name of the Experiment group
group_id ID  The id of the group
end_date ISO 8601 string The last date of the interval
unique_visitor_count integer  The count of unique visitors that were assigned to this group during this week. If the same visitor was assigned to the same group the next week they will be counted as an unique visitor for both weeks.

Definition of confidence intervals

The visitors are modeled by a binomial distribution with parameter p, where success is defined as reaching the goal. We model the posterior distribution for the conversion rate p with a beta distribution. The 95% confidence interval is the most narrow interval that captures 95% of the probability mass. This is also known as highest posterior density or highest density intervals.

Definition of statistical significance

At giosg, we use a Bayesian approach to estimate the statistical significance of differences in conversion rates. The test is essentially a null-hypothesis significance test (NHST) were we test whether the treatment group has a statistically significantly higher conversion rate than the control group. Both groups are modeled by Beta-distributions with uniform uninformative priors (Beta(1, 1)), and the statistical significance is estimated in a Monte Carlo simulation. Due to the approach, you might see slight variations in the statistical significance for the same results, but only in the third decimal.

Real-time Reporting API

Room based real-time statistics

Returns current dates real-time statistics for the selected room.

GET https://service.giosg.com/api/reporting/v1/rooms/<room_id>/realtime

This endpoint accepts the following GET parameters.

Parameter Type Default Description
room_id UUID filter results to only this certain room
timezone String UTC Name of the timezone to use for time based aggregation e.g. Europe/Helsinki

A response contains following fields:

{
  "start_time": "2018-03-02T00:00:00",
  "end_time": "2018-03-02T23:59:59",
  "real_conversations": 4,
  "visitor_count_now": 1,
  "visitor_count_today": 7,
  "missed_chats": 2,
  "avg_wait_time": 14,
  "max_wait_time": 24,
  "total_sales_sum": "40.00",
  "purchased_cart_count": 2,
  "avg_purchased_cart_size": "10.00",
  "chat_conversion_percent": "50.00",
  "sales_with_chat": "20.00",
  "room_id": "b42cb7f0-1e14-11e8-b467-0ed5f89f718b"
}
Attribute Type Description
start_time string DATE starting time of calculated results.
end_time string DATE ending time of calculated results.
real_conversation integer Real chat conversations today in selected time range.
visitor_count_now integer Unique visitors currently in selected room.
visitor_count_today integer Unique visitors today in selected room.
missed_chats integer Chats missed by operators today.
avg_wait_time integer Average wait time of the visitors in selected time range.
max_wait_time integer max wait time of the visitors in selected time range.
total_sales_sum float Total sum of sales in selected time range.
purchased_cart_count integer Total sum of purchased carts in selected time range.
avg_purchased_cart_size float Average size of purchased cart in selected time range.
chat_conversion_percent float percent which chat converted visitors in selected time range.
sales_with_chat float Amount of sales with chat in selected time range.
daily_avg_chat_wait_time float Daily average wait time of the waiting visitors.
daily_max_chat_wait_time float Daily maximum wait time of the waiting visitors.
room_id string UUID type identifier of room

Room based real-time statistics by user

Returns current dates real-time statistics groupped by operator for room.

GET https://service.giosg.com/api/reporting/v1/rooms/<room_id>/realtime/users

This endpoint accepts the following GET parameters.

Parameter Type Default Description
room_id UUID filter results to only this certain room
timezone string UTC Name of the timezone to use for time based aggregation e.g. Europe/Helsinki

A response contains following fields:

{
  "room_id": "b42cb7f0-1e14-11e8-b467-0ed5f89f718b",
  "start_time": "2018-03-02T00:00:00",
  "end_time": "2018-03-02T23:59:59",
  "by_operator": [
    {
      "user_id": "c051e488-1e14-11e8-b467-0ed5f89f718b",
      "real_conversations": 4,
      "purchased_cart_count": 2,
      "avg_purchased_cart_size": "10.00",
      "sales_with_chat": "20.00",
      "chat_conversion_percent": "50.00",
      "online_seconds": 0,
      "present_seconds": 300
    }
  ]
}
Attribute Type Description
room_id string UUID type identifier of room
start_time string date/time starting time of calculated results.
end_time string date/time ending time of calculated results.
by_operator array of objects Array of operator objects.

Each object in by_operator contains these values

Attribute Type Description
user_id UUID  The identifier of user
real_conversations integer  All operators real_conversations in selected time range
purchased_cart_count  integer  Total sum of purchased carts whit operator in selected time range.
avg_purchased_cart_size float Average size of purchased cart in selected time range
sales_with_chat  float  Operators sales with chat
chat_conversion_percent float Chats conversion rate when operator is included
online_seconds float Seconds that operator has been online in chat in selected time range.
present_seconds integer Seconds that operator has been present in site in selected time range.

Organization based real-time statistics

Returns current dates real-time statistics for the selected organization.

GET https://service.giosg.com/api/reporting/v1/orgs/<organization_id>/realtime

This endpoint accepts the following GET parameters.

Parameter Type Default Description
organization_id UUID UUID type identifier of organization
timezone string UTC Name of the timezone to use for time based aggregation e.g. Europe/Helsinki

A response contains following fields:

{
  "start_time": "2018-03-02T00:00:00",
  "end_time": "2018-03-02T23:59:59",
  "real_conversations": 4,
  "visitor_count_now": 1,
  "visitor_count_today": 7,
  "missed_chats": 2,
  "avg_wait_time": 14,
  "max_wait_time": 24,
  "total_sales_sum": "40.00",
  "purchased_cart_count": 2,
  "avg_purchased_cart_size": "10.00",
  "chat_conversion_percent": "50.00",
  "sales_with_chat": "20.00",
  "organization_id": "d7ffcad8-1e18-11e8-b467-0ed5f89f718b"
}
Attribute Type Description
start_time string DATE starting time of calculated results.
end_time string DATE ending time of calculated results.
real_conversation integer Real chat conversations today in selected time range.
visitor_count_now integer Unique visitors currently in selected room.
visitor_count_today integer Unique visitors today in selected room.
missed_chats integer Count of chats missed by operators today.
avg_wait_time integer Average wait time of the visitors in selected time range.
max_wait_time integer max wait time of the visitors in selected time range.
total_sales_sum float Total sum of sales in selected time range.
purchased_cart_count integer Total sum of purchased carts in selected time range.
avg_purchased_cart_size float Average size of purchased cart in selected time range.
chat_conversion_percent float percent which chat converted visitors in selected time range.
sales_with_chat float Amount of sales with chat in selected time range.
daily_avg_chat_wait_time float Daily average wait time of the waiting visitors.
daily_max_chat_wait_time float Daily maximum wait time of the waiting visitors.
organization_id string UUID string identifier

Organization based real-time statistics by user

Returns current dates real-time statistics groupped by operator for organization.

GET https://service.giosg.com/api/reporting/v1/rooms/<organization_id>/realtime/users

This endpoint accepts the following GET parameters.

Parameter Type Default Description
organization_id UUID UUID type identifier of organization
timezone string UTC Name of the timezone to use for time based aggregation e.g. Europe/Helsinki

A response contains following fields:

{
  "organization_id": "109fe0c6-1e19-11e8-b467-0ed5f89f718b",
  "start_time": "2018-03-02T00:00:00",
  "end_time": "2018-03-02T23:59:59",
  "by_operator": [
    {
      "user_id": "182e72ee-1e19-11e8-b467-0ed5f89f718b",
      "real_conversations": 4,
      "purchased_cart_count": 2,
      "avg_purchased_cart_size": "10.00",
      "sales_with_chat": "20.00",
      "chat_conversion_percent": "50.00",
      "online_seconds": 0,
      "present_seconds": 300
    }
  ]
}
Attribute Type Description
organization_id string UUID type identifier of organization
start_time string date/time starting time of calculated results.
end_time string date/time ending time of calculated results.
by_operator array of objects Array of operator objects.

Each object in by_operator contains these values

Attribute Type Description
user_id UUID  The identifier of user
real_conversations integer  All operators real_conversations in selected time range
purchased_cart_count  integer  Total sum of purchased carts whit operator in selected time range.
avg_purchased_cart_size float Average size of purchased cart in selected time range
sales_with_chat  float  Operators sales with chat
chat_conversion_percent float Chats conversion rate when operator is included
online_seconds float Seconds that operator has been online in chat in selected time range.
present_seconds integer Seconds that operator has been present in site in selected time range.

Room based real-time tag statistics

Returns current dates real-time tag statistics for the selected room.

GET https://api.giosg.com/api/reporting/v1/rooms/<room_id>/realtime/tags

This endpoint accepts the following GET parameters.

Parameter Type Default Description
organization_id UUID filter results to only this certain room
room_id UUID type identifier of room
timezone String UTC Name of the timezone to use for time based aggregation e.g. Europe/Helsinki

A response contains following fields:

{
    "room_id": "6aff9e92-cbf4-11e3-9189-525400be0204",
    "start_time": "2018-03-05T00:00:00",
    "end_time": "2018-03-05T23:59:59",
    "tags": [{
        "count": 112,
        "name": "Incident report"
    }, {
        "count": 33,
        "name": "Feature request"
    }]
}
Attribute Type Description
room_id string UUID type identifier of room
start_time string DATE starting time of calculated results.
end_time string DATE ending time of calculated results.
tags array of objects Array of tag objects.

Each object in tags contains these values

Attribute Type Description
count integer  Count of tags used in current room.
name String  Name of the tag

Organization based real-time tag statistics

Returns current dates real-time tag statistics for the selected organization.

GET https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/realtime/tags

This endpoint accepts the following GET parameters.

Parameter Type Default Description
organization_id UUID filter results to only this certain organization
timezone String UTC Name of the timezone to use for time based aggregation e.g. Europe/Helsinki

A response contains following fields:

{
    "organization_id": "64c1366e-3273-11e8-b467-0ed5f89f718b",
    "start_time": "2018-03-05T00:00:00",
    "end_time": "2018-03-05T23:59:59",
    "tags": [{
        "count": 22,
        "name": "Incident report"
    }, {
        "count": 44,
        "name": "Feature request"
    }]
}

Attribute Type Description
organization_id string UUID type identifier of organization
start_time string DATE starting time of calculated results.
end_time string DATE ending time of calculated results.
tags array of objects Array of tag objects.

Each object in tags contains these values:

Attribute Type Description
count integer  Count of tags used by selected organization.
name String  Name of the tag