Insights API

The Kaon Insights Portal (contact your Kaon PM for access) provides an easy-to-use interface to access information about how your applications on the Kaon SaaS Platform are being used. In addition to this web interface, there is API access to analytics data. This document details that REST API.

To use analytics, you will need an API key. This API key should be kept secret, since anyone holding the key can see all the analytics data for your application. Contact support@kaon.com if you need a key generated for you.

Overview

The general form of the API is a URL like this:

https://insights.v-central.com/api/{api name}?apikey={your api key}&client={ID for your app}&{other parameters}

All API calls should use the HTTP GET verb. Kaon will supply you with the api key and client ID for your application.

All successful API calls return a JSON object with a 200 result code. Passing invalid data will result in a 403 (unauthorized) or 404 (not found) error.

Many API calls use "week" numbers. Every week is assigned a number, counting from 1/1/2012 (the date the first app went live on the Kaon SaaS platform). Full insights data is only available starting the week of 12/29/2019 which is week 417. Hit count data is available back to whenever the application first went live.

/api/weeks

Returns the weeks for which full data is available for this application.

Parameters:

apikeyrequiredidentifies the user of the API
clientrequiredidentifies the application

Returns:

clientstringidentifies the application
weeksarrayeach object in the array has members: {
    week: number
    weekname: string
}

/api/engagement

Returns engagement information for one week.

Parameters:

apikeyrequiredidentifies the user of the API
clientrequiredidentifies the application
weekoptionalrequested week (if omitted, the current week will be returned)

Returns:

clientstringidentifies the application
weeknumber returned week
weeknamestringreturned week name 
engagementsarrayeach object in the array has members: {
    dev: string (device type)
    country: string (ISO 3166-1 alpha-2)
    bucket: number (see below)
    online: boolean (true if access was online, false if offline)
    count: number (count of engagements in this bucket)
}

Engagement data is a histogram of durations. Idle time is not included, and if the user accesses the application multiple times with less than a 30 minute gap, those are considered a single engagement.

Bucket values:
00-10s 
110-30s 
230s-1m 
31-3m 
43-5m 
55-30m 
630m+ 

/api/uid

Returns unique device information for one week. Every device is assigned a completely random identifier (uid) on its first run, which allows analysis of frequency of use by that device. Note that browsers tend to discard this information, so only non-web device uids are reliable over the long term.

Parameters:

apikeyrequiredidentifies the user of the API
clientrequiredidentifies the application
weekoptionalrequested week (if omitted, the current week will be returned)

Returns:

clientstringidentifies the application
weeknumber returned week
weeknamestringreturned week name 
uidsarrayeach object in the array has members: {
    dev: string (device type)
    country: string (ISO 3166-1 alpha-2)
    lang: string (2 letter language code, indicating language used in-app)
    uids: string (see below)
}

The uids string is a concatenation of uid values in the format: 0x[16 hex digits]0x[16 hex digits]...

The number of devices is therefore the length of the uids string divided by 18.

To determine the number of unique devices across time spans longer than a week, the caller will need to split the IDs and manage their own sets.

/api/countries

Returns a count of the number of unique engagements in each country.

Parameters:

apikeyrequiredidentifies the user of the API
clientrequiredidentifies the application
weekoptionalrequested week (if omitted, the current week will be returned)

Returns:

clientstringidentifies the application
weeknumber returned week
weeknamestringreturned week name 
countriesarrayeach object in the array has members: {
    country: string (ISO 3166-1 alpha-2)
    count: number (count of engagements in that country)
}


/api/lang

Returns a count of the number of unique engagements in each language.

Parameters:

apikeyrequiredidentifies the user of the API
clientrequiredidentifies the application
weekoptionalrequested week (if omitted, the current week will be returned)

Returns:

clientstringidentifies the application
weeknumber returned week
weeknamestringreturned week name 
langsarrayeach object in the array has members: {
    lang: string (see below)
    count: number (count of engagements in that language)
}

Note that language strings in Kaon apps are not precisely the same as the ISO standards. These are the current set of languages:

en English
gb English (UK)
ar عربى (Arabic)
cs Česky (Czech)
da Dansk (Danish)
de Deutsch (German)
el Ελληνικά (Greek)
es Español (Spanish)
fi Suomi (Finnish)
fr Français (French)
ca Français (Canadian French)
it Italiano (Italian)
ja 日本語 (Japanese)
ko 한국어 (Korean)
nl Nederlands (Dutch)
no Norsk (Norweigan)
pl Polski (Polish)
pt Português (Portuguese)
bz Português (Brasilian Portuguese)
ru Русский (Russian)
sv Svenska (Swedish)
th ไทย (Thai)
tr Türkçe (Turkish)
vi Tiếng Việt (Vietnamese)
zh 中文 (Chinese)
zt 繁體中文 (Traditional Chinese)

/api/hits

Returns hit count information for a particular item in the app.

Parameters:

apikeyrequiredidentifies the user of the API
clientrequiredidentifies the application
weekoptionalrequested week (if omitted, see below)
pathoptional requested path (if omitted, see below) 
detailoptionalrequests added detail about the hits (see below)

If a path is provided, and no week is provided, all hits for that path in all time will be returned (this may go back several years)

If no path is provided, all hits for that week (defaulting to the current week if no week is present) will be returned

The detail parameter is supported only if a path is provided, and requests more detail about the hits. The only supported value is "country"

Returns:

clientstringidentifies the application
hitsarrayeach object in the array has members: {
    path: string (see below)
    count: number (count of path hits)
    embed: number (number of hits that were in an IFRAME, will always be <= .count)
    week: number (only if no week was included in request)
    weekname: string (only if no week was included in request)
    detail: (see below)
}

Paths can be analyzed to understand what kind of a hit they represent. paths are URL-encoded (so, for example, spaces appear as %20). After decoding the following conventions are used:

starts with $$ animation
starts with ~~ hotspot
ends with **ar viewed in augmented reality
ends with **vr viewed in virtual reality
starts with __[mp4] video collateral
starts with __[pdf] pdf collateral
starts with __ touchpoint within the app, such as a section
otherwise anything not matching the above patterns is a 3D product tour

If the optional parameter detail=country is included in the request, each hit will include an object mapping two-letter country codes to the number of hits attributable to that country. Note that the total country-based hits will not necessarily match the count value exactly, as the per-country data is only an approximation.

/api/external

Returns hit information associated with an external ID.

Parameters:

apikeyrequiredidentifies the user of the API
clientrequiredidentifies the application
startoptionalfirst record to return
limitoptionalmaximum number of records to return (default is 100)
detailsoptional"True" to request more detail per hit (see return section)

The optional parameter start is the timestamp below which data is not requested. The first call should omit this, then subsequent calls should pass the timestamp of the last record returned.

If specified, the limit will control how many records are returned. Setting this to too-high a value could result in database timeouts, so it's recommended to just use the default. However, during testing, you may want to set it to a low number (like 10) in order to test that you are paging through data correctly.

Returns:

clientstringidentifies the application
lastbooleanindicates that the result includes the most recent record in the datastore
hitsarrayeach object in the array has members: {
    id: number (unique ID for this record)
    eid: string (external id, see below)
    country: string (two-letter country code) [only if details=True]
    city: string (name of a nearby city to the user, if known) [only if details=True]
    path: string (see /api/hits for an explanation)
    device: string (information about the device used) [only if details=True]
    timestamp: number (see below)
}

In some cases, a Kaon app will be provided with an external ID to use for individual behavior tracking. (Kaon does not know who these IDs correspond to, and it is the responsibility of the company providing these IDs to get proper consent from the users. See our app privacy policy.) In these cases a click-stream of activity from that user is recorded, and can be accessed using this API.

Since there could be a lot of data, the caller should expect to make multiple requests. The first request should omit the "start" attribute. Subsequent calls should pass the timestamp of the last returned record. The caller can then append all the returned records together for analysis.

The timestamp is a standard unix timestamp (integer seconds).

Comments