A Req plugin for interacting with Google Analytics 4 APIs.

Currently implemented methods

Example usage

# Authenticate with Google Cloud using Goth with the desired API scopes

iex> credentials = "credentials.json" |> File.read!() |> Jason.decode!()

iex> scopes = [
  "https://www.googleapis.com/auth/analytics",
  "https://www.googleapis.com/auth/analytics.edit",
  "https://www.googleapis.com/auth/analytics.readonly",
  "https://www.googleapis.com/auth/analytics.manage.users",
  "https://www.googleapis.com/auth/analytics.manage.users.readonly"
]

iex> source = {:service_account, credentials, [scopes: scopes]}
iex> {:ok, _} = Goth.start_link(name: GA, source: source, http_client: &Req.request/1)

# Attach ReqGA to Req's request and response steps
iex> req = Req.new() |> ReqGA.attach(goth: GA)

# Query away!

# ID of property to query. In the format "properties/<id number>", e.g.:
iex> property_id = "properties/264264328"

# Define a report to be posted
iex> report = %{
    "dateRanges" => [%{ "startDate" => "2023-09-01", "endDate" => "2023-09-15" }],
    "dimensions" =>[%{ "name" => "country" }],
    "metrics" => [
      %{"name" => "activeUsers"},
      %{"name" => "userEngagementDuration"},
      %{"name" => "engagementRate"},
      %{"name" => "organicGoogleSearchClickThroughRate"},
    ]
  }

# Run the report with the :run_report method
iex> res = Req.post!(req, ga: :run_report, property_id: property_id, json: report)

# The response body will hold the decoded data
iex> res.body
%ReqGA.ReportResponse{
  dimensions: ["country"],
  metrics: [
    {"activeUsers", "TYPE_INTEGER"},
    {"userEngagementDuration", "TYPE_SECONDS"},
    {"engagementRate", "TYPE_FLOAT"},
    {"organicGoogleSearchClickThroughRate", "TYPE_FLOAT"}
  ],
  columns: ["country", "activeUsers", "userEngagementDuration", "engagementRate",
  "organicGoogleSearchClickThroughRate"],
  rows: [
    ["Australia", 10089, 568807, 0.6080890737138641, 0.06607765656247402],
    ["India", 46, 1022, 0.6730769230769231, 0.006472491909385114]
  ],
  totals: nil,
  maximums: nil,
  minimums: nil,
  count: 2,
  property_quota: nil,
  metadata: %{
    "currencyCode" => "AUD",
    "subjectToThresholding" => true,
    "timeZone" => "Australia/Melbourne"
  }
}

Use with Table

Some of the Structs implement the Table.Reader protocol (https://hex.pm/packages/table) and can be traversed by rows or columns.

• ReqGA.ReportResponse
• ReqGA.PivotReportResponse
• ReqGA.AccountList
• ReqGA.Account

This makes it easier to view in LiveBook as a table by piping it to Kino.DataTable.new or for creating a DataFrame with Explorer.DataFrame.new.

API methods

Below are the API methods from the Google Analytics Data API which have been implemented in this library.

The method is passed to Req using the :ga parameter. For example, the :run_report API method would be called as follows:

res = Req.post!(req, ga: :run_report, property_id: "properties/264264328", json: report)

:run_report

Returns a customized report of your Google Analytics data.

This is equivalent of the Google Analytics Data API endpoint: POST /v1beta/{property=properties/*}:runReport

Use Req.post or Req.post! with the following parameters:

• property_id: an ID of the GA4 property in the format "properties/264264328"
• json: report where report is a map representing a JSON report

Example

report = %{
      "dateRanges" => [%{ "startDate" => "2023-09-01", "endDate" => "2023-09-15" }],
      "dimensions" =>[%{ "name" => "country" }],
      "metrics" => [
        %{"name" => "activeUsers"},
        %{"name" => "userEngagementDuration"},
        %{"name" => "engagementRate"},
        %{"name" => "organicGoogleSearchClickThroughRate"},
      ]
    }

res = Req.post!(req, ga: :run_report, property_id: "properties/264264328", json: report)

More information:

• https://developers.google.com/analytics/devguides/reporting/data/v1/basics
• https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport

:batch_run_reports

Returns multiple reports in a batch.

This is equivalent of the Google Analytics Data API endpoint: POST /v1beta/{property=properties/*}:batchRunReports

Use Req.post or Req.post! with the following parameters:

• property_id: an ID of the GA4 property in the format "properties/264264328"
• json: batch_report where batch_report is a map representing a JSON batch report request

:run_pivot_report

Returns a customized pivot report of your Google Analytics event data.

This is equivalent of the Google Analytics Data API endpoint: POST /v1beta/{property=properties/*}:runPivotReport

Use Req.post or Req.post! with the following parameters:

• property_id: an ID of the GA4 property in the format "properties/264264328"
• json: pivot_report_request where pivot_report_request is a map representing a JSON pivot report request

batch_run_pivot_reports

Returns multiple pivot reports in a batch. All reports must be for the same GA4 Property.

This is equivalent of the Google Analytics Data API endpoint: POST https://analyticsdata.googleapis.com/v1beta/{property=properties/*}:batchRunPivotReports

Use Req.post or Req.post! with the following parameters:

• property_id: an ID of the GA4 property in the format "properties/264264328"
• json: batch_pivot_report_request where batch_pivot_report_request is a map representing a JSON batch pivot report request

:run_realtime_report

Returns a customized report of realtime event data for your property.

This is equivalent of the Google Analytics Data API endpoint: POST /v1beta/{property=properties/*}:runRealtimeReport

Use Req.post or Req.post! with the following parameters:

• property_id: an ID of the GA4 property in the format "properties/264264328"
• json: realtime_report_request where realtime_report_request is a map representing a JSON realtime report request

:check_compatibility

This compatibility method lists dimensions and metrics that can be added to a report request and maintain compatibility.

This is equivalent of the Google Analytics Data API endpoint: POST /v1beta/{property=properties/*}:checkCompatibility

Use Req.post or Req.post! with the following parameters:

• property_id: an ID of the GA4 property in the format "properties/264264328"
• json: compatibility_request where compatibility_request is a map representing a JSON compatibility request

:metadata

Returns metadata for dimensions and metrics available in reporting methods.

This is equivalent of the Google Analytics Data API endpoint: GET /v1beta/{name=properties/*/metadata}

Use Req.get or Req.get! with the following parameters:

• property_id: an ID of the GA4 property in the format "properties/264264328"