> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Buzzvil data source in Adriel.

## Introduction

Buzzvil is a Korean mobile lock-screen advertising network. The connector pulls campaign performance data across four hierarchy levels — ad account, campaign, ad set, and ad — from the Buzzvil public API, authenticated with a static API token issued by Buzzvil.

As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration.

To connect this data source, see [How to connect Buzzvil to Adriel](/data-sources/a-f/buzzvil/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers the ad account, campaigns, ad sets, and ads. The hierarchy refreshes twice daily, at **4:00 PM (UTC)** and **5:00 AM (UTC)**.

### Reports data

Reports include daily performance for the ad account, campaigns, ad sets, and ads.

**Real-time.** Report data is fetched from Buzzvil on demand when a dashboard loads, so the latest values are always visible. On top of that, a scheduled hourly sync (UTC) refreshes the last **30 days** for the ad account, campaign, ad set, and ad levels.

Long-range queries are fetched in chunks of up to **100 days**.

## Architecture levels

Ad account → Campaign → Ad set → Ad

The ad account level is synthesized by Adriel — Buzzvil does not natively expose an ad-account hierarchy — so that widgets can group by ad account consistently with other marketing connectors.

## Date range limits

| Breakdown | Max range |
| --------- | --------- |
| Daily     | 93 days   |
| Weekly    | 1 year    |
| Monthly   | 2 years   |

## Metrics

<Note>
  **How to read the columns**
  **Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
  **API Key** in code style like `impression` is the literal Buzzvil report field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

### Reach & impressions

| Metric             | Description                    | Data type | API Key                                 |
| ------------------ | ------------------------------ | --------- | --------------------------------------- |
| Impressions        | Total ad displays.             | Number    | `impression`                            |
| Unique impressions | Distinct users who saw the ad. | Number    | `conversions:buzzvil:unique_impression` |

### Click performance

| Metric        | Description                                         | Data type  | API Key                                  |
| ------------- | --------------------------------------------------- | ---------- | ---------------------------------------- |
| Clicks        | Total ad clicks.                                    | Number     | `click`                                  |
| Unique clicks | Distinct users who clicked.                         | Number     | `conversions:buzzvil:unique_click`       |
| CTR           | Click-through rate — clicks divided by impressions. | Percentage | *Adriel-computed (clicks ÷ impressions)* |

### Cost & efficiency

<Note>
  Currency values are reported in the account currency read from the first ad group at connection time and pinned to the data source.
</Note>

| Metric              | Description                             | Data type | API Key                                        |
| ------------------- | --------------------------------------- | --------- | ---------------------------------------------- |
| Cost                | Reported spend in the account currency. | Currency  | `cost`                                         |
| CPM                 | Cost per thousand impressions.          | Currency  | *Adriel-computed (cost ÷ impressions × 1,000)* |
| CPC                 | Cost per click.                         | Currency  | *Adriel-computed (cost ÷ clicks)*              |
| Cost per conversion | Spend divided by conversions.           | Currency  | *Adriel-computed (cost ÷ conversions)*         |

### Engagement

| Metric        | Description                                   | Data type | API Key                            |
| ------------- | --------------------------------------------- | --------- | ---------------------------------- |
| Playtime      | Cumulative video or playable engagement time. | Duration  | `conversions:buzzvil:playtime`     |
| SNS followers | Follow events attributed to the campaign.     | Number    | `conversions:buzzvil:sns_follower` |

### Conversion performance

| Metric          | Description                               | Data type  | API Key                                  |
| --------------- | ----------------------------------------- | ---------- | ---------------------------------------- |
| Conversions     | Conversion events as reported by Buzzvil. | Number     | `conversion`                             |
| Conversion rate | Conversions divided by clicks.            | Percentage | *Adriel-computed (conversions ÷ clicks)* |

## Breakdowns

Buzzvil supports grouping by hierarchy level and by date. It does not expose audience, device, placement, or geographic segmentation breakdowns.

### Ad structure

| Breakdown  | Description                             | API Key     |
| ---------- | --------------------------------------- | ----------- |
| Ad account | Group by ad account.                    | `adAccount` |
| Campaign   | Group by campaign.                      | `campaign`  |
| Ad set     | Group by ad set (ad group / line item). | `adSet`     |
| Ad         | Group by creative (creative set).       | `ad`        |

<Note>
  The ad account breakdown groups by the single ad account Adriel synthesizes per data source, since Buzzvil has no native ad-account level.
</Note>

### Time & date

| Breakdown | Description             | API Key |
| --------- | ----------------------- | ------- |
| Daily     | Split reports by day.   | `day`   |
| Weekly    | Split reports by week.  | `week`  |
| Monthly   | Split reports by month. | `month` |

## Limitations

* **No segmentation breakdowns** — Buzzvil exposes no audience, device, placement, or geographic breakdowns. Only hierarchy and date grouping are available.
* **Synthetic ad account level** — Buzzvil has no native ad-account hierarchy; Adriel synthesizes one ad account per data source so data can be grouped consistently with other connectors.
* **Currency captured once at connect time** — the reporting currency is read from the first ad group during connection setup and pinned to the data source. If the underlying account currency changes upstream, reconnect the data source to pick up the new value.
* **Missing conversion fields** — the four `conversions:buzzvil:*` engagement fields are taken directly from the raw report row; when absent they are reported as undefined rather than zero.
* **Deleted elements not provided** — data for campaigns or ad sets deleted upstream is not returned; a deleted item encountered during a report fetch is surfaced as a soft-error row and the rest of the query continues.
* **No conversion value** — Buzzvil reports conversion counts but not conversion value, so revenue- and ROAS-style metrics are not available.

## API references

* Buzzvil public API base endpoint: `https://ad.buzzvil.com/api/public/`
* Connection validation and asset discovery use the Buzzvil `adgroups` endpoint.

## See also

* [How to connect Buzzvil to Adriel](/data-sources/a-f/buzzvil/how-to-connect) (paired how-to)
* [Kakao Moment data reference](/data-sources/g-n/kakao-moment/data-reference) — another marketing connector for the Korean market