Expand my Community achievements bar.

change the structure and format of the API 2.0 responses. Improve Metric Column Naming.

Avatar

Adobe Champion

2/25/25

Description:

Enhance the Adobe Analytics API 2.0 response structure to include actual metric names as column headers or labels instead of, or in addition to, numerical indices (0, 1, 2, 3, etc.) when requesting single or multi-level breakdowns. This will improve readability, usability, and automation capabilities.

Why is this feature important to you?

  • Readability and Usability: Currently, the numerical column names make it difficult to quickly understand the data without referencing the original request or external documentation. This adds unnecessary complexity and slows down analysis.
  • Automation and Efficiency: Automating data processing and analysis is hindered by the need to map numerical indices to metric names. This requires additional logic and increases development time.
  • Debugging and Maintainability: Debugging becomes more challenging as it's not immediately clear which metric corresponds to which column index. Code relying on these numerical indices is less maintainable and prone to errors when metric selections change.
  • Data Clarity: Providing metric names directly in the response enhances data clarity and makes it easier to interpret the results.

    How would you like the feature to work?

    • Include Metric Names as Column Headers: The API response should include the actual metric names (e.g., "Visits", "Page Views", "Revenue") as column headers or labels, either directly within the data structure or in a dedicated metadata section.
    • Provide a Mapping (Optional): If maintaining numerical indices is necessary for backward compatibility, include a clear mapping between the numerical indices and the corresponding metric names within the response, possibly in a separate metadata section.
    • Consistency: Ensure consistent naming conventions for metrics across the API.


      Current Behavior:

      Request:--
      {
      "rsid": "globalprod",
      "metricContainer": {
      "metrics": [
      { "columnId": "0", "id": "metrics/pageviews" },
      { "columnId": "1", "id": "metrics/visits" },
      { "columnId": "2", "id": "metrics/visitors" },
      { "columnId": "3", "id": "cm538_5e65f9850a999d7b5aa3f26d" },
      { "columnId": "4", "id": "cm_average_time_on_site_defaultmetric" },
      { "columnId": "5", "id": "metrics/bouncerate" }
      ]
      },
      "dimension": "variables/marketingchannel"
      }
      SumitK4_0-1740509261589.png

       

      Current Response:--
      {
      "columns": {
      "columnIds": ["0", "1", "2", "3", "4", "5"]
      },
      "rows": [
      {
      "value": "Direct",
      "data": [105.0, 92.0, 53.0, 0.0, 84, 0.70]
      },
      {
      "value": "Organic Search",
      "data": [28, 21, 19, 0., 7, 0.2]
      },
      // ... other rows ...
      ],
      "summaryData": {
      "filteredTotals": [15, 13, 85, 0, 82, 0]
      }
      }

      Key Issue: Notice that the columns.columnIds array contains numerical indices ("0", "1", "2", etc.). The rows.data array uses these indices to represent the metric values. You have to manually map the numerical index back to the metric ID from your original request.


      Desired Behavior:

      The columns section should include the actual metric names, not just the numerical indices. The rows.data array should ideally use metric names as keys, or the columns section should provide a mapping.


      Option 1: Metric Names as Keys in rows.data

      {
      "columns": {
      "columnIds": ["metrics/pageviews", "metrics/visits", "metrics/visitors", "cm538_5e65f98sdfghgfdsdf", "cm_average_time_on_site_defaultmetric", "metrics/bouncerate"]
      },
      "rows": [
      {
      "value": "Direct",
      "data": {
      "metrics/pageviews": 10,
      "metrics/visits": 92,
      "metrics/visitors": 53,
      "cm538_5e65f9850a999d7b5aa3f26d": 0,
      "cm_average_time_on_site_defaultmetric": 84,
      "metrics/bouncerate": 0.7
      }
      },
      {
      "value": "Organic Search",
      "data": {
      "metrics/pageviews": 28,
      "metrics/visits": 21,
      "metrics/visitors": 19,
      "cm538_5e65f9850a999d7b5aa3f26d": 0.04,
      "cm_average_time_on_site_defaultmetric": 77,
      "metrics/bouncerate": 0.26
      }
      },
      // ... other rows ...
      ],
      "summaryData": {
      "filteredTotals": {
      "metrics/pageviews": 156,
      "metrics/visits": 130,
      "metrics/visitors": 857,
      "cm538_5e65f9850a999d7b5aa3f26d": 0.02,
      "cm_average_time_on_site_defaultmetric": 82,
      "metrics/bouncerate": 0.6
      }
      }
      }

    Option 2: Metric Names in columns with a Mapping
    {
    "columns": {
    "columnIds": ["0", "1", "2", "3", "4", "5"],
    "metricMapping": {
    "0": "metrics/pageviews",
    "1": "metrics/visits",
    "2": "metrics/visitors",
    "3": "cm538_5e65f9850a999d7b5aa3f26d",
    "4": "cm_average_time_on_site_defaultmetric",
    "5": "metrics/bouncerate"
    }
    },
    "rows": [
    {
    "value": "Direct",
    "data": [10, 92, 53, 0.0, 84, 0.7]
    },
    // ... other rows ...
    ],
    "summaryData": {
    "filteredTotals": [156, 130, 857, 0.02, 82, 0.6]
    }
    }

    Option 1 is cleaner and more direct, while Option 2 maintains backward compatibility by keeping the numerical indices but adding a mapping.

    Key Point: The essence of the request is to eliminate the need for developers to manually map numerical column indices to metric IDs, improving the API's usability.