This is an overview of the capabilities Realtime Reporting API Method of the Google Analytics Data API v1. For a detailed reference of the API, see the API Reference.
Events appear in realtime reports seconds after they have been sent to the Google Analytics. Realtime reports show events and usage data for the periods of time ranging from the present moment to 30 minutes ago (up to 60 minutes for Google Analytics 360 properties) and can be used for applications such as live counters of visitors on your website.
Realtime reports support a limited subset of dimensions and metrics compared to the Core Reporting functionality of the Data API v1.
Shared Features with Core Reports
Realtime report requests have the same semantics with Core report requests for many shared features. For example pagination, Dimension Filters and User Properties, behave the same in Realtime Reports as Core Reports. Please familiarize yourself with the overview of the Core Reporting functionality of the Data API v1, as the remainder of this document will focus on the features specific to the Realtime report requests.
Report Request
To request realtime reports, you can construct a RunRealtimeReportRequest object. We recommend starting with these request parameters:
- At least one valid entry in the dimensions field.
- At least one valid entry in the metrics field.
Here is a sample request with the recommended fields.
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_realtime_report(property_id)
def run_realtime_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="country")],
metrics=[Metric(name="activeUsers")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
Report Response
The Realtime Report Response of the API request is primarily a header and rows. The header consists of DimensionHeaders and MetricHeaders which list the columns in the Report. Each row consists of DimensionValues and MetricValues for the columns in the report. The ordering of columns is consistent in the request, the header, and every row.
Here is a sample response for the sample request above:
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "2541"
}
]
},
{
"dimensionValues": [
{
"value": "France"
}
],
"metricValues": [
{
"value": "12"
}
]
}
],
"rowCount": 2
}
Dimensions
Dimensions describe and group event data for your
website or app. The city dimension, for example, indicates the city ("Paris"
or "New York") from which each event originated. In a report request, you can
specify zero or more dimensions. See the Realtime Dimensions
for a full list of API Dimension names available in realtime requests.
For example, this request groups Active Users in two dimension columns:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [
{
"name": "country"
},
{
"name": "city"
}
],
"metrics": [{ "name": "activeUsers" }]
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_realtime_report_with_multiple_dimensions(property_id)
def run_realtime_report_with_multiple_dimensions(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="country"), Dimension(name="city")],
metrics=[Metric(name="activeUsers")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
As a sample, a row in the report response could contain the following. This row means there are 47 Active Users for your website or app with events from Cape Town, South Africa in the last 30 minutes.
"rows": [
...
{
"dimensionValues": [
{
"value": "South Africa"
},
{
"value": "Cape Town"
}
],
"metricValues": [
{
"value": "47"
}
]
},
...
],
Metrics
Metrics are quantitative measurements of event data for your website or app. In a report request, you can specify one or more metrics. See the Realtime Metrics for a full list of API Metric names available in requests.
For example, this request will show the two metrics grouped by the dimension
unifiedScreenName:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "unifiedScreenName" }],
"metrics": [
{
"name": "screenPageViews"
},
{
"name": "conversions"
}
],
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_realtime_report_with_multiple_metrics(property_id)
def run_realtime_report_with_multiple_metrics(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="unifiedScreenName")],
metrics=[Metric(name="screenPageViews"), Metric(name="conversions")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
As a sample, a row in report response could contain the following. This row
means that for the page title (web) or screen name (app) of main_menu, there
were 257 views and 72 conversion events in last 30 minutes.
"rows": [
...
{
"dimensionValues": [
{
"value": "main_menu"
}
],
"metricValues": [
{
"value": "257"
},
{
"value": "72"
}
]
},
...
],
Minute Ranges
In a realtime report request, you can use the minuteRanges field to specify Minute Ranges of event data to read. Up to two separate minute ranges can be used in a query. If a minute range specification is not present in a query, a single minute range for the last 30 minutes will be used.
For example, the request below will show the Active Users count for two separate minute ranges:
- Range #1: starting 4 minutes ago until the present moment.
Range #2: starting 29 minutes ago until 25 minutes ago (inclusively).
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"metrics": [
{
"name": "activeUsers"
}
],
"minuteRanges": [
{
"name": "0-4 minutes ago",
"startMinutesAgo": 4,
},
{
"name": "25-29 minutes ago",
"startMinutesAgo": 29,
"endMinutesAgo": 25,
}
],
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Metric,
MinuteRange,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_realtime_report_with_minute_ranges(property_id)
def run_realtime_report_with_minute_ranges(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property. Dimensions
field is omitted in the query, which results in total values of active users
returned for each minute range in the report.
Note the `dateRange` dimension added to the report response automatically
as a result of querying multiple minute ranges.
"""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
metrics=[Metric(name="activeUsers")],
minute_ranges=[
MinuteRange(name="0-4 minutes ago", start_minutes_ago=4),
MinuteRange(
name="25-29 minutes ago", start_minutes_ago=29, end_minutes_ago=25
),
],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
Below is the complete sample response for the query below. Note the
dateRange dimension added to the report response automatically
as a result of querying multiple minute ranges.
{
"dimensionHeaders": [
{
"name": "dateRange"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "0-4 minutes ago"
}
],
"metricValues": [
{
"value": "16"
}
]
},
{
"dimensionValues": [
{
"value": "25-29 minutes ago"
}
],
"metricValues": [
{
"value": "14"
}
]
}
],
"rowCount": 2,
"kind": "analyticsData#runRealtimeReport"
}