Perform a combinedData Request
Perform a combinedData Request
The Coveo Usage Analytics (Coveo UA) Read API stats/combinedData
endpoint allows you to retrieve metric values for combinations of selected dimensions (see /v15/stats/combinedData
).
For every origin level 1, you want to know the daily number of queries and the daily number of items that were viewed during a given period of time. You make a request to the stats/combinedData
endpoint with dimensions originLevel1
and actionDayOfYear
, and with metrics PerformSearch
and DocumentView
(see d
and m
). You also request results be sorted by day (see s
).
GET https://analytics.cloud.coveo.com/rest/ua/v15/stats/combinedData?from=2019-01-13T14:20:20.266Z&to=2019-02-13T15:20:20.266Z&d=originLevel1&d=actionDayOfYear&m=PerformSearch&m=DocumentView&s=actionDayOfYear HTTP/1.1
Authorization: Bearer **********-****-****-****-************
For every combination of originLevel1
and actionDayOfYear
(in Unix time), the service returns the number of usage analytics events which fall under the PerformSearch
category, as well as the number of usage analytics events which fall under the DocumentView
category.
200 OK response body (excerpt)
{
"combinations": [
{
"originLevel1": "CaseCreation",
"actionDayOfYear": 1547337600000,
"PerformSearch": 4513,
"DocumentView": 827
},
{
"originLevel1": "ExternalSearch",
"actionDayOfYear": 1547337600000,
"PerformSearch": 2153,
"DocumentView": 85
},
{
"originLevel1": "CaseCreation",
"actionDayOfYear": 1547424000000,
"PerformSearch": 5032,
"DocumentView": 881
},
{
"originLevel1": "ExternalSearch",
"actionDayOfYear": 1547424000000,
"PerformSearch": 2042,
"DocumentView": 92
},
...
],
...
}
-
The way the Usage Analytics Read service calculates the
PerformSearch
metric differs from the one used to calculate the query count in the Settings section of the Coveo Administration Console. -
In the above example, the
org
query parameter isn’t included, since it’s extracted form the API key. If anOAuth2
token was used, theorg
query parameter would need to be included. -
Requests that would cause the UA Read API to return more than 10,000 items in the response are rejected, returning a
400 - Parameter 'n' must be between 1 and 10000
error. If this happens, consider decreasing the scope of the request.
A typical situation in which you would want to use this endpoint is to leverage such metrics in your own application (i.e., without going through the Administration Console). This article explains how to make requests to do so.
Search integrations with Coveo typically rely on the Administration Console reports rather than on the Coveo UA Read API directly (see Usage analytics reports). This article is relevant only if your use case isn’t met by the Administration Console.
Authenticating
The Usage Analytics Read API relies on the bearer HTTP authentication scheme. All HTTP requests made to the Usage Analytics Read service must include an Authorization
header with a valid access token (i.e., an API key or OAuth2 token):
Authorization: Bearer <token>
To make requests to the Usage Analytics Read stats/combinedData
endpoint, the <token>
must grant the Analytics - Analytics data - View privilege in the target Coveo organization (see Add an API key).
If a Usage Analytics Read API request is authenticated using an OAuth2
token, you need to specify a value for the org
query parameter, as OAuth2
tokens are platform-wide and can therefore allow access to more than one Coveo organization. Otherwise, the org
value is extracted from the API key.
org
(string); the ID of the organization.
For example:
myorg6j53h4
Making a Request
A combinedData
request where only the required query parameters are specified
GET https://analytics.cloud.coveo.com/rest/ua/v15/stats/combinedData?from=2018-02-05T14:20:20.266Z&to=2019-02-05T15:20:20.266Z&m=CustomEvent&d=c_facettitle HTTP/1.1
Authorization: Bearer **********-****-****-****-************
Ensure that you URL-encode your requests (see Percent-encoding).
For example, after you URL-encode the above request, it becomes the following:
GET https%3A%2F%2Fplatform.cloud.coveo.com%2Frest%2Fua%2Fv15%2Fstats%2FcombinedData%3Ffrom%3D2018-02-05T14%3A20%3A20.266Z%26to%3D2019-02-05T15%3A20%3A20.266Z%26m%3DCustomEvent%26d%3Dc_facettitle HTTP/1.1
Authorization: Bearer **********-****-****-****-************
To make the examples in this article work in the Coveo HIPAA environment, replace platform
by analyticshipaa
in the example request headers.
For example:
GET https://analyticshipaa/rest/v15/metrics?org=myOrg HTTP/1.1
Required Query Parameters
from
(string)
The beginning date of the date range. ISO8601 format YYYY-MM-DDThh:mm:ss.sssZ
(see ISO 8601).
2018-02-05T14:20:20.266Z
to
(string)
The end date of the date range. ISO8601 format YYYY-MM-DDThh:mm:ss.sssZ
(see ISO 8601).
2019-02-05T15:20:20.266Z
m
(string)
The metric to fetch.
To fetch several metrics, send several m
query parameters.
To fetch metrics PerformSearch
and DocumentView
, append the following to your query string:
&m=PerformSearch&m=DocumentView
You can retrieve the exhaustive list of metrics available in your organization by making a request to the metrics
endpoint (see List Metrics).
d
(string)
The dimension to fetch.
To fetch several dimensions, send several d
query parameters.
To fetch dimensions originLevel1
and actionDayOfYear
, append the following to your query string:
&d=originLevel1&d=actionDayOfYear
You can retrieve the exhaustive list of dimensions available in your organization by navigating to the Dimensions page of the Coveo Administration Console (see Manage dimensions on custom metadata).
Alternatively, you can make a request to the dimensions
endpoint (see List dimensions).
Optional Query Parameters
tz
(string)
The timezone to map the from
and to
arguments into (+/-hh:mm
or IANA TZDB format).
Default value is Z
(i.e., Coordinated Universal Time).
-
America/Montreal
-
+01:00
f
(string)
The filter to apply to the event dimensions (analogous to the SQL WHERE
command). If you send many f
query parameters, the service joins them with the AND
operator.
You can define an f
argument with the Read filter syntax. You can also use preexisting named filters by preceding them by the $
character.
-
$EXCLUDE_PAGEVIEW_BOTS AND (customeventtype=='pageVisit')
where
EXCLUDE_PAGEVIEW_BOTS
is a preexisting named filter. - Alternatively, you can send several
f
query parameters. I.e., appending&f=$EXCLUDE_PAGEVIEW_BOTS AND (customeventtype=='pageVisit')
to your query string is equivalent to appending&f=$EXCLUDE_PAGEVIEW_BOTS&f=(customeventtype=='pageVisit')
to your query string.
You can retrieve the exhaustive list of named filters available in your organization by navigating to the Named Filters page of the Coveo Administration Console (see Manage Named Filters).
Alternatively, you can make a request to the filters/reporting
endpoint (see List Named Filters).
fm
(string)
The filter to apply to the event metrics (analogous to the SQL WHERE
command). If you send many fm
query parameters, the service joins them with the AND
operator.
The filter must respect the Read filter syntax.
documentView<1000
s
(string)
The name of the field to order the results by (analogous to the SQL ORDER BY
command). Must be a dimension or metric specified in the m
or the d
parameter.
If no value is provided, the result ordering is unpredictable.
documentView
p
(integer)
The 1-based number of the results page to access.
Default value is 1
.
2
n
(integer)
The number of results to include per results page.
Default value is 10
.
20
asc
(Boolean)
Whether to sort results by ascending order.
Default value is true
.
false
includeMetadata
(Boolean)
Whether to include metadata regarding the results, namely total and unique counts. Only applicable when format is set to JSON
Default value is true
.
false
format
(string)
The format of the response. Possible values are JSON
and CSV
.
Default value is JSON
.
CSV
bindOnLastSearch
(Boolean)
Whether to establish the relationship between events using the lastSearchId
or the visitId
.
Default value is true
.
In a support interface, you log a custom event with a custom data field c_caseid
whenever a support case is created. You’ve created a custom dimension on c_caseid
(see Manage dimensions on custom metadata). You want to know how many queries preceded the creation of each support case.
You send a request to the stats/combinedData
endpoint on dimension c_caseid
and metric performSearch
, with bindOnLastSearch
set to false
.
GET https://analytics.cloud.coveo.com/rest/ua/v15/stats/combinedData?from=2019-01-13T14:20:20.266Z&to=2019-02-13T15:20:20.266Z&d=c_caseid&m=PerformSearch&bindOnLastSearch=false HTTP/1.1
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
For every case created (c_caseid
), the service returns the number of search events (PerformSearch
) in the same visit.
{
"combinations": [
{
"c_caseid": "5000d00001O0PxBAAV",
"PerformSearch": 5
},
{
"c_caseid": "5000d00001P9fXJAAZ",
"PerformSearch": 3
},
...
],
...
}
If bindOnLastSearch
had been left to the default value, i.e., true
, the service would have returned the number of search events that immediately preceded the case creation, namely 0
or 1
.
{
"combinations": [
{
"c_caseid": "5000d00001O0PxBAAV",
"PerformSearch": 1
},
{
"c_caseid": "5000d00002P3fUZEEZ",
"PerformSearch": 0
},
...
],
...
}