ReqGA

About

ReqGA is a minimal Req plugin for Google Google Analytics 4 (GA4).

Status

This is an early draft and currently under development.

It current supports the following GA4 API endpoints:

:ga API method	API	Endpoint	Req HTTP method supported
:run_report	Data API	":runReport"	post
:batch_run_reports	Data API	":batchRunReports"	post
:run_pivot_report	Data API	":runPivotReport"	post
:batch_run_pivot_reports	Data API	":batchRunPivotReports"	post
:run_realtime_report	Data API	":runRealtimeReport"	post
:check_compatibility	Data API	":checkCompatibility"	post
:metadata	Data API	"/metadata"	get
:audience_list	Data API	"/audienceList"	get
:account_summaries	Admin API	"/accountSummaries"	get
:custom_dimensions	Admin API	"/customDimensions"	get, post
:custom_metrics	Admin API	"/customMetrics"	get, post
:accounts	Admin API	"/accounts"	get, delete, post
:properties	Admin API	"/accounts"	get, delete, post

What is Req?

Req is an excellent, ergonomic and extensibile HTTP client for Elixir. It allows custom request and response steps, which ReqGA uses to interact with Google Analytics API endpoints.

You can learn more about Req by visiting:

• https://hexdocs.pm/req/readme.html
• https://github.com/wojtekmach/req

Google Analytics APIs

This library is for use with the newer GA4 APIs. It can be used with both the Data API and the Admin API although only some API methods have been implemented.

Authenticating to Google Cloud

Goth is used for authentication.

This requires setting up a service account in Google Cloud and and a adding it to the Google Analytics 4 properties you wish to interact with.

For more information on this, visit:

• https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart-client-libraries
• https://developers.google.com/analytics/devguides/config/admin/v1/quickstart-client-libraries
• https://cloud.google.com/iam/docs/service-account-overview

Tabular data

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

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

Related packages

You may also be interested in the ReqBigQuery which is a Req plugin for BigQuery.

Example

# 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"
  }
}

Installation

Adding it to your Elixir project

The package can be installed by adding req_ga to your list of dependencies in mix.exs:

def deps do
  [
    {:req_ga, "~> 0.1"}
  ]
end

Using within LiveBook and IEx

Mix.install([{:req_ga, "~> 0.1"}])

LiveBook demonstration

Also see the demo in LiveBook at /livebook/req_ga_demo.livemd.livemd.

Documentation

The docs can be found at https://hexdocs.pm/req_ga.