名称： supermetrics
描述： "Supermetrics 官方技能。从 100 多个平台（包括 Google Analytics、Meta Ads、Google Ads 和 LinkedIn）查询营销数据。需要 API 密钥。"
版本： 1.0.1
触发器：
- 营销数据
- supermetrics
- 分析
- 广告表现
- 营销活动指标
- google analytics
- meta ads
- facebook ads
- google ads
- linkedin ads
- 营销报告
作者： supermetrics
标签： [营销, 分析, supermetrics, api, 数据]
requires:
env:
- SUPERMETRICS_API_KEY

Supermetrics 营销数据

从 100 多个平台（包括 Google Analytics、Meta Ads、Google Ads 和 LinkedIn）查询营销数据。

使用方法

导入辅助模块：

from supermetrics import (
    discover_sources,
    discover_accounts,
    discover_fields,
    query_data,
    get_results,
    get_today,
    search,
    health,
)

函数说明

discover_sources()

列出所有可用的营销平台。

result = discover_sources()
for src in result['data']['sources']:
    print(f"{src['id']}: {src['name']}")

discover_accounts(ds_id)

获取指定数据源下已连接的账户。

常用数据源 ID：
| ID | 平台 |
|----|----------|
| FA | Meta Ads (Facebook) |
| AW | Google Ads |
| GAWA | Google Analytics |
| GA4 | Google Analytics 4 |
| LI | LinkedIn Ads |
| AC | Microsoft Advertising (Bing) |

result = discover_accounts("GAWA")
for acc in result['data']['accounts']:
    print(f"{acc['account_id']}: {acc['account_name']}")

discover_fields(ds_id, field_type=None)

获取可用的指标和维度。

# 获取所有字段
result = discover_fields("GAWA")

# 仅获取指标
result = discover_fields("GAWA", "metric")

# 仅获取维度
result = discover_fields("GAWA", "dimension")

query_data(...)

执行营销数据查询。返回用于异步获取结果的 schedule_id。

result = query_data(
    ds_id="GAWA",
    ds_accounts="123456789",
    fields=["date", "sessions", "pageviews", "users"],
    date_range_type="last_7_days"
)
schedule_id = result['data']['schedule_id']

参数说明：
- ds_id (必需)：数据源 ID
- ds_accounts (必需)：来自 discover_accounts() 的账户 ID（一个或多个）
- fields (必需)：来自 discover_fields() 的字段 ID（一个或多个）
- date_range_type：日期范围类型，可选 last_7_days、last_30_days、last_3_months、custom
- start_date, end_date：自定义日期范围时使用 (格式：YYYY-MM-DD)
- filters：过滤表达式 (例如："country == United States")
- timezone：IANA 时区 (例如："America/New_York")

过滤运算符：
- ==, != - 等于，不等于
- >, >=, <, <= - 比较
- =@, !@ - 包含，不包含
- =~, !~ - 正则表达式匹配

get_results(schedule_id)

检索查询结果。

result = get_results(schedule_id)
for row in result['data']['data']:
    print(row)

get_today()

获取当前 UTC 日期，用于日期计算。

result = get_today()
print(result['data']['date'])  # 输出示例："2026-02-03"

search(query)

在 Supermetrics 资源中搜索指导和建议。

result = search("facebook ads metrics")
print(result['data'])

health()

检查 Supermetrics 服务器健康状态。

result = health()
print(result['data']['status'])  # 输出示例："healthy"

工作流示例

from supermetrics import (
    discover_accounts,
    discover_fields,
    query_data,
    get_results,
)

# 1. 查找账户
accounts = discover_accounts("GAWA")
account_id = accounts['data']['accounts'][0]['account_id']

# 2. 查看可用字段
fields = discover_fields("GAWA", "metric")
print([f['id'] for f in fields['data']['metrics'][:5]])

# 3. 查询数据
query = query_data(
    ds_id="GAWA",
    ds_accounts=account_id,
    fields=["date", "sessions", "users", "pageviews"],
    date_range_type="last_7_days"
)

# 4. 获取结果
data = get_results(query['data']['schedule_id'])
for row in data['data']['data']:
    print(row)

响应格式

所有函数均返回以下格式：

{"success": True, "data": {...}}  # 成功
{"success": False, "error": "..."}  # 错误