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
Documentation last update: April 2021

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.

More information here

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.

More information here

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.

More information here

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

More information here

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.)

More information here

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.

Multiple IDs should be separated by a comma

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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
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. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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: `up` `down` `left` `right` `hor` (for horizontal) `vert` (for vertical)

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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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: `up` `down` `left` `right` `hor` (for horizontal) `vert` (for vertical)

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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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: `up` `down` `left` `right` `hor` (for horizontal) `vert` (for vertical)

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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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. Default: none Must be a date prior to endDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
endDate	Required. End of date range for analysis. Default: none Must be a date after startDate ISO format in UTC (eg. "2021-08-13T12:32:40.000Z") or with a time zone offset (eg. "2021-08-13T12:32:40+02:00" or "2021-08-13T12:32:40%2B+02:00" when encoded in the URL)
device	Device filter for analysis. Default: all Available values: all, desktop, mobile, tablet
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. Default: none Available values: daily
segmentIds	Filter analysis with Contentsquare segments. Default: All visitors You can specify multiple segments separated by commas to retrieve the metrics for the intersection of the specified 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
}