# 广告数据报表 > 来源：https://help.gravity-engine.com/docs/server-integration/reporting/advertising-reports > 说明如何通过 Gravity Engine OpenAPI 查询广告账户、计划和素材等层级的媒体消耗与投放数据，涵盖认证、请求参数、筛选条件和返回字段。 > **广告数据报表的全新升级版——「多维报表」接口已正式上线。「广告数据报表」将于近期下线且后续不再维护，建议您切换至新接口，以获取更强大的数据分析能力。 > [>前往多维报表](/docs/server-integration/reporting/multidimensional-reports)** 此接口用于获取引力后台广告报表页数据，包括媒体消耗、产品后向回收等数据指标。 ## 数据口径 [#数据口径] 1. 曝光归因口径：将事件的时间归因到该用户有效触点广告的曝光时间上。适合场景：首日 ROI、24 小时 ROI 等 ROI 追踪。 2. 行为发生口径：事件发生的独立时间。适合场景：当日的行为发生数、上报率等。 ## 数据更新频率 [#数据更新频率] 1. 数据每 **15\~30** 分钟更新一次。 2. 一般行为发生口径的历史数据不会变化，除数据有问题需要校对时会更新历史数据。 3. 曝光归因口径的数据会随着用户行为的发生而不断变化。 ## 申请引力开发者应用 [#申请引力开发者应用] 在正式接入本接口之前，您需要在引力后台-[引力开发者](https://web.gravity-engine.com/#/manage/develop)页面申请引力开发者应用，申请之后，我们将在一个工作日内完成审核，审核通过之后，您的开发者应用才可以正常拉取数据。 创建好开发者应用之后，请复制 `app_key` 参数，并发送给研发同学以供后续接口调用使用。 ## 接口限频 [#接口限频] 默认接口限频：每 10 分钟 1 次。接口限频按开发者应用维度统计，即同一个 `app_key` 下的应用共用同一套频次限制。如果开发者绑定应用过多导致频繁触发限频，请联系引力运营评估后提升限频等级。 ## 接口信息 [#接口信息] ### 请求地址 [#请求地址] ```text https://api-insight.gravity-engine.com/openapi/api/v1/report/combo_sql/ ``` ### 请求方法 [#请求方法] POST ### Header [#header] | 字段 | 类型 | 描述 | | ------------- | ------ | ------------------------------------------------------------- | | Authorization | string | 具体如何生成，请参考 [【签名生成】](/docs/server-integration/request-signing) | ### body 请求参数 [#body-请求参数] | 字段 | 必填 | 参数类型 | 描述 | | -------------------- | -- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `date_list` | Y | string\[] | 起始日期数组，格式 YYYY-MM-DD，举例：\["2023-08-14", "2023-08-19"] | | `metrics_list` | Y | string\[] | 指定需要的指标名称，可参考应答参数返回的消耗指标字段，应答参数指标说明详见 [这个文件](https://gravity-engine-internal-resource.oss-cn-beijing.aliyuncs.com/1/excels/metric_data.json) | | `dims_list` | Y | string\[] | 分组条件，具体详见【分组规则】 | | `statistics_caliber` | Y | string | 数据口径：`user_activated_time` 为曝光归因口径，`behavior_occurred_time` 为行为发生口径 | | `decimal_point` | Y | number | 数据精度，可选值为 `2` 和 `4`，表示返回的数据小数点精度值 | | `roi_version` | N | number | ROI 精准模型，可选值为 `1` 和 `2`，传 2 表示启用 ROI 精准模型，默认为 1，传 1 表示关闭 ROI 精准模型 | | `app_id` | Y | number | 查询的应用引力 ID，可以在引力后台 [应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面获取 | | `filtering` | N | FilterObject | 具体参见 [FilterObject](#filterobject) | | `sign` | Y | string | 签名，详情请参考 [【签名生成】](/docs/server-integration/request-signing) | ### FilterObject [#filterobject] | 字段 | 必填 | 参数类型 | 描述 | | ------------------------------- | -- | --------- | ------------------------------------------------------- | | `ad_platform_list` | N | string\[] | 广告平台枚举值，具体详见 [广告平台枚举](/docs/appendix/ad-platform-enums) | | `channel_list` | N | string\[] | 渠道列表，例如 `['xiaomi', 'huawei']` | | `version_list` | N | number\[] | 版本列表，例如 `[123, 125]` | | `turbo_promoted_object_id_list` | N | string\[] | 引力推广活动 ID 列表 | | `os_platform_list` | N | string\[] | 设备类型，取值：android/ios/linux/windows/other | ### 应答参数指标说明 [#应答参数指标说明] 请参考 [这个文件](https://gravity-engine-internal-resource.oss-cn-beijing.aliyuncs.com/1/excels/metric_data.json) 中的说明。 ## 其他信息 [#其他信息] ### 分组规则 [#分组规则] 引力支持同时根据多个维度来聚合查询数据： | 字段 | 分组聚合维度 | | -------------------------- | ------ | | `date` | 日期 | | `ad_platform` | 媒体 | | `advertiser_id` | 账户 | | `gid` | 计划 | | `aid` | 广告 | | `channel` | 渠道 | | `os_platform` | 设备类型 | | `operator` | 优化师 | | `turbo_promoted_object_id` | 推广活动 | | `csite` | 版位 | | `dept` | 部门 | 但是需要遵循以下互斥规则，标 ❌ 的两个维度不可以同时查询，否则会报错或者数据不准确： | 字段 | 日期 | 媒体 | 账户 | 计划 | 广告 | 渠道 | 设备类型 | 优化师 | 推广活动 | 版位 | 部门 | | ---- | -- | -- | -- | -- | -- | -- | ---- | --- | ---- | -- | -- | | 日期 | - | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | 媒体 | ✅ | - | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | | 账户 | ✅ | ✅ | - | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | | 计划 | ✅ | ✅ | ✅ | - | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | | 广告 | ✅ | ✅ | ✅ | ✅ | - | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | | 渠道 | ✅ | ✅ | ✅ | ✅ | ✅ | - | ✅ | ❌ | ❌ | ❌ | ❌ | | 设备类型 | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | - | ✅ | ✅ | ❌ | ✅ | | 优化师 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | - | ✅ | ❌ | ✅ | | 推广活动 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | - | ❌ | ❌ | | 版位 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | - | ❌ | | 部门 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | - | ### 关联维度查询 [#关联维度查询] 在勾选特定的分组规则后，可以传入关联维度参数以获取当前分组聚合下的其他维度信息。您可以通过 `dims_metrics_list` 数组传入，具体可传入字段枚举值说明如下表： | 字段 | 字段含义 | 依赖分组 | | ------------------- | ----------- | ------------------- | | `advertiser_status` | 广告账户状态 | `advertiser_id`（账户） | | `advertiser_name` | 账户名称（广告主名称） | `advertiser_id`（账户） | | `advertiser_remark` | 账户备注 | `advertiser_id`（账户） | | `gName` | 广告计划名称 | `gid`（计划） | | `gStatus` | 广告计划状态 | `gid`（计划） | | `AidName` | 广告名称 | `aid`（广告） | | `AidStatus` | 广告状态 | `aid`（广告） | 例如，如果您在开启账户分组的情况下，传入 ``` { "dims_metrics_list": ["advertiser_status", "advertiser_name"], ... } ``` 则返回的数据会额外返回**广告账户状态**和**账户名称**两个字段值。 ### 请求示例 [#请求示例] ```bash curl 'http://localhost:8000/openapi/api/v1/report/combo_sql/' \ -H 'Content-Type: application/json' \ -H 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcHBfa2V5IjoiMWMyOGU2MDNlNzE2NGNiYWFjZWEwMGU5ODkxNTNhNGQifQ.ZaVNUeFdKUJG7cRXorxaupDDCk9XAII-aV68yCFPmtc' \ -d '{ "date_list": [ "2023-09-12", "2023-09-13" ], "metrics_list": ["AdCost", "AppActivateStandard", "AppROI"], "dims_list": ["date", "advertiser_id"], "statistics_caliber": "user_activated_time", "decimal_point": 4, "app_id": 17214059, "filtering": { "ad_platform_list": [], "channel_list": [], "version_list": [], "turbo_promoted_object_id_list": [] }, "sign": "adab8bac98c2f639a94b4b9733249513" }' ``` ### 应答示例 [#应答示例] ```json { "data": { "columns": ["AdCost", "AppActivateStandard", "AppROI"], "items": [ { "date": "2023-09-12", "AdCost": 192448.89, "AppROI": 0.14 }, { "date": "2023-09-13", "AdCost": 1000.89, "AppROI": 0.16 } ], "total": [ { "AdCost": 193448.89, "AppROI": 0.15 } ], "tips": { "平台_消耗": "总花费(无法拆分设备类型)", "标准_激活数": "引力引擎收集到的标准全量激活数", "总ROI": "(总收入-提现金额)/平台_消耗" }, "static": [ "日期", "渠道", "推广活动ID", "推广活动名称", "设备类型", "优化师", "设计师", "广告平台", "广告主ID", "广告主名称", "广告计划ID", "版位", "广告ID", "广告名称", "广告状态", "广告创意ID", "广告创意名称", "部门" ] }, "extra": { "error": "", "request_id": "cfd6772848d440828875844bfce3db80" }, "code": 0, "msg": "成功" } ```