Metrics API

Last updated on

The Contentsquare Metrics API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. All API requests must be made over HTTPS.

Not a developer? Contact your CSM. They will direct you to the best solution to meet your data needs, whether it's connectors (such as Google Data Studio or Reeport) or the help of the Professional Services team at Contentsquare.

  • Base URL of the API: https://api.{cloud}.contentsquare.com
  • Current Version of the API: 1.0

What is Contentsquare?

Contentsquare is a next-gen Analytics tool that helps you understand how and why your users are interacting with your app, mobile and websites.

To understand the metrics exposed by the API Metrics you should understand some very important concepts of Contentsquare. The metrics are obtained based on elements created and managed within the Contentsquare interface.

What is a mapping?

Defined by a name and set of pages, a mapping helps model your site by grouping together your site's URLs into page groups. Thanks to multiple mappings of varying granularity, you can analyze your site at a macro and micro level.

Contentsquare's Mappings are organized into URLs which are sorted in different "page groups" and the "page groups" are grouped under different categories.

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

Overview

The Contentsquare APIs use the server-to-server OAuth 2.0 standard for authentication, also know as 2-legged OAuth or OAuth 2LO.

The flow basically consists in calling an authentication endpoint with a pair client_id / client_secret to retrieve an access token that remains valid for 1 hour. This JWT token should then be used as a Bearer token in the headers of your HTTPS requests (in the form Authorization: Bearer YOUR_ACCESS_TOKEN).

Note that the API call to the authentication endpoint will also dynamically return the right base URL that you must use. This base URL depends on which cloud the target project is installed on.

You can refer below to a detailed example of the overall flow to retrieve a token and a base URL, and use those to make query the Metrics API.

You can generate a pair client_id / client_secret from the Contentsquare console, as a Contentsquare administrator. You can find how to generate these credentials in our Help Center documentation.

You can create OAuth credentials either:

  • At the Project level, to request access resources from a specific project only
  • At the Account level: to request access for any project of the account

Refresh your access token

Once you get a JWT access token (see the authentication endpoint below), it's valid for 1 hour. If you try to query the Contentsquare APIs with an access token that has expired, you will receive a 401 Unauthorized error with the error code JWT_EXPIRED, in the form:

{
  "success": false,
  "errorMessage": "Auth token is expired.",
  "errorCode": "JWT_EXPIRED"
}

In that case, you should first use your OAuth credentials (your pair client_id / client_secret) to query a new access token. The OAuth credentials don't expire.

Authentication endpoint

POST https://api.contentsquare.com/v1/oauth/token

Parameters

These parameters have to be provided in the body of the request.

client_id

Required. The OAuth client_id generated from the Contentsquare console

client_secret

Required. The OAuth client_secret generated from the Contentsquare console

grant_type

Required. Always set it to "client_credentials", as required by the OAuth 2.0 standard

scope

Required. You should use "metrics".
If needed, you can specify a list of several scopes to get a token that can query several APIs (e.g. "data-export metrics" if you want your token to cover both the Data Export API and Metrics API scopes)

project_id

Optional. Only required if you use account-level OAuth credentials, to specify which project of the account you want to target

Request example

curl --location 'https://api.contentsquare.com/v1/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "c3133d76-a768-4f5a-XXX",
    "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX",
    "grant_type": "client_credentials",
    "scope": "metrics",
    "project_id": 42
}'

Response example

{
  "access_token": "eyJhbGciOiJSIsImtpY5MTXXX.CNTcKWAUb2mTp2cZyiDRYYOtGCKXXX", // to be used as bearer token to query the APIs
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "metrics",
  "project_id": 42,
  "endpoint": "https://api.eu-west-1.production.contentsquare.com" // this is the base URL you should use to query the Metrics API endpoints - the providded URL depends on the cloud the project is installed on
}

Example of authentication flow

Below is a sample of Javascript code to show a complete API call flow that first retrieves an access token and then use it to retrieve the list of segments on a project:

const clientId = "<your_client_id>";
const clientSecret = "<your_client_secret>";
const authEndpoint = "https://api.contentsquare.com/v1/oauth/token";
const authRequestOptions = {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: clientId,
    client_secret: clientSecret,
    grant_type: "client_credentials",
    project_id: 42,
    scope: "metrics",
  }),
};
const authResponse = await fetch(authEndpoint, authRequestOptions);
const authJsonData = await authResponse.json();
// Below are the access token and base URL that must be used to query the Metrics API endpoints
const accessToken = authJsonData.access_token;
const baseURL = authJsonData.endpoint;
// Using the access token and base URL to query the Metrics API endpoints and get the segments in this example
const metricsApiEndpointResponse = await fetch(`${baseURL}/v1/segments`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const metricsApiEndpointauthJsonData = await metricsApiEndpointResponse.json();
const segments = metricsApiEndpointauthJsonData.payload;

OAuth credentials information endpoint

POST https://api.contentsquare.com/v1/oauth/me

Parameters

None.

Request example

curl --location 'https://api.contentsquare.com/v1/oauth/me' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "c3133d76-a768-4f5a-XXX",
    "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX",
}'

Response example

{
  "scopes": "metrics data-export session-replay symbolicator",
  "permissions": {
    "projects": [
      {
        "id": 42,
        "name": "UX ANALYTICS"
      }
    ]
  }
}

Limits

  • 10 concurrent requests maximum per project
  • 10 OAuth credentials (client_id/client_secret) per project and per account maximum
  • The data available for query is limited to the project contractual data retention period

Date ranges

For metrics endpoints, you need to specify the date range you want to query. As in our CS Digital platform, you cannot query more than 92 days of data for at once (this is to guarantee reliability and performance). If a date range exceeds 92 days or is out of the project data retention period, the API will return an error message indicating that the range is out of bonds.

In terms of format, dates must respect one of the following ISO formats:

  • 2021-08-13T12:32:40.000Z (YYYY-MM-DDThh:mm:ss.sssZ) for a date in UTC.
  • 2021-08-13T12:32:40 (YYYY-MM-DDThh:mm:ss), equivalent to 2021-08-13T12:32:40.000Z.
  • 2021-08-13T12:32 (YYYY-MM-DDThh:mm), equivalent to 2021-08-13T12:32:00.000Z.
  • 2021-08-13 (YYYY-MM-DD), equivalent to 2021-08-13T00:00:00.000Z.
  • 2021-08 (YYYY-MM), equivalent to 2021-08-01T00:00:00.000Z.
  • 2021-08-13T12:32:40+02:00 (YYYY-MM-DDThh:mm:ss+hh:mm) where the part after the + (it can also be -) represents the time zone UTC offset. Keep in mind that when specifying dates in URL parameters, the + character must be encoded into %2B (e.g. 2021-08-13T12:32:40%2B02:00).
  • 2021-08-13T12:32+02:00 (YYYY-MM-DDThh:mm+hh:mm), equivalent to 2021-08-13T12:32:00+02:00.

Objects Endpoints

The metrics API replicates the behavior of the analysis context in Contentsquare. To get a metric, you can filter by device, segment etc. Plus, for page groups and zones metrics, you will have to define for which page group or zones you want data. To help you, we provide an API that retrieves these objects: segments, page groups etc.

Segments

/v1/segments

Get the list of all segments for a project. More information regarding segments in Contentsquare

Parameters
projectId

Only required for account-level OAuth credentials. The target project.

ids

Filter the results and get a list of segments that matches the ids provided.

  • 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 OAuth credentials. The target project.

Mappings

/v1/mappings

Get the list of all mappings for a project. More information regarding mappings in Contentsquare

Parameters
projectId Only required for OAuth credentials. The target project.
ids

Filter the results and get a list of mappings that matches the ids provided.


Multiple IDs should be separated by a comma

Example of response
{
  "payload": [
    {
      "id": 101010,
      "name": "New Zoning Mapping",
      "description": "Test",
      "createdAt": "2019-11-05T09:44:51.000Z",
      "updatedAt": "2019-11-05T09:45:05.000Z"
    }
  ],
  "success": true
}

/v1/mappings/{mappingId}

Get information for a specific mapping More information regarding mappings in Contentsquare

Parameters
projectId Only required for OAuth credentials. The target project.
Example of response
{
  "payload": [
    {
      "id": 101010,
      "name": "New Zoning Mapping",
      "description": "Test",
      "createdAt": "2019-11-05T09:44:51.000Z",
      "updatedAt": "2019-11-05T09:45:05.000Z"
    }
  ],
  "success": true
}

Page groups

/v1/mappings/{mappingId}/page-groups

Get all the page groups for a specific mapping More information regarding mappings and page groups in Contentsquare

Parameters
projectId Only required for OAuth credentials. The target project.
Example of response
{
  "payload": [
    {
      "id": 1010,
      "name": "Product Pages",
      "category": "Other"
    }
  ],
  "success": true
}

/v1/page-groups/{pageGroupId}

Get information about a page and all the related mappings More information regarding page groups in Contentsquare

Parameters
projectId Only required for OAuth credentials. The target project.
Example of response
{
  "payload": {
    "id": 1010,
    "name": "Product pages",
    "category": "Other",
    "mappings": [
      {
        "id": 147,
        "name": "Ecommerce",
        "description": null,
        "createdAt": "2018-10-16T11:37:36.000Z",
        "updatedAt": "2019-08-21T07:12:18.000Z"
      },
      {
        "id": 148,
        "name": "All pages",
        "description": null,
        "createdAt": "2018-10-16T12:49:49.000Z",
        "updatedAt": "2019-08-21T07:12:23.000Z"
      }
    ]
  },
  "success": true
}

Zonings

/v1/page-groups/{pageGroupId}/zonings

Get all the zonings for a page group More information regarding zonings in Contentsquare

Parameters
projectId Only required for OAuth credentials. The target project.
Example of response
{
  "payload": [
    {
      "id": 100,
      "name": "Revamp product page",
      "createdAt": "2019-10-25T13:12:45.000Z",
      "lastUpdatedAt": "2019-10-29T11:11:22.000Z"
    }
  ],
  "success": true
}

Zones

/v1/zonings/{zoningId}/zones

Get all the zones for a zoning More information regarding zonings in Contentsquare

Parameters
projectId Only required for OAuth credentials. The target project.
Example of response
{
  "payload": [
    {
      "id": 100,
      "name": "Add to cart button"
    }
  ],
  "success": true
}

Site Metrics Endpoints

All site metrics

/v1/metrics/site

Returns all site metrics between two dates.

Parameters
projectId Only required for OAuth credentials. The target project.
startDate

Required. Beginning of date range for analysis.

  • 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 Group Metrics Endpoints

All page groups metrics

/v1/metrics/page-group/{pageGroupId}

Returns all page group metrics between two dates.

Parameters
projectId Only required for OAuth credentials. The target project.
startDate

Required. Beginning of date range for analysis.

  • 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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 OAuth credentials. 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
}