泰途AI 泰途AISkill 市场

google-analytics

TotalClaw 作者 maton

Google Analytics API 与托管 OAuth 集成。管理帐户、属性和数据流（管理 API）。运行有关会话、用户、页面浏览量和转化的报告（数据 API）。当用户想要配置或查询 Google Analytics 时，请使用此技能。对于其他第三方应用程序，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。

安装 / 下载方式

TotalClaw CLI推荐
totalclaw install totalclaw:totalclaw~rich-song-google-analytics-api
cURL直接下载，无需登录
curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~rich-song-google-analytics-api/file -o rich-song-google-analytics-api.md
## 概述（中文）

Google Analytics API 与托管 OAuth 集成。管理帐户、属性和数据流（管理 API）。运行有关会话、用户、页面浏览量和转化的报告（数据 API）。当用户想要配置或查询 Google Analytics 时，请使用此技能。对于其他第三方应用程序，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。

## 原文

# Google Analytics

Access Google Analytics with managed OAuth authentication. This skill covers both the Admin API (manage accounts, properties, data streams) and the Data API (run reports on metrics).

## Quick Start

```bash
# List account summaries (Admin API)
curl -s -X GET "https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries" -H "Authorization: Bearer $MATON_API_KEY"

# Run a report (Data API)
curl -s -X POST "https://gateway.maton.ai/google-analytics-data/v1beta/properties/{propertyId}:runReport" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}], "dimensions": [{"name": "city"}], "metrics": [{"name": "activeUsers"}]}'
```

## Base URLs

**Admin API** (manage accounts, properties, data streams):
```
https://gateway.maton.ai/google-analytics-admin/{native-api-path}
```

**Data API** (run reports):
```
https://gateway.maton.ai/google-analytics-data/{native-api-path}
```

Replace `{native-api-path}` with the actual Google Analytics API endpoint path. The gateway proxies requests to `analyticsadmin.googleapis.com` and `analyticsdata.googleapis.com` and automatically injects your OAuth token.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Google OAuth connections at `https://ctrl.maton.ai`.

**Important:** The Admin API and Data API use separate connections:
- `google-analytics-admin` - Required for Admin API endpoints (manage accounts, properties, data streams)
- `google-analytics-data` - Required for Data API endpoints (run reports)

Create the connection(s) you need based on which API you want to use.

### List Connections

```bash
# List Admin API connections
curl -s -X GET "https://ctrl.maton.ai/connections?app=google-analytics-admin&status=ACTIVE" -H "Authorization: Bearer $MATON_API_KEY"

# List Data API connections
curl -s -X GET "https://ctrl.maton.ai/connections?app=google-analytics-data&status=ACTIVE" -H "Authorization: Bearer $MATON_API_KEY"
```

### Create Connection

```bash
# Create Admin API connection (for managing accounts, properties, data streams)
curl -s -X POST "https://ctrl.maton.ai/connections" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"app": "google-analytics-admin"}'

# Create Data API connection (for running reports)
curl -s -X POST "https://ctrl.maton.ai/connections" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"app": "google-analytics-data"}'
```

### Get Connection

```bash
curl -s -X GET "https://ctrl.maton.ai/connections/{connection_id}" -H "Authorization: Bearer $MATON_API_KEY"
```

**Response:**
```json
{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-analytics-admin",
    "metadata": {}
  }
}
```

Open the returned `url` in a browser to complete OAuth authorization.

### Delete Connection

```bash
curl -s -X DELETE "https://ctrl.maton.ai/connections/{connection_id}" -H "Authorization: Bearer $MATON_API_KEY"
```

### Specifying Connection

If you have multiple Google Analytics connections, specify which one to use with the `Maton-Connection` header:

```bash
curl -s -X GET "https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries" -H "Authorization: Bearer $MATON_API_KEY" -H "Maton-Connection: 21fd90f9-5935-43cd-b6c8-bde9d915ca80"
```

If omitted, the gateway uses the default (oldest) active connection.

## Admin API Reference

### Accounts

```bash
GET /google-analytics-admin/v1beta/accounts
GET /google-analytics-admin/v1beta/accounts/{accountId}
GET /google-analytics-admin/v1beta/accountSummaries
```

### Properties

```bash
GET /google-analytics-admin/v1beta/properties?filter=parent:accounts/{accountId}
GET /google-analytics-admin/v1beta/properties/{propertyId}
```

#### Create Property

```bash
POST /google-analytics-admin/v1beta/properties
Content-Type: application/json

{
  "parent": "accounts/{accountId}",
  "displayName": "My New Property",
  "timeZone": "America/Los_Angeles",
  "currencyCode": "USD"
}
```

### Data Streams

```bash
GET /google-analytics-admin/v1beta/properties/{propertyId}/dataStreams
```

#### Create Web Data Stream

```bash
POST /google-analytics-admin/v1beta/properties/{propertyId}/dataStreams
Content-Type: application/json

{
  "type": "WEB_DATA_STREAM",
  "displayName": "My Website",
  "webStreamData": {"defaultUri": "https://example.com"}
}
```

### Custom Dimensions

```bash
GET /google-analytics-admin/v1beta/properties/{propertyId}/customDimensions
```

#### Create Custom Dimension

```bash
POST /google-analytics-admin/v1beta/properties/{propertyId}/customDimensions
Content-Type: application/json

{
  "parameterName": "user_type",
  "displayName": "User Type",
  "scope": "USER"
}
```

### Conversion Events

```bash
GET /google-analytics-admin/v1beta/properties/{propertyId}/conversionEvents
POST /google-analytics-admin/v1beta/properties/{propertyId}/conversionEvents
```

## Data API Reference

### Run Report

```bash
POST /google-analytics-data/v1beta/properties/{propertyId}:runReport
Content-Type: application/json

{
  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "city"}],
  "metrics": [{"name": "activeUsers"}]
}
```

### Run Realtime Report

```bash
POST /google-analytics-data/v1beta/properties/{propertyId}:runRealtimeReport
Content-Type: application/json

{
  "dimensions": [{"name": "country"}],
  "metrics": [{"name": "activeUsers"}]
}
```

### Batch Run Reports

```bash
POST /google-analytics-data/v1beta/properties/{propertyId}:batchRunReports
Content-Type: application/json

{
  "requests": [
    {
      "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
      "dimensions": [{"name": "country"}],
      "metrics": [{"name": "sessions"}]
    }
  ]
}
```

### Get Metadata

```bash
GET /google-analytics-data/v1beta/properties/{propertyId}/metadata
```

## Common Report Examples

### Page Views by Page

```json
{
  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "pagePath"}],
  "metrics": [{"name": "screenPageViews"}],
  "orderBys": [{"metric": {"metricName": "screenPageViews"}, "desc": true}],
  "limit": 10
}
```

### Users by Country

```json
{
  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "country"}],
  "metrics": [{"name": "activeUsers"}, {"name": "sessions"}]
}
```

### Traffic Sources

```json
{
  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "sessionSource"}, {"name": "sessionMedium"}],
  "metrics": [{"name": "sessions"}, {"name": "conversions"}]
}
```

## Common Dimensions

- `date`, `country`, `city`, `deviceCategory`
- `pagePath`, `pageTitle`, `landingPage`
- `sessionSource`, `sessionMedium`, `sessionCampaignName`

## Common Metrics

- `activeUsers`, `newUsers`, `sessions`
- `screenPageViews`, `bounceRate`, `averageSessionDuration`
- `conversions`, `eventCount`

## Date Formats

- Relative: `today`, `yesterday`, `7daysAgo`, `30daysAgo`
- Absolute: `2026-01-01`

## Code Examples

### JavaScript

```javascript
// List account summaries (A