Metrics API
The Contentsquare Metrics API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. All API requests must be made over HTTPS.
Not a developer? Contact your CSM. They will direct you to the best solution to meet your data needs, whether it's connectors (such as Google Data Studio or Reeport) or the help of the Professional Services team at Contentsquare.
- Base URL of the API:
https://api.{cloud}.contentsquare.com - Current Version of the API: 1.0
What is Contentsquare?
Contentsquare is a next-gen Analytics tool that helps you understand how and why your users are interacting with your app, mobile and websites.
To understand the metrics exposed by the API Metrics you should understand some very important concepts of Contentsquare. The metrics are obtained based on elements created and managed within the Contentsquare interface.
What is a mapping?
Defined by a name and set of pages, a mapping helps model your site by grouping together your site's URLs into page groups. Thanks to multiple mappings of varying granularity, you can analyze your site at a macro and micro level.
Contentsquare's Mappings are organized into URLs which are sorted in different "page groups" and the "page groups" are grouped under different categories.
What is a page group?
Contentsquare's page groups allow you to gather and group one or several URLs of the same type. By type we mean a set of pages of your website that share the same template and function. E.g. Product pages, List pages, etc.
Gathering URLs into "buckets" is the easiest way to analyze your website according to different levels of granularity.
What is a zoning?
The Zoning Analysis module allows you to analyze visitors' in-page navigation. You can differentiate clickable areas on the page, called "zones". Zoning Analysis has a large range of metrics so as to provide the most accurate and deepest in-page analysis. This way, you can determine what zones bring navigation anomalies and should be changed or moved.
You can perform your analysis with segment or goals.
Zonings split your page groups into zones. The definition of zones is based on the div of your HTML code.
You can create multiple zonings for the same page group.
What is a goal?
A Goal is a navigation event collected by the tag.
A goal can be one of three types:
- A page view
- A select a zone
- A hover over a zone
What is a segment?
Segments help you to divide visitors into homogeneous population groups based on behaviors. A segment can be composed of:
- Conditions tied to visitors’ context (location, technology used, language, etc.)
- Conditions tied to visitors’ intention (behaviors, visit time, page viewed, etc.)
Authentication
Overview
The Contentsquare APIs use the server-to-server OAuth 2.0 standard for authentication, also know as 2-legged OAuth or OAuth 2LO.
The flow basically consists in calling an authentication endpoint with a pair client_id / client_secret to retrieve
an access token that remains valid for 1 hour. This JWT token should then be used as a Bearer token in the headers of
your HTTPS requests (in the form Authorization: Bearer YOUR_ACCESS_TOKEN).
Note that the API call to the authentication endpoint will also dynamically return the right base URL that you must use. This base URL depends on which cloud the target project is installed on.
You can refer below to a detailed example of the overall flow to retrieve a token and a base URL, and use those to make query the Metrics API.
You can generate a pair client_id / client_secret from the Contentsquare console,
as a Contentsquare administrator. You can find how to generate these credentials in our Help Center documentation.
You can create OAuth credentials either:
- At the Project level, to request access resources from a specific project only
- At the Account level: to request access for any project of the account
Refresh your access token
Once you get a JWT access token (see the authentication endpoint below), it's valid for 1 hour.
If you try to query the Contentsquare APIs with an access token that has expired, you will receive a 401 Unauthorized
error with the error code JWT_EXPIRED, in the form:
{
"success": false,
"errorMessage": "Auth token is expired.",
"errorCode": "JWT_EXPIRED"
}In that case, you should first use your OAuth credentials (your pair client_id / client_secret) to query a new
access token. The OAuth credentials don't expire.
Authentication endpoint
POST https://api.contentsquare.com/v1/oauth/token
Parameters
These parameters have to be provided in the body of the request.
client_id | Required. The OAuth client_id generated from the Contentsquare console |
|---|---|
client_secret | Required. The OAuth client_secret generated from the Contentsquare console |
grant_type | Required. Always set it to |
scope | Required. You should use |
project_id | Optional. Only required if you use account-level OAuth credentials, to specify which project of the account you want to target |
Request example
curl --location 'https://api.contentsquare.com/v1/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "c3133d76-a768-4f5a-XXX",
"client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX",
"grant_type": "client_credentials",
"scope": "metrics",
"project_id": 42
}'
Response example
{
"access_token": "eyJhbGciOiJSIsImtpY5MTXXX.CNTcKWAUb2mTp2cZyiDRYYOtGCKXXX", // to be used as bearer token to query the APIs
"token_type": "bearer",
"expires_in": 3600,
"scope": "metrics",
"project_id": 42,
"endpoint": "https://api.eu-west-1.production.contentsquare.com" // this is the base URL you should use to query the Metrics API endpoints - the providded URL depends on the cloud the project is installed on
}Example of authentication flow
Below is a sample of Javascript code to show a complete API call flow that first retrieves an access token and then use it to retrieve the list of segments on a project:
const clientId = "<your_client_id>";
const clientSecret = "<your_client_secret>";
const authEndpoint = "https://api.contentsquare.com/v1/oauth/token";
const authRequestOptions = {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: clientId,
client_secret: clientSecret,
grant_type: "client_credentials",
project_id: 42,
scope: "metrics",
}),
};
const authResponse = await fetch(authEndpoint, authRequestOptions);
const authJsonData = await authResponse.json();
// Below are the access token and base URL that must be used to query the Metrics API endpoints
const accessToken = authJsonData.access_token;
const baseURL = authJsonData.endpoint;
// Using the access token and base URL to query the Metrics API endpoints and get the segments in this example
const metricsApiEndpointResponse = await fetch(`${baseURL}/v1/segments`, {
headers: { Authorization: `Bearer ${accessToken}` },
});
const metricsApiEndpointauthJsonData = await metricsApiEndpointResponse.json();
const segments = metricsApiEndpointauthJsonData.payload;OAuth credentials information endpoint
POST https://api.contentsquare.com/v1/oauth/me
Parameters
None.
Request example
curl --location 'https://api.contentsquare.com/v1/oauth/me' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "c3133d76-a768-4f5a-XXX",
"client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX",
}'
Response example
{
"scopes": "metrics data-export session-replay symbolicator",
"permissions": {
"projects": [
{
"id": 42,
"name": "UX ANALYTICS"
}
]
}
}Limits
- 10 concurrent requests maximum per project
- 10 OAuth credentials (
client_id/client_secret) per project and per account maximum - The data available for query is limited to the project contractual data retention period
Date ranges
For metrics endpoints, you need to specify the date range you want to query. As in our CS Digital platform, you cannot query more than 92 days of data for at once (this is to guarantee reliability and performance). If a date range exceeds 92 days or is out of the project data retention period, the API will return an error message indicating that the range is out of bonds.
In terms of format, dates must respect one of the following ISO formats:
- 2021-08-13T12:32:40.000Z (
YYYY-MM-DDThh:mm:ss.sssZ) for a date in UTC. - 2021-08-13T12:32:40 (
YYYY-MM-DDThh:mm:ss), equivalent to 2021-08-13T12:32:40.000Z. - 2021-08-13T12:32 (
YYYY-MM-DDThh:mm), equivalent to 2021-08-13T12:32:00.000Z. - 2021-08-13 (
YYYY-MM-DD), equivalent to 2021-08-13T00:00:00.000Z. - 2021-08 (
YYYY-MM), equivalent to 2021-08-01T00:00:00.000Z. - 2021-08-13T12:32:40+02:00 (
YYYY-MM-DDThh:mm:ss+hh:mm) where the part after the+(it can also be-) represents the time zone UTC offset. Keep in mind that when specifying dates in URL parameters, the+character must be encoded into%2B(e.g. 2021-08-13T12:32:40%2B02:00). - 2021-08-13T12:32+02:00 (
YYYY-MM-DDThh:mm+hh:mm), equivalent to 2021-08-13T12:32:00+02:00.
Objects Endpoints
The metrics API replicates the behavior of the analysis context in Contentsquare. To get a metric, you can filter by device, segment etc. Plus, for page groups and zones metrics, you will have to define for which page group or zones you want data. To help you, we provide an API that retrieves these objects: segments, page groups etc.
Segments
/v1/segments
Get the list of all segments for a project. More information regarding segments in Contentsquare
Parameters
| projectId | Only required for account-level OAuth credentials. The target project. |
|---|---|
| ids | Filter the results and get a list of segments that matches the ids provided.
|
Example of response
{
"payload": [
{
"id": 1,
"name": "New visitors",
"source": "contentsquare",
"createdAt": "2019-11-21T09:46:16.000Z",
"updatedAt": "2019-11-21T09:46:16.000Z"
}
],
"success": true
}Goals
/v1/goals
Get the list of all goals for a project. More information regarding goals in Contentsquare
Example of response
{
"payload": [
{
"id": 100,
"name": "Reach Cart",
"type": "pageview",
"createdAt": "2019-10-05T10:34:42.670Z",
"updatedAt": "2019-11-21T09:46:09.000Z"
}
],
"success": true
}| projectId | Only required for OAuth credentials. The target project. |
|---|
Mappings
/v1/mappings
Get the list of all mappings for a project. More information regarding mappings in Contentsquare
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| ids | Filter the results and get a list of mappings that matches the ids provided. Multiple IDs should be separated by a comma |
Example of response
{
"payload": [
{
"id": 101010,
"name": "New Zoning Mapping",
"description": "Test",
"createdAt": "2019-11-05T09:44:51.000Z",
"updatedAt": "2019-11-05T09:45:05.000Z"
}
],
"success": true
}/v1/mappings/{mappingId}
Get information for a specific mapping More information regarding mappings in Contentsquare
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|
Example of response
{
"payload": [
{
"id": 101010,
"name": "New Zoning Mapping",
"description": "Test",
"createdAt": "2019-11-05T09:44:51.000Z",
"updatedAt": "2019-11-05T09:45:05.000Z"
}
],
"success": true
}Page groups
/v1/mappings/{mappingId}/page-groups
Get all the page groups for a specific mapping More information regarding mappings and page groups in Contentsquare
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|
Example of response
{
"payload": [
{
"id": 1010,
"name": "Product Pages",
"category": "Other"
}
],
"success": true
}/v1/page-groups/{pageGroupId}
Get information about a page and all the related mappings More information regarding page groups in Contentsquare
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|
Example of response
{
"payload": {
"id": 1010,
"name": "Product pages",
"category": "Other",
"mappings": [
{
"id": 147,
"name": "Ecommerce",
"description": null,
"createdAt": "2018-10-16T11:37:36.000Z",
"updatedAt": "2019-08-21T07:12:18.000Z"
},
{
"id": 148,
"name": "All pages",
"description": null,
"createdAt": "2018-10-16T12:49:49.000Z",
"updatedAt": "2019-08-21T07:12:23.000Z"
}
]
},
"success": true
}Zonings
/v1/page-groups/{pageGroupId}/zonings
Get all the zonings for a page group More information regarding zonings in Contentsquare
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|
Example of response
{
"payload": [
{
"id": 100,
"name": "Revamp product page",
"createdAt": "2019-10-25T13:12:45.000Z",
"lastUpdatedAt": "2019-10-29T11:11:22.000Z"
}
],
"success": true
}Zones
/v1/zonings/{zoningId}/zones
Get all the zones for a zoning More information regarding zonings in Contentsquare
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|
Example of response
{
"payload": [
{
"id": 100,
"name": "Add to cart button"
}
],
"success": true
}Site Metrics Endpoints
All site metrics
/v1/metrics/site
Returns all site metrics between two dates.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| goalId | To return conversion metrics for a non-ecommerce goal |
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 93.00790024010534,
"name": "bounceRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 186.890756302521,
"name": "cartAverage",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 3649,
"name": "conversionCount",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7.068828577516902,
"name": "conversionRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.1468321586244288,
"name": "pageviewAverage",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 22240,
"name": "revenue",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 3.1195242041669893,
"name": "sessionTimeAverage",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.1468321586244288,
"name": "viewsVisits",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 100,
"name": "visitRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 51644,
"name": "visits",
"currency": "USD"
}
]
},
"success": true
}Bounce rate
/v1/metrics/site/bounce-rate
The ratio between the visitors who entered the site and left it without having seen a second page and all visitors.
More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 93.00790024010534,
"name": "bounceRate",
"currency": "USD"
}
]
},
"success": true
}Cart average
/v1/metrics/site/cart-average
The average cart amount is calculated by dividing the total revenue by the number of transactions. This metric is only accessible for "e-commerce" projects.
More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 186.890756302521,
"name": "cartAverage",
"currency": "USD"
}
]
},
"success": true
}Conversions
/v1/metrics/site/conversions
The number of sessions where a specified goal was reached. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| goalId | Only required for non "e-commerce" projects. Goal filter for analysis. If not specified for an "e-commerce" project, the API will return data for the "e-commerce" goal. |
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 3649,
"name": "conversionCount",
"currency": "USD"
}
]
},
"success": true
}Conversion rate
/v1/metrics/site/conversion-rate
Ratio between the number of sessions where a specified goal was reached and the total number of sessions. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| goalId | Only required for non "e-commerce" projects. Goal filter for analysis. If not specified for an "e-commerce" project, the API will return data for the "e-commerce" goal. |
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7.068828577516902,
"name": "conversionRate",
"currency": "USD"
}
]
},
"success": true
}Pageview average
/v1/metrics/site/pageview-average
Average number page views during a session (a page that has been refreshed counts as one view).
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.1468321586244288,
"name": "pageviewAverage",
"currency": "USD"
}
]
},
"success": true
}Revenue
/v1/metrics/site/revenue
Sum of all the transaction amounts. This metric is only accessible for "e-commerce" projects.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 22240,
"name": "revenue",
"currency": "USD"
}
]
},
"success": true
}Session time average
/v1/metrics/site/session-time-average
Average time spent from entry on the site to site exit for each visit.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 3.1195242041669893,
"name": "sessionTimeAverage",
"currency": "USD"
}
]
},
"success": true
}Visits
/v1/metrics/site/visits
Number of sessions. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 51644,
"name": "visits",
"currency": "USD"
}
]
},
"success": true
}Page Group Metrics Endpoints
All page groups metrics
/v1/metrics/page-group/{pageGroupId}
Returns all page group metrics between two dates.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| goalId | To return conversion metrics for a non-ecommerce goal |
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 4.820247587511826,
"name": "activityRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 64.65578424414478,
"name": "bounceRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 4.267288693743139,
"name": "conversionRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 9.558127422045425,
"name": "elapsedTime",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 63.23623764917233,
"name": "exitRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 907.4778647504171,
"name": "foldHeight",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1009.0064436943848,
"name": "interactionTime",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 13.648339726452013,
"name": "landingRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.6267757352941177,
"name": "loadingTime",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 3862.80071859361,
"name": "pageHeight",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 53.2996317888923,
"name": "scrollRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 4.267288693743139,
"name": "transformationRate",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7284,
"name": "uniqueVisits",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7793,
"name": "views",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.0692919868276618,
"name": "viewsVisits",
"currency": "USD"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7288,
"name": "visits",
"currency": "USD"
}
]
},
"success": true
}Activity rate
/v1/metrics/page-group/{pageGroupId}/activity-rate
The ratio of time visitors spend interacting with the page to the time spent on the page. Displayed as percentage. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 4.820247587511827,
"name": "activityRate",
"currency": "USD"
}
]
},
"success": true
}Bounce rate
/v1/metrics/page-group/{pageGroupId}/bounce-rate
The ratio between the visitors who landed on the page and left the site without having seen a second page and all visitors who landed on the page. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 64.65578424414478,
"name": "bounceRate",
"currency": "USD"
}
]
},
"success": true
}Conversion rate
/v1/metrics/page-group/{pageGroupId}/conversion-rate
Ratio between the number of users that viewed the page and reached the goal during their navigation and the number of users that viewed the page.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| goalId | Only required for non "e-commerce" projects. Goal filter for analysis. If not specified for an "e-commerce" project, the API will return data for the "e-commerce" goal. |
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 4.267288693743139,
"name": "conversionRate",
"currency": "USD"
}
]
},
"success": true
}Time spent / Elapsed time
/v1/metrics/page-group/{pageGroupId}/elapsed-time
The average time spent on the page, from the first page view trigger to the last event sent. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 9.558127422045425,
"name": "elapsedTime",
"currency": "USD"
}
]
},
"success": true
}Exit rate
/v1/metrics/page-group/{pageGroupId}/exit-rate
The ratio between the number of views of the page which are the last page view of the session and the total number of views of the page. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 63.23623764917233,
"name": "exitRate",
"currency": "USD"
}
]
},
"success": true
}Height / Fold Height
/v1/metrics/page-group/{pageGroupId}/fold-height
Average screen height.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 907.4778647504171,
"name": "foldHeight",
"currency": "USD"
}
]
},
"success": true
}Interaction time
/v1/metrics/page-group/{pageGroupId}/interaction-time
The average time spent interacting on the page.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1009.0064436943848,
"name": "interactionTime",
"currency": "USD"
}
]
},
"success": true
}Landing rate
/v1/metrics/page-group/{pageGroupId}/landing-rate
Ratio between users that landed on this screen and the total number of users. For mobile project only.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 13.648339726452013,
"name": "landingRate",
"currency": "USD"
}
]
},
"success": true
}Loading time / Load time
/v1/metrics/page-group/{pageGroupId}/loading-time
The average time in seconds between the call of the page and when the visitor can start interacting with it. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.6267757352941177,
"name": "loadingTime",
"currency": "USD"
}
]
},
"success": true
}Page height
/v1/metrics/page-group/{pageGroupId}/page-height
The average height of the page in pixels at its first load (an average for all the URLs included in the page). More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 3862.80071859361,
"name": "pageHeight",
"currency": "USD"
}
]
},
"success": true
}Scroll rate
/v1/metrics/page-group/{pageGroupId}/scroll-rate
The proportion of the page displayed by visitors (the ratio between the last line of pixels displayed on the screen and the height of the page). More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 53.2996317888923,
"name": "scrollRate",
"currency": "USD"
}
]
},
"success": true
}Unique visits
/v1/metrics/page-group/{pageGroupId}/unique-visits
The number of unique users who saw the selected page at least once during their session.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7284,
"name": "uniqueVisits",
"currency": "USD"
}
]
},
"success": true
}Views
/v1/metrics/page-group/{pageGroupId}/views
The number of times the page was viewed. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7793,
"name": "views",
"currency": "USD"
}
]
},
"success": true
}Views / Visit
/v1/metrics/page-group/{pageGroupId}/views-visits
The average number of times the page is viewed per visit. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.0692919868276618,
"name": "viewsVisits",
"currency": "USD"
}
]
},
"success": true
}Visits
/v1/metrics/page-group/{pageGroupId}/visits
Number of sessions where the page has been seen at least once. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7288,
"name": "visits",
"currency": "USD"
}
]
},
"success": true
}Zone Metrics Endpoints (Web)
All zone metrics
/v1/metrics/zone/{zoneId}
Returns all zone metrics between two dates
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| goalId | To return conversion metrics for a non-ecommerce goal |
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 6.033720930232558,
"name": "averageRevenueAfterClick",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 10.497237569060774,
"name": "avgConversionAfterClick",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 10.9011137360783,
"name": "avgConversionAfterHover",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 0.003087246192893401,
"name": "avgHoverTime",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 33.472123489387634,
"name": "clickRate",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 1.4462985436893203,
"name": "clickRepetition",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 104.56852791878173,
"name": "engagementRateLive",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 0.5985779733009708,
"name": "hesitation",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 32.00974916218137,
"name": "hoverRate",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 15.274424150485437,
"name": "timeBeforeFirstClick",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 4767,
"name": "totalClicks",
"device": "desktop",
"currency": "USD"
},
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T09:59:03.543Z",
"value": 25945,
"name": "totalRevenueAfterClick",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Attractiveness rate
/v1/metrics/zone/{zoneId}/attractiveness-rate
The percentage of page views with at least one select the zone out of the views where the zone was displayed. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-10-10T22:00:00.000Z",
"endDate": "2021-10-17T21:59:59.000Z",
"value": 4.808743169398907,
"name": "attractivityRate",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Click rate
/v1/metrics/zone/{zoneId}/click-rate
The percentage of pageviews with at least one select the zone. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:10:50.314Z",
"value": 33.472123489387634,
"name": "clickRate",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Click recurrence
/v1/metrics/zone/{zoneId}/click-recurrence
The average number of clicks on the zone, for pageviews with at least one select the zone. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:11:13.661Z",
"value": 1.4462985436893203,
"name": "clickRepetition",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Conversion Rate per Click
/v1/metrics/zone/{zoneId}/conversion-rate-per-click
Percentage of visitors who achieved the goal after clicking on a zone This metric allows you to determine whether interaction (click) with a zoning encourages or prevents visitors from exhibiting the goal. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| goalId | Only required for non "e-commerce" projects. Goal filter for analysis. If not specified for an "e-commerce" project, the API will return data for the "e-commerce" goal. |
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:11:44.754Z",
"value": 10.497237569060774,
"name": "avgConversionAfterClick",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Conversion Rate per Hover
/v1/metrics/zone/{zoneId}/conversion-rate-per-hover
Percentage of visitors who achieved the goal after hovering on a zone This metric allows you to determine whether consumption (hover) of zone is contributing or detrimental to completing the goal. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| goalId | Only required for non "e-commerce" projects. Goal filter for analysis. If not specified for an "e-commerce" project, the API will return data for the "e-commerce" goal. |
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:12:16.518Z",
"value": 10.9011137360783,
"name": "avgConversionAfterHover",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Engagement Rate
/v1/metrics/zone/{zoneId}/engagement-rate
Percentage of visitors who clicked after having hovered a zone This metric translates the affordance of an element, i.e. its capacity to define how it should be interacted with through its design. For example, the design of a CTA should make it obvious that it should be clicked. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:12:56.222Z",
"value": 104.56852791878173,
"name": "engagementRateLive",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Exposure rate
/v1/metrics/zone/{zoneId}/exposure-rate
The exposure rate takes into account the time spent on a zone. If a user scrolled through a zone very quickly, it will not be taken into account in the exposure data. A zone can only be considered "exposed" if it has been displayed for at least 150 milliseconds. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-10-10T22:00:00.000Z",
"endDate": "2021-10-17T21:59:59.000Z",
"value": 87.4,
"name": "exposureRate",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Exposure time
/v1/metrics/zone/{zoneId}/exposure-time
Time a zone was exposed. A zone can only be considered "exposed" if it has been displayed for at least 150 milliseconds. If you scroll fast from the top to the bottom of the page, the middle page will not be taken into account as the scroll movement is too fast to consider the zones in the middle have been exposed.. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-10-10T22:00:00.000Z",
"endDate": "2021-10-17T21:59:59.000Z",
"value": 20.451490710382515,
"name": "exposureTime",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Hesitation time
/v1/metrics/zone/{zoneId}/hesitation
Average time elapsed between the last hover and the first select a zone This metric translates whether the content is understood quickly or if users hesitate before clicking. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:13:21.844Z",
"value": 0.5985779733009708,
"name": "hesitation",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Hover Rate
/v1/metrics/zone/{zoneId}/hover-rate
Percentage of users who hovered a zone at least once This metric determines which zones are consumed the most. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:13:51.154Z",
"value": 32.00974916218137,
"name": "hoverRate",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Hover time / Float time
/v1/metrics/zone/{zoneId}/hover-time
Average total time spent hovering over an element This metric translates interest or lack of clarity, depending on the type of element. For example, a float time over 3 seconds is positive on an image or description text but is not on a CTA. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:14:10.533Z",
"value": 0.003087246192893401,
"name": "avgHoverTime",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Number of clicks
/v1/metrics/zone/{zoneId}/number-of-clicks
The total number of clicks on the zone, for pageviews with at least one select the zone.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:14:33.276Z",
"value": 4767,
"name": "totalClicks",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Revenue
/v1/metrics/zone/{zoneId}/revenue
Total revenue generated by the segmented users after they clicked on an element. This metric ranks elements based on their contribution to revenue. More information regarding the metric and how to interpret it...
This metric is only accessible for "e-commerce" projects.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:14:56.993Z",
"value": 25945,
"name": "totalRevenueAfterClick",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Revenue per Click
/v1/metrics/zone/{zoneId}/revenue-per-click
Average revenue per click generated by users after they clicked on an element This metric ranks elements based on their contribution to revenue. More information regarding the metric and how to interpret it...
This metric is only accessible for "e-commerce" projects.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:15:15.384Z",
"value": 7.871662621359223,
"name": "averageRevenueAfterClick",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Time Before First Click
/v1/metrics/zone/{zoneId}/time-before-first-click
Number of seconds between page load and first select an element This metric identifies which elements were interacted with first. More information regarding the metric and how to interpret it...
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-08-03T00:00:00.000Z",
"endDate": "2021-08-11T17:15:40.261Z",
"value": 15.274424150485437,
"name": "timeBeforeFirstClick",
"device": "desktop",
"currency": "USD"
}
]
},
"success": true
}Zone Metrics Endpoints (Apps)
All zone metrics
/v1/metrics/zone/{zoneId}
Returns all zone metrics between two dates
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| direction | The swipe direction for swipe metrics (swipe rate and swipe recurrence). If not specified, those metrics won't be returned. Can be one of the following values:
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 16.953225338691635,
"name": "avgTransactionAfterTap",
"device": "mobile",
"currency": "EUR"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 0.11907269940804448,
"name": "dragFlickRate",
"device": "mobile",
"currency": "EUR"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.0633130962705983,
"name": "dragFlickRecurrence",
"device": "mobile",
"currency": "EUR"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7.6946619277745105,
"name": "revenuePerTap",
"device": "mobile",
"currency": "EUR"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 12.096980737693068,
"name": "tapRate",
"device": "mobile",
"currency": "EUR"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.0165105816266422,
"name": "tapRecurrence",
"device": "mobile",
"currency": "EUR"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 4.493400932241734,
"name": "timeBeforeFirstTap",
"device": "mobile",
"currency": "EUR"
},
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 902791.6,
"name": "totalRevenueWithTap",
"device": "mobile",
"currency": "EUR"
}
]
},
"success": true
}Conversion rate per tap
/v1/metrics/zone/{zoneId}/conversion-rate-per-tap
Of users that tapped on the zone, the percentage that also completed the selected goal during the same session.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| goalId | Only required for non "e-commerce" projects. Goal filter for analysis. If not specified for an "e-commerce" project, the API will return data for the "e-commerce" goal. |
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 16.953225338691635,
"name": "avgConversionAfterTap",
"device": "mobile",
"currency": "EUR"
}
]
},
"success": true
}Revenue
/v1/metrics/zone/{zoneId}/revenue
Total revenue generated by users who clicked on the zone.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 900157.6,
"name": "totalRevenueWithTap",
"device": "mobile",
"currency": "EUR"
}
]
},
"success": true
}Revenue per tap
/v1/metrics/zone/{zoneId}/revenue-per-tap
Average revenue per tap generated by users after they tapped on an element.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 7.684434465625721,
"name": "revenuePerTap",
"device": "mobile",
"currency": "EUR"
}
]
},
"success": true
}Swipe rate
/v1/metrics/zone/{zoneId}/swipe-rate
Percentage of users performing at least one swipe on a zone during a screen display.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| direction | Required. The swipe direction for swipe metrics (swipe rate and swipe recurrence). If not specified, those metrics won't be returned. Can be one of the following values:
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 0.6463799007761929,
"name": "dragFlickRate",
"device": "mobile",
"currency": "EUR"
}
]
},
"success": true
}Swipe recurrence
/v1/metrics/zone/{zoneId}/swipe-recurrence
Average number of times an element was swiped when engaged with during a screenview.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
| direction | Required. The swipe direction for swipe metrics (swipe rate and swipe recurrence). If not specified, those metrics won't be returned. Can be one of the following values:
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.0633130962705983,
"name": "dragFlickRecurrence",
"device": "mobile",
"currency": "EUR"
}
]
},
"success": true
}Tap rate
/v1/metrics/zone/{zoneId}/tap-rate
Percentage of users that tapped on the zone at least once.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 12.096980737693068,
"name": "tapRate",
"device": "mobile",
"currency": "EUR"
}
]
},
"success": true
}Tap recurrence
/v1/metrics/zone/{zoneId}/tap-recurrence
Average number of times an element was tapped when engaged with during a screenview.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 1.0165105816266422,
"name": "tapRecurrence",
"device": "mobile",
"currency": "EUR"
}
]
},
"success": true
}Time before first tap
/v1/metrics/zone/{zoneId}/time-before-first-tap
Number of seconds between screen load and first tap on an element.
Parameters
| projectId | Only required for OAuth credentials. The target project. |
|---|---|
| startDate | Required. Beginning of date range for analysis.
|
| endDate | Required. End of date range for analysis.
|
| device | Device filter for analysis.
|
| period | Granularity of the results. Can only be used on a date range larger then one day. It allows you to have data for each day instead of having a combine result.
|
| segmentIds | Filter analysis with Contentsquare segments.
|
Example of response
{
"payload": {
"values": [
{
"startDate": "2021-07-16T00:00:00.000Z",
"endDate": "2021-07-22T00:00:00.000Z",
"value": 4.493400932241734,
"name": "timeBeforeFirstTap",
"device": "mobile",
"currency": "EUR"
}
]
},
"success": true
}