View Source README

ReqGA

Documentation Package

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 methodAPIEndpointReq HTTP method supported
:run_reportData API":runReport"post
:batch_run_reportsData API":batchRunReports"post
:run_pivot_reportData API":runPivotReport"post
:batch_run_pivot_reportsData API":batchRunPivotReports"post
:run_realtime_reportData API":runRealtimeReport"post
:check_compatibilityData API":checkCompatibility"post
:metadataData API"/metadata"get
:audience_listsData API"/audienceLists"get
:audience_exportsData API"/audienceExports"get
:account_summariesAdmin API"/accountSummaries"get
:custom_dimensionsAdmin API"/customDimensions"get, post
:custom_metricsAdmin API"/customMetrics"get, post
:accountsAdmin API"/accounts"get, delete, post
:propertiesAdmin API"/accounts"get, delete, post
:key_eventsAdmin API"/keyEvents"get

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:

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:

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.

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.