ClickHelp Documentation

API: Reporting and Analytics

ClickHelp User Manual/ClickHelp API/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 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. To get the data for anonymous users, use - instead of the user name.
The startDate and endDate parameters are date and time string values in the ISO 8601 format (a date can be in any time zone). 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).

Copy Code

Code

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

Response example

Copy Code

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 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. To get the data for anonymous users, use - instead of the user name.
The startDate and endDate parameters are date and time string values in the ISO 8601 format (a date can be in any time zone). 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 search queries 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 full-text search queries of the "reader" user from December 1 (in GMT) till specific time on December 31 of 2017 (in GMT+3).

Copy Code

Code

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

Response example

Copy Code

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.

API: Project Management Reporting and Analytics