> ## 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 Naver Search Ads data source in Adriel.

## Introduction

Naver Search Ads is Naver's paid search advertising platform, used to run search-keyword, shopping search, brand search, and place-search campaigns across Naver's search results, its Shopping vertical, and content partners. The platform supports CPC and CPM payment models across awareness, traffic, and conversion objectives, with bidding tied to Korean-language keywords, shopping-product feeds, and audience segments within the Naver ecosystem. The connector imports campaign structure, performance metrics, and conversion data through the Naver Search Ad API.

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 Naver Search Ads to Adriel](/data-sources/g-n/naver-search-ads/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers ad accounts, campaigns, ad sets (ad groups), ads, and keywords. It refreshes twice daily at **4:00 PM UTC** and **5:00 AM UTC**. On data source creation, the cache fills with **365 days** of historical data for the ad account, campaign, ad set, and ad levels, and **186 days** for the keyword level.

### Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad sets, ads, and keywords, plus per-ad-account segmentations for age, gender, device target, hour of day, search term view, location, and shopping keyword.

**Cache-only.** Report data comes from cached daily performance snapshots. Dashboard queries always read from the last snapshot rather than live from Naver.

**Uniqueness caveat.** Metrics based on uniqueness (such as reach) can be overvalued when viewed for date periods longer than one day, because uniqueness is computed per snapshot rather than across the full range.

**Refresh schedule.** Reports refresh on several schedules:

* **9:00 PM UTC** — syncs the last **5 days** for ad account, campaign, ad set, ad, and keyword, plus per-ad-account age, gender, device target, hour of day, search term view, location, and shopping keyword
* **2:00 AM, 4:00 AM, and 6:00 AM UTC** — syncs the last **1 day** for campaign, ad set, and ad
* **9:00 AM UTC every 2 days** — syncs the last **21 days** for the same levels and segmentations as the 9:00 PM job
* **1:00 AM and 5:00 AM UTC** — syncs the last **3 days** for campaign, ad set, and ad
* **12:00 AM UTC** — syncs the last **2 days** for campaign, ad set, and ad

Data is reliable within the cache sync period. Data outside this range may be incomplete or inaccurate due to legacy caching behavior.

## Architecture levels

Ad account → Campaign → Ad set → Ad → Keyword

## Date range limits

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

The connector guarantees access to the most recent 1 year of data. Anything older relies on the legacy cache and may be incomplete or unavailable.

## 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 `salesAmt` is the literal Naver Search Ad API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

### Reach and impressions

| Metric      | Description                                | Data type | API Key                                                     |
| ----------- | ------------------------------------------ | --------- | ----------------------------------------------------------- |
| Impressions | Total times the ads were displayed.        | Number    | `impCnt`                                                    |
| Reach       | Unique users who saw the ad at least once. | Number    | *Adriel-aggregated (uniqueness metric; see refresh caveat)* |

### Click performance

| Metric       | Description              | Data type  | API Key                                  |
| ------------ | ------------------------ | ---------- | ---------------------------------------- |
| Clicks (all) | Total clicks on the ads. | Number     | `clkCnt`                                 |
| Link clicks  | Clicks on the ad's link. | Number     | `clkCnt`                                 |
| CTR          | Click-through rate.      | Percentage | *Adriel-computed (clicks ÷ impressions)* |

### Cost and spend

<Note>
  Currency values are reported in KRW. Naver Search Ads accounts are supported in KRW only.
</Note>

| Metric   | Description                                            | Data type | API Key                                        |
| -------- | ------------------------------------------------------ | --------- | ---------------------------------------------- |
| Ad spend | Total amount spent on ads during the reporting period. | Currency  | `salesAmt`                                     |
| CPC      | Cost per click.                                        | Currency  | *Adriel-computed (spend ÷ clicks)*             |
| CPM      | Cost per thousand impressions.                         | Currency  | *Adriel-computed (spend ÷ impressions × 1000)* |
| CPR      | Cost per result — spend divided by desired outcomes.   | Currency  | *Adriel-computed*                              |

### Conversion performance

| Metric           | Description                                                                                                    | Data type  | API Key                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------- |
| Conversions      | Attributed actions matching the defined conversion events. Defaults to Purchase when no specific event is set. | Number     | `ConversionCount`                            |
| Conversion value | Monetary value of attributed conversions.                                                                      | Currency   | `SalesByConversion`                          |
| Revenue          | Conversion revenue. Defaults to Purchase when no specific event is set.                                        | Currency   | `SalesByConversion`                          |
| ROAS             | Return on ad spend.                                                                                            | Ratio      | *Adriel-computed (conversion value ÷ spend)* |
| CPA              | Cost per acquisition.                                                                                          | Currency   | *Adriel-computed (spend ÷ conversions)*      |
| Conversion rate  | Conversions divided by clicks.                                                                                 | Percentage | *Adriel-computed*                            |

### Conversion event metrics

Each conversion event active on the connected Naver account is auto-imported as its own metric, and only events that are active on the account appear on the dashboard. For every imported event, Adriel also generates derived KPIs such as ROAS, CPA, and conversion rate. Common Korean event names include:

* 구매 (Purchase) — total / direct / indirect
* 가입 (Sign-up) — total / direct / indirect
* 장바구니 넣기 (Add to cart) — total / direct / indirect
* 신청 혹은 예약 (Application or reservation) — total / direct / indirect
* 기타 (Other) — total / direct / indirect

<Note>
  **Purchase Complete (구매완료) updates faster than other events.** This metric is fetched through a separate sync API call rather than the async report path, then merged into report rows, so its numbers refresh ahead of other conversion metrics.
</Note>

### Video performance

| Metric                                         | Description                                                 | Data type | API Key         |
| ---------------------------------------------- | ----------------------------------------------------------- | --------- | --------------- |
| Video impressions                              | Number of times video creatives started displaying.         | Number    | `videoPlay`     |
| Video play                                     | Any play of the video, regardless of duration.              | Number    | *Adriel-mapped* |
| Views                                          | Aggregated count of all qualified video views.              | Number    | *Adriel-mapped* |
| Video played to 25% / 50% / 75% / 100% (Views) | Plays reaching each completion threshold.                   | Number    | *Adriel-mapped* |
| ThruPlays                                      | Video viewed to at least 97% or 15s, whichever comes first. | Number    | *Adriel-mapped* |
| 2s / 3s / 6s / 15s / 30s video plays           | Plays lasting at least the stated duration.                 | Number    | *Adriel-mapped* |

### Engagement

| Metric         | Description                                                              | Data type | API Key         |
| -------------- | ------------------------------------------------------------------------ | --------- | --------------- |
| Engagement     | Any user interaction with the ad, such as clicks, reactions, and shares. | Number    | *Adriel-mapped* |
| Post reactions | Reactions on the post-style ad.                                          | Number    | *Adriel-mapped* |
| Post comments  | Comments on the post.                                                    | Number    | *Adriel-mapped* |
| Post shares    | Shares of the post.                                                      | Number    | *Adriel-mapped* |
| Post saves     | Saves of the post.                                                       | Number    | *Adriel-mapped* |

### Budget and schedule

| Metric          | Description                                                | Data type | API Key                            |
| --------------- | ---------------------------------------------------------- | --------- | ---------------------------------- |
| Daily budget    | Configured daily budget on the campaign or ad set.         | Currency  | `dailyBudget`, `sharedDailyBudget` |
| Lifetime budget | Total budget allocated for the campaign's entire lifetime. | Currency  | *Adriel-mapped*                    |
| Bid cap         | Bid cap set on the ad set or campaign.                     | Currency  | `bidAmt`                           |
| Bid strategy    | Bid strategy set on the ad set or campaign.                | Text      | `deliveryMethod`                   |
| Starts          | Reporting period start date.                               | Date      | `periodStartDt`                    |
| Ends            | Reporting period end date.                                 | Date      | `periodEndDt`                      |

### UTM tracking

<Note>
  UTM values are parsed by Adriel, not returned by Naver. Adriel reads the UTM query parameters from each ad's configuration or landing URL and exposes them as both metrics and breakdowns.
</Note>

| Metric       | Description                      | API Key                                       |
| ------------ | -------------------------------- | --------------------------------------------- |
| UTM Source   | Parsed `utm_source` parameter.   | *Adriel-parsed from ad config or landing URL* |
| UTM Medium   | Parsed `utm_medium` parameter.   | *Adriel-parsed*                               |
| UTM Campaign | Parsed `utm_campaign` parameter. | *Adriel-parsed*                               |
| UTM Content  | Parsed `utm_content` parameter.  | *Adriel-parsed*                               |
| UTM Term     | Parsed `utm_term` parameter.     | *Adriel-parsed*                               |

### Campaign structure metadata

| Metric          | Description                                          | Data type | API Key                                                                  |
| --------------- | ---------------------------------------------------- | --------- | ------------------------------------------------------------------------ |
| Ad account name | Name of the ad account.                              | Text      | `name`                                                                   |
| Campaign name   | Campaign name, with type.                            | Text      | `name`, `campaignTp`                                                     |
| Ad set name     | Ad set / ad group name.                              | Text      | `name`                                                                   |
| Ad name         | Ad name, with type.                                  | Text      | `name`, `type`                                                           |
| Keyword name    | Keyword text (search campaigns only).                | Text      | `keyword`                                                                |
| Status          | Mapped Naver status (running, paused, or in review). | Text      | `status`, `statusReason`, `inspectStatus`                                |
| Objective       | Campaign objective.                                  | Text      | `campaignTp`                                                             |
| Channel         | Channel where the ad is published.                   | Text      | *Constant value ("naver-search-ads")*                                    |
| Creative URL    | URL of the ad creative.                              | URL       | `ad.thumbnail`, `referenceData.imageUrl`, `ad.logoImage`, `ad.imagePath` |
| Creative type   | Format of the ad creative.                           | Text      | *Resolved from ad metadata*                                              |

## Breakdowns

### Standard hierarchy

| Breakdown  | Description                               | API Key              |
| ---------- | ----------------------------------------- | -------------------- |
| Ad account | Group by ad account.                      | `name`               |
| Campaign   | Group by campaign.                        | `name`, `campaignTp` |
| Ad set     | Group by ad set (or ad group).            | `name`               |
| Ad         | Group by ad.                              | `name`, `type`       |
| Keyword    | Group by keyword (search campaigns only). | `keyword`            |

### Identifiers

| Breakdown     | Description                            | API Key     |
| ------------- | -------------------------------------- | ----------- |
| Ad account ID | Group by ad account identifier.        | *Object ID* |
| Campaign ID   | Group by campaign identifier.          | *Object ID* |
| Ad set ID     | Group by ad set / ad group identifier. | *Object ID* |
| Ad ID         | Group by ad identifier.                | *Object ID* |

### Demographics and geography

<Note>
  These segmentations are available per ad account and are decoded by Adriel from Naver's report codes.
</Note>

| Breakdown     | Description          | API Key                                   |
| ------------- | -------------------- | ----------------------------------------- |
| Age           | Audience age range.  | *Decoded from Naver age code (`AG~XXXX`)* |
| Gender        | Audience gender.     | *Decoded from Naver gender code (`GN~X`)* |
| Location      | Named Korean region. | `regionCode` *(decoded)*                  |
| Device target | PC vs. Mobile.       | `pcMobileType` (`P` = PC, else Mobile)    |

### Time and device

| Breakdown        | Description                                                                                              | API Key |
| ---------------- | -------------------------------------------------------------------------------------------------------- | ------- |
| Hour of day      | Hour during which the impression occurred, in HH:00:00–HH:59:59. Available per ad account.               | `hours` |
| Hourly breakdown | Group results by hour of day. When the date range spans multiple days, hours are aggregated across days. | `hours` |

### Naver segmentations

| Breakdown        | Description                                              | API Key         |
| ---------------- | -------------------------------------------------------- | --------------- |
| Search term view | Expanded search keyword. Available per ad account.       | `searchKeyword` |
| Shopping keyword | Naver Shopping search keyword. Available per ad account. | `searchKeyword` |

### Objective and status

| Breakdown | Description                              | API Key                                   |
| --------- | ---------------------------------------- | ----------------------------------------- |
| Objective | Group campaigns by their objective.      | `campaignTp`                              |
| Status    | Group by campaign, ad set, or ad status. | `status`, `statusReason`, `inspectStatus` |

### Channel and grouping

<Note>
  Channel is an Adriel-added constant used for cross-connector rollup; for Naver Search Ads it is always "naver-search-ads".
</Note>

| Breakdown | Description                                              |
| --------- | -------------------------------------------------------- |
| Channel   | Constant grouping label used for cross-connector rollup. |

### Time and date grouping

<Note>
  Naver returns daily records; Adriel aggregates them into these views for reporting.
</Note>

| Breakdown         | Description                                        |
| ----------------- | -------------------------------------------------- |
| Daily breakdown   | Split reports by day (maximum 93 days).            |
| Weekly breakdown  | Split reports by week (maximum 1 year).            |
| Monthly breakdown | Split reports by calendar month (maximum 2 years). |

### UTM tracking

<Note>
  Naver doesn't return UTM values; Adriel parses them from each ad's configuration or landing URL and exposes them as breakdowns for grouping.
</Note>

| Breakdown    | Description                     |
| ------------ | ------------------------------- |
| UTM Source   | Group by parsed `utm_source`.   |
| UTM Medium   | Group by parsed `utm_medium`.   |
| UTM Campaign | Group by parsed `utm_campaign`. |
| UTM Content  | Group by parsed `utm_content`.  |
| UTM Term     | Group by parsed `utm_term`.     |

## Limitations

* **KRW only** — currency is hardcoded to KRW. Naver Search Ads accounts that report in any other currency are not supported.
* **Customer ID required** — requests fail immediately if the Customer ID is missing or set to the literal string `dummy`, before any request is sent to Naver.
* **1-year reliable window** — the connector guarantees the most recent 1 year of data. Older data relies on the legacy cache and may be incomplete or unavailable.
* **No deleted-data retrieval** — data is not available after an element is deleted on the platform.
* **Keyword-level backfill is shorter** — the initial cache holds 186 days for keywords, versus 365 days for the ad account, campaign, ad set, and ad levels.

## API references

* [Naver Search Ad API documentation](https://naver.github.io/searchad-apidoc/)

## See also

* [How to connect Naver Search Ads to Adriel](/data-sources/g-n/naver-search-ads/how-to-connect) (paired how-to)
* [Naver GFA data reference](/data-sources/g-n/naver-gfa/data-reference) — for display ads on Naver's network
* [Naver Smart Store data reference](/data-sources/g-n/naver-smart-store/data-reference) — for e-commerce orders