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

## Introduction

Yahoo Japan Search Ads (Yahoo! JAPAN Ads — Search Ads) is Yahoo Japan's paid search advertising platform for the Japanese market. Advertisers run keyword-targeted search campaigns, and the connector imports the resulting architecture and daily performance data via the Yahoo! JAPAN Ads API. It shares its authentication, connection, cache, and reporting pipeline with Yahoo Japan Display Ads through a common base, but uses the search-specific API endpoint, metric set, and keyword-level reporting.

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 Yahoo Japan Search Ads to Adriel](/data-sources/o-z/yahoo-japan-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**.

### Reports data

Reports include daily performance for ad accounts, campaigns, ad sets, ads, and keywords.

**Cache-only.** Report data is served from cached daily performance snapshots and is never fetched on demand when a dashboard loads. Each dashboard view aggregates data from the most recent snapshot. Because snapshots are aggregated daily, metrics based on uniqueness (such as Reach) may be overvalued when viewed over a date range longer than one day.

When a data source is first created, the cache is filled for the previous **93 days** across all levels (ad account, campaign, ad set, ad, keyword).

**Refresh schedule.** Cached reports refresh on three overlapping schedules:

* **7:00 AM UTC, every 5 days** — syncs the last **90 days**
* **8:00 PM UTC and 3:00 AM UTC daily** — syncs the last **5 days**
* **4:00 PM UTC daily** — syncs the last **30 days**

Each sync covers ad account, campaign, ad set, ad, and keyword, plus the device, country, and location breakdowns at the ad-account level. Data is considered reliable within the cache sync period; data outside this range may be incomplete or missing.

## Architecture levels

Ad account → Campaign → Ad set (ad group) → Ad → Keyword

The same five levels are used for both architecture (entity metadata) and reports (performance) queries.

## Date range limits

To keep query sizes manageable, the connector enforces these maximum look-back windows per time breakdown:

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

## Metrics

<Note>
  **How to read the columns**

  The **Data type** column uses Adriel's standardized vocabulary (Number, Currency, Percentage, Ratio, Text, URL, Date, Array, Boolean). In the **API Key** column, `code` style is the literal field or column name returned by the Yahoo! JAPAN Ads API, while *italic text* describes how a value is produced when it doesn't map cleanly to a single API field (Adriel-computed rates or aggregated values).
</Note>

### Delivery & clicks

| Metric       | Description                                                       | Data type  | API Key                 |
| ------------ | ----------------------------------------------------------------- | ---------- | ----------------------- |
| Impressions  | Total times ads were displayed, regardless of interaction.        | Number     | `Impressions`           |
| Reach        | Unique users who saw the ad at least once.                        | Number     | *Aggregated internally* |
| Frequency    | Average times each reached user saw the ad (impressions ÷ reach). | Ratio      | *Adriel-computed*       |
| Clicks (all) | Total clicks, including link and other interactions.              | Number     | `Clicks`                |
| Link clicks  | Clicks on the ad's link.                                          | Number     | `Clicks`                |
| CTR          | Click-through rate (clicks ÷ impressions).                        | Percentage | *Adriel-computed*       |
| Outbound CTR | Outbound clicks divided by impressions.                           | Percentage | *Adriel-computed*       |
| Engagement   | Any user interaction with the ad.                                 | Number     | *Aggregated internally* |

### Cost & spend

| Metric          | Description                                                   | Data type | API Key                                    |
| --------------- | ------------------------------------------------------------- | --------- | ------------------------------------------ |
| Ad spend        | Total amount spent during the reporting period.               | Currency  | `Cost`                                     |
| CPC             | Cost per click (spend ÷ clicks).                              | Currency  | *Adriel-computed*                          |
| CPM             | Cost per thousand impressions.                                | Currency  | *Adriel-computed*                          |
| CPR             | Cost per result — spend divided by the resolved Result count. | Currency  | *Adriel-computed*                          |
| Budget          | Budget set on the campaign or ad set (daily or lifetime).     | Currency  | *Resolved from campaign / ad set settings* |
| Daily budget    | Daily budget set on the campaign or ad set.                   | Currency  | *Resolved from campaign / ad set settings* |
| Lifetime budget | Total budget allocated for the campaign's lifetime.           | Currency  | *Resolved from campaign / ad set settings* |
| Bid cap         | Bid cap set on the ad set or campaign.                        | Currency  | *Resolved from campaign / ad set settings* |

<Note>
  **Currency conversion**

  Each ad account's currency comes from its Yahoo! JAPAN Ads settings. When an ad account's currency differs from the workspace currency, costs are automatically converted using the current day's exchange rate.
</Note>

### Conversions & value

| Metric                   | Description                                                                                                      | Data type  | API Key              |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ---------- | -------------------- |
| Conversions              | Attributed actions matching the defined conversion events. Defaults to "Purchase" when no specific event is set. | Number     | `Conversions`        |
| All conversions          | Count of every conversion action recorded — primary plus secondary.                                              | Number     | `Conversions (all)`  |
| Conversion value         | Monetary value of attributed conversions.                                                                        | Currency   | `Conv. value`        |
| All conversions value    | Monetary value of all conversions (primary + secondary).                                                         | Currency   | `Conv. value (all)`  |
| Revenue                  | Alias for conversion value — monetary value of attributed conversions.                                           | Currency   | `Conv. value`        |
| Cross-device conversions | Conversions that started on one device and completed on another.                                                 | Number     | `Cross-device conv.` |
| ROAS                     | Return on ad spend (conversion value ÷ spend).                                                                   | Ratio      | *Adriel-computed*    |
| CPA                      | Cost per action (spend ÷ conversions).                                                                           | Currency   | *Adriel-computed*    |
| CVR                      | Conversion rate (conversions ÷ clicks × 100%).                                                                   | Percentage | *Adriel-computed*    |
| Result rate              | Results divided by clicks.                                                                                       | Percentage | *Adriel-computed*    |

<Note>
  **Conversions vs. all conversions**

  "Conversions" reflects the conversion actions configured as the account's primary events, while "All conversions" includes every recorded conversion action. Two different numbers in different widgets usually means each is using a different one of these.
</Note>

### Custom conversion events

Each conversion action tracked in the Yahoo! JAPAN Ads account is automatically imported and only appears in dashboards when the underlying event is active. Conversions may be shown as a single total or grouped by conversion category (for example, `category__Purchase / Sales`, `category__Application`). For every imported event, these metrics are auto-generated:

| Pattern                                                       | Description                                               | Data type  | API Key                        |
| ------------------------------------------------------------- | --------------------------------------------------------- | ---------- | ------------------------------ |
| `Yahoo Japan Search Ads: [conversion_name]`                   | Count of that conversion, tracked by the account's pixel. | Number     | *Resolved from the event name* |
| `Yahoo Japan Search Ads: [conversion_name]: Conversion value` | Monetary value attributed to that conversion.             | Currency   | *Resolved*                     |
| `Yahoo Japan Search Ads: [conversion_name]: CPA`              | Cost per action (spend ÷ count).                          | Currency   | *Adriel-computed*              |
| `Yahoo Japan Search Ads: [conversion_name]: ROAS`             | Return on ad spend (value ÷ spend).                       | Ratio      | *Adriel-computed*              |
| `Yahoo Japan Search Ads: [conversion_name]: CVR`              | Conversion rate (count ÷ clicks × 100%).                  | Percentage | *Adriel-computed*              |

### Impression share & quality

<Note>
  Impression share metrics use percentage values with **unique** aggregation — they are not summable across rows, so a total row over multiple entities will not equal the sum of the individual values. They are available at the ad-account, campaign, and (partially) ad-set levels, but not at the ad level.
</Note>

| Metric                                    | Description                                                         | Data type  | API Key                                            |
| ----------------------------------------- | ------------------------------------------------------------------- | ---------- | -------------------------------------------------- |
| Impression share                          | Impressions received divided by the estimated impressions eligible. | Percentage | `Impression share`                                 |
| Exact match impression share              | Impression share for searches that exactly matched the keyword.     | Percentage | `Exact match impression share`                     |
| Search top impression share               | Share of top-of-page impressions received.                          | Percentage | `Search top impression share`                      |
| Search absolute top impression share      | Share of absolute-top impressions received.                         | Percentage | `Search absolute top impression share`             |
| Budget lost impression share              | Impressions lost because of budget.                                 | Percentage | `Lost impression share (budget)`                   |
| Rank lost impression share                | Impressions lost because of ad rank.                                | Percentage | `Lost impression share (rank)`                     |
| Budget lost top impression share          | Top impressions lost because of budget.                             | Percentage | `Search top lost impression share (budget)`        |
| Rank lost top impression share            | Top impressions lost because of ad rank.                            | Percentage | `Search top lost impression share (rank)`          |
| Budget lost absolute top impression share | Absolute-top impressions lost because of budget.                    | Percentage | `Search absolute top impression share (budget)`    |
| Rank lost absolute top impression share   | Absolute-top impressions lost because of ad rank.                   | Percentage | `Search absolute top lost impression share (rank)` |

Keyword-level campaigns additionally expose quality-score fields returned by the platform. These are available at the keyword level only:

| Metric                                | Description                                     | Data type | API Key                                 |
| ------------------------------------- | ----------------------------------------------- | --------- | --------------------------------------- |
| Quality index                         | Yahoo Japan's keyword quality index.            | Number    | `QUALITY_INDEX`                         |
| First page bid estimate               | Estimated bid for first-page placement.         | Currency  | `FIRST_PAGE_BID_ESTIMATE`               |
| Top of page bid estimate              | Estimated bid for top-of-page placement.        | Currency  | `TOP_OF_PAGE_BID_ESTIMATE`              |
| Keyword match type                    | Match type applied to the keyword.              | Text      | `KEYWORD_MATCH_TYPE`                    |
| Search predicted CTR                  | Predicted click-through-rate quality component. | Text      | `SEARCH_PREDICTED_CTR`                  |
| Historical quality score              | Historical overall quality score.               | Number    | `HISTORICAL_QUALITY_SCORE`              |
| Post-click quality score              | Landing-page experience quality component.      | Text      | `POST_CLICK_QUALITY_SCORE`              |
| Creative quality score                | Ad relevance quality component.                 | Text      | `CREATIVE_QUALITY_SCORE`                |
| Historical landing page quality score | Historical landing-page experience component.   | Text      | `HISTORICAL_LANDING_PAGE_QUALITY_SCORE` |

### Campaign structure & metadata

| Metric          | Description                                                    | Data type | API Key                                    |
| --------------- | -------------------------------------------------------------- | --------- | ------------------------------------------ |
| Ad account name | Name of the ad account.                                        | Text      | `accountName - accountId`                  |
| Campaign name   | Group by campaign name.                                        | Text      | `campaignName`                             |
| Ad set name     | Group by ad set (ad group) name.                               | Text      | `adGroupName`                              |
| Ad name         | Group by ad name.                                              | Text      | `adName`                                   |
| Keyword name    | Keyword text (Search campaigns only).                          | Text      | *Resolved from keyword entity*             |
| Status          | Campaign / ad set / ad status.                                 | Text      | *Resolved from entity status*              |
| Channel         | Channel where the ad is published.                             | Text      | *Constant value*                           |
| Objective       | Campaign objective grouping.                                   | Text      | *Resolved from campaign settings*          |
| Bid strategy    | Bid strategy set on the ad set or campaign.                    | Text      | *Resolved from campaign / ad set settings* |
| Creative type   | Type of the ad creative.                                       | Text      | *Resolved from creative*                   |
| Creative URL    | Destination URL of the ad.                                     | URL       | *Resolved from creative*                   |
| Creative image  | Ad creative image; visually similar images are auto-clustered. | URL       | *Resolved from creative asset URLs*        |

### UTM tracking

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

## Breakdowns

### Standard hierarchy

| Breakdown    | Description                                    | API Key                        |
| ------------ | ---------------------------------------------- | ------------------------------ |
| Ad account   | Group by ad account.                           | `accountName`                  |
| Campaign     | Group by campaign.                             | `campaignName`                 |
| Ad set       | Group by ad set (ad group).                    | `adGroupName`                  |
| Ad           | Group by ad.                                   | `adName`                       |
| Keyword      | Group by keyword ID (Search campaigns only).   | *Resolved from keyword entity* |
| Keyword text | Group by keyword text (Search campaigns only). | *Resolved from keyword entity* |

### Device & search term

| Breakdown     | Description                                                    | API Key        |
| ------------- | -------------------------------------------------------------- | -------------- |
| Device target | Group by device (mobile, desktop, tablet).                     | `DEVICE`       |
| Search term   | Group by the actual user search query (Search campaigns only). | `SEARCH_QUERY` |

### Geographic

| Breakdown | Description                                       | API Key             |
| --------- | ------------------------------------------------- | ------------------- |
| Location  | Split reports by city where impressions occurred. | `CITY`              |
| Country   | Split reports by two-digit country code.          | `COUNTRY_TERRITORY` |

### Time & date grouping

<Note>
  The platform returns daily records; Adriel groups them into these views for reporting.
</Note>

| Breakdown                  | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown        | Automatically picks the best granularity for the date range. |
| Daily                      | Split reports by day (max 93-day range).                     |
| Weekly (Start: Mon)        | Split reports by week, starting Monday (max 1-year range).   |
| Weekly (Start: Sun)        | Split reports by week, starting Sunday (max 1-year range).   |
| Week Date Breakdown        | Group by the day of the week the impression occurred.        |
| Week Number Breakdown (W#) | Split by week number in the year.                            |
| Monthly                    | Split reports by calendar month.                             |
| Quarterly                  | Split reports by calendar quarter.                           |
| Yearly                     | Split reports by calendar year.                              |

### Creative analysis

<Note>
  Adriel post-processes ad creatives to generate these breakdowns.
</Note>

| Breakdown        | Description                                     |
| ---------------- | ----------------------------------------------- |
| Creative image   | Auto-clusters visually similar creative images. |
| Color Clustering | Groups creatives by dominant color.             |
| Emoji Analysis   | Groups creatives by emoji usage.                |

### UTM tracking

<Note>
  UTM values are parsed by Adriel from each ad's configuration and landing URL, not returned by the platform.
</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

Based on the current connector, Yahoo Japan Search Ads has the following limits:

* **Cache-only reports** — report data is served from cached daily snapshots and is never fetched on demand. Data is reliable only within the cache sync window; older data may be incomplete or missing.
* **Uniqueness metrics over long ranges** — metrics based on uniqueness (such as Reach) may be overvalued when a date range longer than one day is viewed, because snapshots are aggregated daily.
* **Impression share not summable** — impression share metrics use unique aggregation and are not available at the ad level; budget-lost impression share is also excluded at the ad-set level.
* **Search-only breakdowns** — Keyword, Keyword text, and Search term breakdowns return data only for Search campaigns.
* **Age, gender, region, and site breakdowns are unavailable** — these are Display-Ads-only. A site breakdown request on Search Ads returns an `INVALID_DIMENSIONS_METRICS_COMBINATION` error.
* **No video or viewability metrics** — video-performance and viewability metrics are Display-Ads-only and do not populate for Search Ads.
* **Date range caps** — daily breakdowns are limited to 93 days, weekly to 1 year, and monthly to 2 years; data outside these windows may be truncated.

## API references

* [Yahoo! JAPAN Ads API documentation](https://ads-developers.yahoo.co.jp/)
* [Yahoo! JAPAN Ads Search Ads API reference](https://ads-developers.yahoo.co.jp/reference/searchads/)
* [Yahoo! JAPAN Ads OAuth (biz-oauth)](https://biz-oauth.yahoo.co.jp/)

## See also

* [How to connect Yahoo Japan Search Ads to Adriel](/data-sources/o-z/yahoo-japan-search-ads/how-to-connect) — step-by-step setup guide
* [Yahoo Japan Display Ads data reference](/data-sources/o-z/yahoo-japan-display-ads/data-reference)