This document provides a high level overview of the Google Analytics Core Reporting API Version 3.0. For a detailed reference of the API, see Reference Guide.
The Google Analytics Core Reporting API gives you access to most of the report data in Google Analytics. With the Core Reporting API you can:
- Build custom dashboards to display Google Analytics data.
- Save time by automating complex reporting tasks.
- Integrate your Google Analytics data with other business applications.
Choosing a Version
We recently launched a new version of the Core Reporting API.
- Building a new application? – We recommend you use the latest version 3.0.
- Using the legacy version 2.3? – Read the Migration Guide for details on how to update your app to use the new version.
Want to get started right away? Read the Hello Analytics API Tutorial.
Each application that uses the API will have to go through a couple of steps to register, authorize the user, and work with the API. This tutorial will walk you through each step and in the end, you will have a working application that you can customize.
The Core Reporting API returns report data consisting of statistics derived from the data collected by the Google Analytics tracking code. Each report is organized as dimensions and metrics. You use the Core Reporting API to query for dimensions and metrics in order to build customized reports.
There are 3 fundamental concepts underlying the Core Reporting API:
- How reports relate to users and views (profiles).
- The structure of a report and how to build queries
- Working with the API response
Reports, Users, and Views (Profiles)
To request report data for a user, your application must identify the user and specify a view (profile) for which to retrieve the data. A user is identified by obtaining authorization credentials and passing them in each API request. A view (profile) is part of the Google Analytics configuration hierarchy and identified by a view (profile) ID.
There are a couple of ways to find your view (profile) ID.
- Your application can use the Management API to traverse Management configuration hierarchy to obtain a view (profile) ID.
- In the URL of each report in Google Analytics.
- In Google Analytics under Admin > View (Profile) > View (Profile) Settings
Querying for Dimensions and Metrics
You query the API for Google Analytics report data, which consists of dimensions and metrics. Metrics are the individual measurements of user activity on your property, such as sessions and pageviews. Dimensions break down metrics across some common criteria, such as country or browser. When you build a query, you specify which dimensions and metrics you want in your report data.
Use the interactive Dimensions & Metrics Reference Guide to explore all the dimensions and metrics exposed through the API. Also read the Core Reporting API Reference Guide to learn about how to specify dimensions and metrics in an API query.
Working With Reports
The data returned form the API can be thought of as a table with a header and a list of rows. Each API response consists of a header that describes the name and data type of each column. The response also contains a list of rows, where each row is a list of cells with data in the same order as the headers. You use the information in the header to determine the type of data in each cell.
Read the Core Reporting API Reference Guide for more information about the API response.
Quota and Deprecation Policies
The Google Analytics API handles millions of operations. To protect the system from receiving more operations than it can handle, and to ensure an equitable distribution of system resources, it is necessary to employ a quota system. Read the Limits and Quotas guide for specific limits.
For details on how changes to Core Reporting API columns (i.e. dimensions and metrics) are handled, read the Data Deprecation Policy. To learn how the Metadata API can be used to check for deprecated columns, see the Metadata API Dev Guide.
Now that you understand how the API works, we have a bunch of resources to help you get started:
- Read the Developer Guide to learn how to work with the API.
- Use the interactive Query Explorer tool to visually build queries and see the response through the API.
- Read the Common Queries article which lists several of the most common queries to the Core Reporting API.
- Check the Dimensions & Metrics reference for a list of all the data available through the API.
- Check the Libraries & Samples page for a list of all the available client libraries that can be used with this API.