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.
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.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
The Contentsquare Metrics API uses API keys to authenticate requests. You can view and manage your API keys in the console.
You can either get an API key:
- At the Project level: to request metrics for a specific project only
- At the Account level: to request metrics for any project of an account
Your API keys carry many privileges, so make sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via Bearer auth. Provide your API key as the basic auth username value. You do not need to provide a password. Use "Authorization: Bearer YOUR_API_KEY" in your HTTP request header.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Limits
Per project
- 15 000 requests/month (renewed the first day of each month)
- 10 concurrent requests maximum
- 5 API keys per project
- Data available limited to client's contractual retention period
Note that limitations are tracked at the project-level, not at the API key level. So if you have created several API keys for a project, the total number of requests from those keys must not exceed 15,000 over a month.
Per account
- 300 000 requests/month (renewed the first day of each month)
- 10 concurrent requests maximum
- 3 API keys per account
- Data available limited to client's contractual retention period
Note that limitations are tracked at the account-level, not at the API key level. So if you have created several API keys for an account, the total number of requests from those keys must not exceed 300,000 over a month.
Also note that account-level and project-level limitations are independent. So you can send 300,000 requests with an account API key AND 15,000 requests with a project API key over the same month.
You can check your remaining quota in the HTTP response header x-quota-remaining of any request. The information is also visible in the console.
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.
API key information
/v1/me
This endpoint provides information about the current API Key and the related project or account.
Example of response
{
"payload": {
"keyName": "Contentsquare customer test",
"projectId": 162,
"projectName": "Contentsquare.com",
"createdAt": "2019-09-04T13:22:17.000Z"
},
"success": true
}Projects
/v1/me/projects
This endpoint provides the list of all the projects attached to the current account. It is relevant for account-level API keys only.
Example of response
{
"payload": [
{
"id": 1,
"name": "myProjectName"
}
],
"success": true
}Segments
/v1/segments
Get the list of all segments for a project. More information regarding segments in Contentsquare
Parameters
| projectId | Only required for an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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
}Pages
/v1/mappings/{mappingId}/page-groups
Get all the pages for a specific mapping More information regarding mappings and page groups in Contentsquare
Parameters
| projectId | Only required for an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 Metrics Endpoints
All page groups metrics
/v1/metrics/page-group/{pageGroupId}
Returns all page group metrics between two dates.
Parameters
| projectId | Only required for an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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 an account-level API key. 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
}