feat: flatten REST endpoint response with named fields

Improved REST API response format from positional arrays to self-documenting
named objects for better developer experience.

**Before:**
```json
{
  "rows": [
    {
      "dimensions": ["2026-02-09", "/products"],
      "metrics": ["150", "120"]
    }
  ]
}
```

**After:**
```json
{
  "dimensions": ["date", "pagePath"],
  "metrics": ["sessions", "activeUsers"],
  "rows": [
    {
      "date": "2026-02-09",
      "pagePath": "/products",
      "sessions": "150",
      "activeUsers": "120"
    }
  ]
}
```

**Changes:**
- Added dimension/metric name arrays to response metadata
- Flattened row structure with named fields instead of positional arrays
- Updated README with REST API usage examples
- Added dimensions & metrics explainer section

**Breaking change:** Response format changed, but acceptable since endpoint
not yet released.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: fmontes

README.md

@@ -72,6 +72,58 @@ $gaRequest.setDimensions("date")
 </table>
 ```
 
+### REST API Usage
+
+Query Google Analytics data via REST endpoint:
+
+```bash
+curl -X POST http://localhost:8080/api/v1/googleanalytics/query \
+  -H "Content-Type: application/json" \
+  -u admin@dotcms.com:admin \
+  -d '{
+    "propertyId": "123456789",
+    "startDate": "2026-02-09",
+    "endDate": "2026-02-16",
+    "metrics": ["sessions", "activeUsers"],
+    "dimensions": ["date", "pagePath"],
+    "filters": {
+      "dimension": [
+        {"field": "pagePath", "value": "/products", "operator": "CONTAINS"}
+      ]
+    },
+    "sort": "sessions",
+    "maxResults": 100
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "rowCount": 7,
+  "dimensions": ["date", "pagePath"],
+  "metrics": ["sessions", "activeUsers"],
+  "rows": [
+    {
+      "date": "20260209",
+      "pagePath": "/products",
+      "sessions": "150",
+      "activeUsers": "120"
+    },
+    {
+      "date": "20260210",
+      "pagePath": "/home",
+      "sessions": "200",
+      "activeUsers": "180"
+    }
+  ],
+  "metadata": {
+    "currencyCode": "USD",
+    "timeZone": "America/New_York"
+  }
+}
+```
+
 ## Documentation
 
 For complete setup instructions including Google Cloud configuration, Google Analytics permissions, advanced usage, and troubleshooting:
@@ -86,16 +138,46 @@ For complete setup instructions including Google Cloud configuration, Google Ana
 - **Troubleshooting** - OSGi issues, metric errors, variable name conflicts
 - **Available Metrics & Dimensions** - GA4 API schema reference
 
-## Available Metrics
+## Understanding Dimensions and Metrics
+
+When querying Google Analytics, you combine **dimensions** and **metrics** to get the data you need:
+
+### Dimensions (What to group by)
 
-Common GA4 metrics you can query:
-- `sessions` - Number of sessions
+Dimensions are categorical attributes that describe your data—they answer "what are we breaking this down by?"
+
+Common dimensions:
+- `date` - When the activity happened (e.g., "20260209")
+- `pagePath` - Which page was viewed (e.g., "/products")
+- `country` - Where users are located (e.g., "United States")
+- `deviceCategory` - Device type (e.g., "desktop", "mobile", "tablet")
+- `browser` - Browser used (e.g., "Chrome", "Safari")
+- `city` - User's city (e.g., "New York")
+- `source` - Traffic source (e.g., "google", "facebook", "direct")
+
+### Metrics (What to measure)
+
+Metrics are the numerical measurements you want to analyze:
+- `sessions` - Number of sessions (visits)
 - `activeUsers` - Number of distinct users
-- `screenPageViews` - Total page and screen views
+- `screenPageViews` - Total page views
 - `bounceRate` - Percentage of single-page sessions
 - `averageSessionDuration` - Average session duration in seconds
 
-See the [GA4 API Schema](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema) for the full list.
+### Example Query
+
+"Show me sessions and active users, broken down by date and page path"
+
+```json
+{
+  "dimensions": ["date", "pagePath"],
+  "metrics": ["sessions", "activeUsers"]
+}
+```
+
+Each row in the response represents one unique combination of dimension values with its associated metrics.
+
+See the [GA4 API Schema](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema) for the complete list of available dimensions and metrics.
 
 ## Version History
 

src/main/java/com/dotcms/google/analytics/rest/GoogleAnalyticsResource.java

@@ -7,6 +7,8 @@
 import com.dotcms.google.analytics.service.GoogleAnalyticsService;
 import com.dotcms.rest.WebResource;
 import com.dotmarketing.util.Logger;
+import com.google.analytics.data.v1beta.DimensionValue;
+import com.google.analytics.data.v1beta.MetricValue;
 import com.google.analytics.data.v1beta.RunReportResponse;
 import com.liferay.portal.model.User;
 
@@ -149,26 +151,38 @@ public Response query(
             // Execute query
             final RunReportResponse gaResponse = analyticsService.query(analyticsRequest);
 
+            // Capture field names for flattened response
+            final List<String> dimensionNames = queryRequest.getDimensions();
+            final List<String> metricNames = queryRequest.getMetrics();
+
             // Convert to JSON-friendly format
             final Map<String, Object> responseData = new HashMap<>();
             responseData.put("rowCount", gaResponse.getRowCount());
 
-            // Convert rows to simple structure
-            final List<Map<String, Object>> rows = gaResponse.getRowsList().stream()
+            // Add metadata with dimension and metric names
+            responseData.put("dimensions", dimensionNames != null ? dimensionNames : new ArrayList<>());
+            responseData.put("metrics", metricNames != null ? metricNames : new ArrayList<>());
+
+            // Convert rows to flattened structure with named fields
+            final List<Map<String, String>> rows = gaResponse.getRowsList().stream()
                     .map(row -> {
-                        final Map<String, Object> rowData = new HashMap<>();
-
-                        // Extract dimensions
-                        final List<String> dimensions = row.getDimensionValuesList().stream()
-                                .map(dv -> dv.getValue())
-                                .collect(Collectors.toList());
-                        rowData.put("dimensions", dimensions);
-
-                        // Extract metrics
-                        final List<String> metrics = row.getMetricValuesList().stream()
-                                .map(mv -> mv.getValue())
-                                .collect(Collectors.toList());
-                        rowData.put("metrics", metrics);
+                        final Map<String, String> rowData = new HashMap<>();
+
+                        // Map dimension values to names
+                        final List<DimensionValue> dimensionValues = row.getDimensionValuesList();
+                        if (dimensionNames != null) {
+                            for (int i = 0; i < dimensionNames.size() && i < dimensionValues.size(); i++) {
+                                rowData.put(dimensionNames.get(i), dimensionValues.get(i).getValue());
+                            }
+                        }
+
+                        // Map metric values to names
+                        final List<MetricValue> metricValues = row.getMetricValuesList();
+                        if (metricNames != null) {
+                            for (int i = 0; i < metricNames.size() && i < metricValues.size(); i++) {
+                                rowData.put(metricNames.get(i), metricValues.get(i).getValue());
+                            }
+                        }
 
                         return rowData;
                     })