You can use the [Data API](https://developers.google.com/analytics/devguides/reporting/data/v1/rest) to
programmatically access Google Analytics report data.

[Learn more about Google Analytics
properties](https://support.google.com/analytics/answer/9325020).

The data returned by the API is consistent with the data shown in the Google Analytics
user interface and fully respects the
[Reporting identity settings](https://support.google.com/analytics/answer/10976610)--
such as Blended, Observed, or Device-based--that are configured for your Google Analytics
property.

> [!WARNING]
> This API provides features in Alpha and Beta channels. Alpha and Beta products may have limited support, and changes to these products may not be compatible with other Alpha and Beta versions.
>
> **Alpha**:
> Features are in an early preview stage. While we try to notify you of
> upcoming changes, expect to encounter breaking changes before the API is publicly released.
>
> **Beta**:
> No breaking changes are expected in this channel.
>
> For official Google Analytics API announcements, subscribe to the
> [Google Analytics API Notify Group](https://groups.google.com/forum/#!forum/google-analytics-api-notify).

Here are some examples you might report on using the Google Analytics Data API v1:

- How many daily active users has your Android app had in the last week.
- How many page views the top 10 pages on your site had in the last 28 days.
- How many active users per country your iOS app had in the last 30 minutes.

You can also use the Google Analytics Data API v1 to do the following:

- Build custom dashboards to display Google Analytics data.
- Automate complex reporting tasks to save time.
- Integrate your Google Analytics data with other business applications.

## Data consistency and reporting identity

The Google Analytics Data API v1 accesses the same report data as the Google Analytics
interface. The data returned by the API fully respects the
**Reporting Identity** settings configured for your Google Analytics property so
user counts, deduplication, and data modeling align with the
chosen identity space---such as Blended, Observed, or Device-based---in your
property settings.

To learn more about how different identity spaces can affect your reports, see
[Reporting identity](https://support.google.com/analytics/answer/10976610).

## Get started

To get started with a client library in Java, Python, Node.js, PHP, C#, Go, or
Ruby, see the [client library quickstart](https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart). To learn how to
construct queries, filter dimensions, and read responses, see [Create a
report](https://developers.google.com/analytics/devguides/reporting/data/v1/basics), or test queries interactively in the [Query
Explorer](https://ga-dev-tools.google/ga4/query-explorer/).

### Sample `runReport` request and response

To query event data over REST, send a `POST` request to the
[`runReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport) endpoint with a
[`RunReportRequest`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport#request-body)
JSON body specifying your `dateRanges`, `dimensions`, and `metrics`:

    POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
    {
      "dateRanges": [
        { "startDate": "7daysAgo", "endDate": "yesterday" }
      ],
      "dimensions": [
        { "name": "country" }
      ],
      "metrics": [
        { "name": "activeUsers" }
      ]
    }

Or run the equivalent `curl` command using [Application Default
Credentials](https://cloud.google.com/docs/authentication/application-default-credentials):

    curl -X POST \
      "https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport" \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "x-goog-user-project: PROJECT_ID" \
      -H "Content-Type: application/json" \
      -d '{
        "dateRanges": [
          { "startDate": "7daysAgo", "endDate": "yesterday" }
        ],
        "dimensions": [
          { "name": "country" }
        ],
        "metrics": [
          { "name": "activeUsers" }
        ]
      }'

The API returns a [`RunReportResponse`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/RunReportResponse)
containing column headers and data rows:

    {
      "dimensionHeaders": [
        { "name": "country" }
      ],
      "metricHeaders": [
        { "name": "activeUsers", "type": "TYPE_INTEGER" }
      ],
      "rows": [
        {
          "dimensionValues": [{ "value": "United States" }],
          "metricValues": [{ "value": "4820" }]
        },
        {
          "dimensionValues": [{ "value": "Japan" }],
          "metricValues": [{ "value": "2541" }]
        }
      ],
      "rowCount": 2,
      "kind": "analyticsData#runReport"
    }

## Available methods

Here's a list of the Data API methods. For more details, see the [reference
documentation](https://developers.google.com/analytics/devguides/reporting/data/v1/rest).

- [`runReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport) This method returns a customized report of your Google Analytics event data and is the preferred method for [simple report queries](https://developers.google.com/analytics/devguides/reporting/data/v1/basics).
- [`batchRunReports`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/batchRunReports) This is a batch version of the runReport method which lets you generate multiple reports using a single API call.
- [`runPivotReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runPivotReport) This method returns a customized [pivot report](https://developers.google.com/analytics/devguides/reporting/data/v1/pivots) of your Google Analytics event data. Pivot reports are more advanced and expressive formats than regular reports. Each pivot describes the visible dimension columns and rows in the report response.
- [`batchRunPivotReports`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/batchRunPivotReports) This is a batch version of the runPivotReport method which lets you generate multiple reports using a single API call.
- [`getMetadata`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/getMetadata) This method returns metadata for dimensions and metrics available in reporting methods. Used to explore the dimensions and metrics. The response of this method also includes the Custom dimensions and metrics available for the specified Google Analytics property.
- [`checkCompatibility`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/checkCompatibility) This method lists dimensions and metrics that can be added to a report request and maintain compatibility.
- [`runRealtimeReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport) This method returns a customized [report of realtime event
  data](https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-basics) for your property. Events appear in realtime reports seconds after they have been sent to 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).
- [`properties.audienceExports`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports) A group of methods that let you [generate Audience
  Exports](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-export-basics), which include a snapshot of the users in an audience.
- [`properties.recurringAudienceLists`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists) **(Early preview)** A group of methods that let you manage recurring Audience Exports. A recurring audience export produces new audience lists each day.
- [`runFunnelReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/runFunnelReport) **(Early preview)** This method returns a customized [funnel
  report](https://developers.google.com/analytics/devguides/reporting/data/v1/funnels) of your Google Analytics event data. Funnel exploration lets you visualize the steps your users take to complete a task and quickly see how well they are succeeding or failing at each step.
- [`properties.chat`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat) **(Early preview)** This method provides programmatic conversational access to [Ask Advisor in Google Analytics](https://developers.google.com/analytics/devguides/reporting/data/v1/advisor-basics). You can ask natural language questions about your event data, diagnose performance changes, and receive structured narrative and tabular insights.

## Supported dimensions and metrics

For a list of all the dimensions and metrics supported by the Data API, see the
[API schema documentation](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema).