Date-trended advanced reports

This guide extends the features described in the Basic Date-Trended Report and introduces the following advanced features:

• Include date range comparisons in a date-trended report
• Add a segment to a date-trended report

All examples in this guide use the Adobe Analytics 2.0 Reports API. The endpoints described in this guide are routed through analytics.adobe.io. To use them, you must first create a client with access to the Adobe Developer Console. For more information, see Getting started with the Analytics API.

data-variant=info

data-slots=text

Include date range comparisons in a date-trended report

Use this endpoint to create a date-trended report that compares metric data across two date ranges. Date range comparisons allow you to evaluate performance for a current period against a previous period in a single report request. For more information on date-trended reports, see the Basic Date-Trended Report.

POST https://analytics.adobe.io/api/{GLOBAL_COMPANY_ID}/reports

data-variant=info

data-slots=text

Request and Response Examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X 'POST' \
  "https://analytics.adobe.io/api/{GLOBAL_COMPANY_ID}/reports" \
  -H "accept: application/json" \
  -H "x-api-key: {CLIENT_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "rsid": "examplersid",
    "globalFilters": [
      {
        "type": "dateRange",
        "dateRange": "YYYY-01-01T00:00:00.000/YYYY-01-31T23:59:59.999"
      },
      {
        "type": "dateRange",
        "dateRange": "YYYY-02-01T00:00:00.000/YYYY-02-28T23:59:59.999"
      }
    ],
    "dimension": "variables/daterangeday",
    "metricContainer": {
      "metrics": [
        {
          "id": "metrics/visits",
          "columnId": "visits-period1"
        },
        {
          "id": "metrics/visits",
          "columnId": "visits-period2",
          "filters": ["1"]
        }
      ],
      "metricFilters": [
        {
          "id": "1",
          "type": "dateRange",
          "dateRange": "YYYY-02-01T00:00:00.000/YYYY-02-28T23:59:59.999"
        }
      ]
    }
  }'

{
  "totalPages": 1,
  "numberOfElements": 2,
  "rows": [
    {
      "itemId": "YYYY0101",
      "value": "Jan 1, YYYY",
      "data": [842, 731]
    },
    {
      "itemId": "YYYY0102",
      "value": "Jan 2, YYYY",
      "data": [915, 803]
    }
  ],
  "columns": {
    "dimension": {
      "id": "variables/daterangeday",
      "type": "time"
    },
    "columnIds": ["visits-period1", "visits-period2"]
  },
  "summaryData": {
    "totals": [1757, 1534]
  }
}

Request example details

The example above creates a date-trended report comparing visits across two monthly periods:

• The report runs against the examplersid report suite.
• Two dateRange filters are included in globalFilters. The first defines the primary reporting period. The second defines the comparison period.
• The dimension is set to variables/daterangeday to trend the data by day.
• The metricContainer includes the metrics/visits metric twice — once for each period — each assigned a unique columnId (visits-period1 and visits-period2) to distinguish the columns in the response.
• A metricFilters entry scopes the second metric column to the comparison date range using a filter id of "1", which is referenced in the filters array of the second metric object.

Response example details

The example response above returns the following:

• Each row in rows represents one day, identified by an itemId and a human-readable value.
• The data array for each row contains two values: the first corresponds to visits-period1 and the second to visits-period2.
• The columns object identifies the dimension and the two column IDs returned.
• The summaryData.totals array contains the aggregated totals for each column across all rows in the response.

Request Parameters

The following table describes the date range comparison request parameters:

Response Parameters

The following table describes the date range comparison response parameters:

How the itemId encodes the date

For time dimensions such as variables/daterangeday, the itemId is not an arbitrary key. It deterministically encodes the underlying Gregorian date, regardless of whether the report suite includes a standard or a custom (fiscal) calendar. Because of this, itemId is the reliable field to read when you need the actual date: the value field is a display label whose format changes with the report suite calendar, while the itemId for a given date does not.

The itemId is built by concatenating the following segments, left to right:

The hour segment is appended for daterangehour and daterangeminute; the minute segment is appended only for daterangeminute. Date-only dimensions such as daterangeday end after the day segment.

Examples

To decode an itemId back to a date, read the segments from the right: the last two digits are the day and the two before that are the zero-indexed month; the remaining leading digits are the year offset, so add 1900. For time dimensions, the rightmost four digits are the hour and minute, with the day and month shifted left accordingly.

Add a segment to a date-trended report

Use this endpoint to apply a segment to a date-trended report. Segments filter data before metric aggregation occurs, limiting the report to the subset of data that matches the segment definition. For more information on segments, see the Segments API.

POST https://analytics.adobe.io/api/{GLOBAL_COMPANY_ID}/reports

Request and Response Examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X 'POST' \
  "https://analytics.adobe.io/api/{GLOBAL_COMPANY_ID}/reports" \
  -H "accept: application/json" \
  -H "x-api-key: {CLIENT_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "rsid": "examplersid",
    "globalFilters": [
      {
        "type": "dateRange",
        "dateRange": "YYYY-01-01T00:00:00.000/YYYY-01-31T23:59:59.999"
      },
      {
        "type": "segment",
        "segmentId": "s1234567890_example"
      }
    ],
    "dimension": "variables/daterangeday",
    "metricContainer": {
      "metrics": [
        {
          "id": "metrics/visits"
        }
      ]
    }
  }'

{
  "totalPages": 1,
  "numberOfElements": 2,
  "rows": [
    {
      "itemId": "YYYY0101",
      "value": "Jan 1, YYYY",
      "data": [284]
    },
    {
      "itemId": "YYYY0102",
      "value": "Jan 2, YYYY",
      "data": [317]
    }
  ],
  "columns": {
    "dimension": {
      "id": "variables/daterangeday",
      "type": "time"
    },
    "columnIds": ["0"]
  },
  "summaryData": {
    "totals": [601]
  }
}

Request example details

The example above creates a date-trended report for visits filtered to a specific segment:

• The report runs against the examplersid report suite.
• The globalFilters array includes two filters: a dateRange filter that scopes the report to January, and a segment filter that applies the segment s1234567890_example as a pre-aggregation filter.
• The segment filters data before the metrics/visits metric is aggregated, so the report reflects only visits that match the segment definition.
• The dimension is set to variables/daterangeday to trend results by day.

Response example details

The example response above returns the following:

• Each row in rows represents one day, with data containing the visit count for users matching the segment.
• The lower data values compared to an unsegmented report reflect the pre-aggregation filtering applied by the segment.
• The summaryData.totals array contains the total visits for the segment across the full date range.

Request Parameters

The following table describes the segmented date-trended report request parameters not previously described above:

Response Parameters

The response parameters are the same as those described above in the date range comparisons response parameters table.

Status codes

Each API request returns an HTTP status code that reflects the result, as follows:

For more information, or for trouble-shooting help, see the following:

• Reports API overview
• API Status Codes
• API request error headers