report/demand-comparison/ad-units

GET/report/demand-comparison/ad-units

Request

cURL

curl -X GET "https://provisioning.cloudx.io/api/v1/report/demand-comparison/ad-units?start_time=1712462400&end_time=1713067200&demand_source=<demand_source>" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"

Query parameters

Name	Type	Description
`start_time`required	`integer<int64>`	Start of the inclusive report window as a Unix timestamp in seconds. CloudX converts the timestamp to a calendar date in `timezone`. The start date must be 2020-01-01 or later. The window can span any number of completed calendar dates within available history; some dates may have no data.
`end_time`required	`integer<int64>`	End of the inclusive report window as a Unix timestamp in seconds. CloudX converts the timestamp to a calendar date in `timezone`. The end date must not precede the start date and must be complete. At and after 12:00 UTC, yesterday is complete. Before 12:00 UTC, the most recent complete date is the day before yesterday. The window can span any number of completed calendar dates within available history; some dates may have no data.
`timezone`	`string`	IANA timezone used to convert `start_time` and `end_time` to calendar dates. Defaults to UTC.
`demand_source`required	`string`	Required demand source. Provide exactly one supported value, for example `demand_source=meta`. Allowed values: digitalturbine, inmobi, liftoff, meta, moloco.
`provider_business_id`	`string`	Optional provider-business filter. Use a comma-separated list for multiple values.
`provider_property_id`	`string`	Optional provider-property filter. Use a comma-separated list for multiple values.
`cloudx_ad_unit_id`	`string`	Optional CloudX ad-unit filter. Use a comma-separated list for multiple values.
`view`	`string`	Select mapped comparison rows or partner rows that have no current CloudX mapping. Allowed values: mapped, unmapped.
`limit`	`integer<int32>`

Responses

Demand comparison ad units for the requested view.

{
  "rows": [
    {
      "cloudx_revenue": 12.34,
      "partner_revenue": 12.34,
      "revenue_delta": 12.34,
      "revenue_delta_percent": 12.34,
      "cloudx_ecpm": 12.34,
      "partner_ecpm": 12.34,
      "ecpm_delta": 12.34,
      "ecpm_delta_percent": 12.34,
      "cloudx_impressions": 12.34,
      "partner_impressions": 12.34,
      "impression_delta": 12.34,
      "impression_delta_percent": 12.34,
      "demand_source": "<string>",
      "status": "comparable",
      "provider_business_id": "<string>",
      "provider_property_id": "<string>",
      "partner_ad_unit_id": "<string>",
      "partner_ad_unit_name": "<string>",
      "provider_endpoint": "<string>",
      "demand_type": "<string>",
      "partner_ad_formats": [
        "<string>"
      ],
      "cloudx_ad_unit_ids": [
        "<string>"
      ],
      "excluded_partner_revenue": 12.34,
      "excluded_partner_impressions": 12.34
    }
  ],
  "row_count": 123,
  "limit": 123,
  "truncated": true
}

200Demand comparison ad units for the requested view.

Field	Type	Description
`rows`required	`array of object`
`row_count`required	`integer<int64>`
`limit`required	`integer<int64>`
`truncated`required	`boolean`

400Invalid request parameters.

Field	Type	Description
`error`required	`string`

401Unauthorized.

Field	Type	Description
`error`required	`string`

403Forbidden.

Field	Type	Description
`error`required	`string`

500Internal server error.

Field	Type	Description
`error`required	`string`

504The query did not finish within the request time budget. Retry, narrowing the time range or filters where the operation accepts them.

Field	Type	Description
`error`required	`string`

需求对比广告单元参考

该端点为一个需求方来源汇总完整请求日历日期窗口。它不提供 day、country、platform、mediator 或原始需求方报表行。其日期和时区规则与需求对比汇总端点相同。

demand_source 必填，且只能是 digitalturbine、inmobi、liftoff、meta 或 moloco 中的一个。provider_business_id、provider_property_id 和 cloudx_ad_unit_id 是可选逗号分隔过滤器。它们接受实时需求方或 CloudX ID，不是封闭枚举。需求方 ID 标识需求方账号或资产。CloudX ID 标识 CloudX 广告单元。

view 为 mapped 或 unmapped，默认 mapped。mapped 返回有当前 CloudX 映射的需求方广告单元聚合。unmapped 返回没有当前 CloudX 映射或归因不明确的需求方行。limit 为 1 至 1000，默认 1000。响应没有分页 cursor。truncated 为 true 时请使用过滤器。

响应包含 rows、row_count、limit 和 truncated。row_count 是返回行数，不是可用总数。limit 是实际最大值。存在更多匹配行时 truncated 为 true。

每一行都有以下 CloudX 指标：

字段	含义
`cloudx_revenue`	CloudX 确认的收入。
`cloudx_ecpm`	`cloudx_revenue * 1000 / cloudx_impressions`；展示数为零时为 `0`。
`cloudx_impressions`	CloudX 展示数。

下列需求方和差异字段只有在该行有需求方数据时才是数字。字段缺失表示不可用，不表示零。即使报表日期已覆盖，需求方隐藏收入也可能导致该指标不可用。在未映射视图中，应使用 excluded_partner_revenue 和 excluded_partner_impressions 读取被排除的数据，而不是已映射对比指标。

字段	含义
`partner_revenue`	需求方上报收入。
`revenue_delta`	`cloudx_revenue - partner_revenue`。
`revenue_delta_percent`	收入差异占需求方收入的百分比。需求方收入低于 `0.005` 时缺失。
`partner_ecpm`	`partner_revenue * 1000 / partner_impressions`；展示数为零时为 `0`。需要两个需求方指标均可用。
`ecpm_delta`	`cloudx_ecpm - partner_ecpm`。
`ecpm_delta_percent`	eCPM 差异占需求方 eCPM 的百分比。需求方 eCPM 低于 `0.005` 时缺失。
`partner_impressions`	需求方上报展示数。
`impression_delta`	`cloudx_impressions - partner_impressions`。
`impression_delta_percent`	展示差异占需求方展示数的百分比。需求方展示数低于 `1` 时缺失。

字段	含义
`demand_source`	所选的受支持需求方来源枚举值。
`status`	`comparable`、`not_connected`、`no_partner_data`、`unmapped_partner_data`、`stale_partner_data` 或 `unmapped`。`unmapped` 用于未映射视图。
`provider_business_id`	动态需求方业务 ID。
`provider_property_id`	动态需求方资产 ID。
`partner_ad_unit_id`	动态需求方广告单元 ID。
`partner_ad_unit_name`	需求方广告单元名称。
`provider_endpoint`	来自映射的端点字符串，或以逗号和空格分隔的端点字符串。可以为空，不是封闭的 API 枚举。
`demand_type`	来自映射的需求分类字符串，或以逗号和空格分隔的分类。可以为空，不是封闭的 API 枚举。
`partner_ad_formats`	需求方广告格式字符串，不是封闭的 API 枚举。需求方未提供格式时可以为空数组。
`cloudx_ad_unit_ids`	关联的动态 CloudX 广告单元 ID。
`excluded_partner_revenue`	在未映射视图中，从已映射对比排除的需求方收入。可以缺失。
`excluded_partner_impressions`	在未映射视图中，从已映射对比排除的需求方展示数。可以缺失。

CloudX 先形成需求方广告单元聚合，再应用 cloudx_ad_unit_id。只要任一关联 ID 匹配，响应会保留该聚合的完整指标和完整 cloudx_ad_unit_ids 列表。

JSON 示例

{
  "rows": [{"cloudx_revenue": 14.25, "partner_revenue": 13.9, "revenue_delta": 0.35, "revenue_delta_percent": 2.5179856115107913, "cloudx_ecpm": 11.875, "partner_ecpm": 11.583333333333334, "ecpm_delta": 0.2916666666666661, "ecpm_delta_percent": 2.5179856115107864, "cloudx_impressions": 1200, "partner_impressions": 1200, "impression_delta": 0, "impression_delta_percent": 0, "demand_source": "meta", "status": "comparable", "provider_business_id": "business-demo", "provider_property_id": "property-demo", "partner_ad_unit_id": "partner-unit-demo", "partner_ad_unit_name": "Sample banner", "provider_endpoint": "meta", "demand_type": "standard", "partner_ad_formats": [], "cloudx_ad_unit_ids": ["ad-unit-home"]}],
  "row_count": 1,
  "limit": 1000,
  "truncated": false
}