How to use api_request as a metric instead or a dimension?

Question

I'm trying to measure the API calls made via my server and instead of storing the API usage in my server I'm pushing it to GA4 using Measurement Protocol. I've successfully implemented it and am pushing events successfully using this code:

$eventData = [
    'appInstanceId' => $appInstanceId,
    'userId'        => $userId,
    'events'        => [
        'name'   => 'api_request',
        'params' => []
    ]
];

$firebaseAppId = Settings::get('firebase_app_id');
$appSecret = Settings::get('firebase_api_secret');
$out = Http::get(sprintf('https://www.google-analytics.com/mp/collect?firebase_app_id=%s&api_secret=%s', $firebaseAppId, $appSecret), function ($http) use ($eventData) {
    $http->setOption(CURLOPT_POSTFIELDS, json_encode($eventData));
});

Which is basically a PHP adaptation of this code.

And it successfully pushes the event to firebase and I can even view it on the firebase analytics console. However, when I try to fetch the same using the GA4 data API, it fails. I tried to manually create the metric from the Google Analytics dashboard "Custom Definitions" tab's and it appeared in the meta API and it showed under the metrics array. However, when I fetch the data it fails.

I was experimenting a bit and tried renaming the field to api_request_2 and used the same code. This time when I went to the custom definitions section, it auto-created the field except as a "dimension". I was confused and so I tried doing a fetch of the same using runReport API, except this time using it as a dimension, and the metric as eventCount. That actually worked and returned a result. But this isn't useful for me because I need it as a metric so I can put it on a graph against it's dimension (Date) so I have a count of the APIs requests on a per-day basis. How do I go about making this work?

Answer 1

If you're trying to get a count of "API requests" events on a per-day basis, you don't need to use Custom Definitions. The Measurement Protocol code that you shared will send events with an eventName of api_request. You can create a per-day report through the GA4 Data API through the following request:

POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
  "entity": { "propertyId": "YOUR_GA4_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "2021-03-01", "endDate": "2021-03-20" }],
  "dimensions": [{ "name": "date" }],
  "metrics": [{ "name": "eventCount" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "eventName",
      "stringFilter": {
        "value": "api_request"
      }
    }
  },
}

There are examples of using dimension filters in the Data API here.

What could you use custom definitions for?

If you want to log additional information about the request, you could add an event parameter, register a custom definition, and use the custom definition in a Data API request. For example, let's say you're making API requests to multiple APIs (the Drive API and the Youtube API for example). You could add a api_method parameter to the event like this:

$eventData = [
    'appInstanceId' => $appInstanceId,
    'userId'        => $userId,
    'events'        => [
        'name'   => 'api_request',
        'params' => [
            'api_method': 'drive-api'
        ]
    ]
];

After registering a Custom Definition for the parameter api_method, you can use the parameter in Reports (Guide). This request creates a per-day report through the GA4 Data API that is additionally broken down by api_method:

POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
  "entity": { "propertyId": "YOUR_GA4_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "2021-03-01", "endDate": "2021-03-20" }],
  "dimensions": [{ "name": "date" },{ "name": "customEvent:api_method" }],
  "metrics": [{ "name": "eventCount" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "eventName",
      "stringFilter": {
        "value": "api_request"
      }
    }
  },
}

An example response row for the Report follows. This row would mean you logged 1337 request to the drive-api on March 10th.

  "rows": [
...
    {
      "dimensionValues": [
        {
          "value": "20210310"
        },
        {
          "value": "drive-api"
        }
      ],
      "metricValues": [
        {
          "value": "1337"
        }
      ]
    },
...