Share:
ClickHelp Documentation

API: Reporting and Analytics

In addition to the visual reports available in Report Center, ClickHelp also allows you to retrieve data measured by your portal via the REST API. For example, reporting functions allow you to retrieve information on what Power Readers are doing when working with the portal. Various third-party systems can use this information to get insight into your end users' behavior.

Reporting functions list:


Get Topic Views

GET Request Get topic views
/api/v1/reports/user-events/{userName}/articles?startDate={startDate}&endDate={endDate} HTTP/1.1  

Returns information on topics viewed by the given Power Reader user during the given period, ordered by dates (latest go first). The userName parameter refers to the login name of the Power Reader user. The startDate and endDate parameters are date and time string values in the ISO 8601 format (a date can be in any time zone). For example, such strings can be generated by the JavaScript toISOString method.

Authorization

This request is using basic authentication.

Request parameters

Path parameters

userName

required

string The login of the user whose topic views will be retrieved. 

Query string parameters

Field Type Description
startDate DateTime Report start date timestamp string in the ISO 8601 format, in the GMT timezone.
endDate DateTime Report end date timestamp string in the ISO 8601 format, in the GMT timezone.

Request example

Below is an example of a CURL command line you can use in a batch file to get topic views of the "reader" user from December 1 (in GMT) till a specific time on December 31 of 2017 (in GMT).

Code
curl -X GET ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/reports/user-events/reader/articles?startDate=2017-12-01&endDate=2017-12-31T17:55:13%2B03:00

Response example

JSON
{[  
{
"href":"/api/v1/projects/my-manual-publication/articles/introduction",
"dateTime":"2017-12-23T13:23:45",
"referrerUrl":null,
"actionType":"FromToc"
},
{
"href":"/api/v1/projects/my-manual-publication/articles/my-topic",
"dateTime":"2017-12-07T12:11:47",
"referrerUrl":"http://test.com/best-help-topics-ever/",
"actionType":"DirectNavigation"
}
]}

Response fields

href String

The URL which can be used to retrieve detailed information on the topic viewed by the user.

dateTime String

Event timestamp string in the ISO 8601 format, in the GMT timezone.

referrerUrl String The URL of the referrer page from which the user navigated to the topic.
actionType String

The type of the topic view action. It can be one of the following:

  • DirectNavigation - navigation via link clicks.
  • FromToc - the topic was opened as a result of a TOC node click.
  • FromIndex - the topic was opened by index keyword click.
  • FromSearch - the topic was opened from full-text search results.
  • FromContextHelp - the topic was loaded as a Context Help snippet.

Response codes

All API functions may return error codes listed in the Error Handling topic. Below are the operation-specific meanings of some response codes:

200: OK

The request has succeeded, the response body contains the requested information.

403: Forbidden

The user does not have the permission to view Power Reader profiles.

Get Full-Text Search Queries

GET Request Get full-text search queries
/api/v1/reports/user-events/{userName}/search-queries?startDate={startDate}&endDate={endDate} HTTP/1.1 

Returns information on full-text search queries performed by the given Power Reader user during the given period, ordered by dates (latest go first). The userName parameter refers to the login name of the Power Reader user. The startDate and endDate parameters are date and time string values in the ISO 8601 format (a date can be in any time zone). For example, such strings can be generated by the JavaScript toISOString method.

Authorization

This request is using basic authentication.


Request parameters

Path parameters

userName

REQUIRED

stringThe login of the user whose search queries will be retrieved. 

Query string parameters

FieldTypeDescription
startDatedatetimeReport start date timestamp string in the ISO 8601 format, in the GMT timezone.
endDatedatetimeReport end date timestamp string in the ISO 8601 format, in the GMT timezone.

Request example

Below is an example of a CURL command line you can use in a batch file to get full-text search queries of the "reader" user from December 1 (in GMT) till specific time on December 31 of 2017 (in GMT+3).

Code
curl -X GET ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/reports/user-events/reader/search-queries?startDate=2017-12-01&endDate=2017-12-31T17:55:13%2B03:00

Response example

JSON
{[  
{
"queryText":"getting data",
"dateTime":"2017-12-23T13:23:45",
"resultsTotal":456,
},
{
"queryText":"how to write to files",
"dateTime":"2017-12-07T12:11:47",
"resultsTotal":0
}
]}

Response fields

Field Type Description
queryText String

The full-text search query.

dateTime String

Event timestamp string in the ISO 8601 format, in the GMT timezone.

resultsTotal Integer The total number of search results returned.

Response codes

All API functions may return error codes listed in the Error Handling topic. Below are the operation-specific meanings of some response codes:

200: OK

The request has succeeded, the response body contains the requested information.

403: Forbidden

The user does not have permission to view Power Reader profiles.