> ## 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 Display Ads data source in Adriel.
## Introduction
Yahoo Japan Display Ads (YDA, also known as YDN) is the display advertising product of Yahoo! JAPAN Ads, covering banner, native, and video placements across the Yahoo! JAPAN network and its partner sites in Japan. The connector imports account structure and daily performance through the Yahoo Ads Display API, and standardizes them into Adriel's internal model.
As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration. Compared with Yahoo Japan Search Ads, Display Ads adds video and viewability metrics plus audience (age, gender), prefecture, and site breakdowns, and does not support keyword-level reporting.
To connect this data source, see [How to connect Yahoo Japan Display Ads to Adriel](/data-sources/o-z/yahoo-japan-display-ads/how-to-connect).
## Data refresh strategy
### Architecture data
Architecture covers ad accounts, campaigns, ad sets (ad groups), and ads. It refreshes at **4:00 PM UTC** and **5:00 AM UTC**.
### Reports data
Reports include daily performance for ad accounts, campaigns, ad sets, and ads.
**Cache only.** Report data comes from cached daily performance snapshots. When a dashboard loads, values are aggregated from the last snapshot rather than fetched live. Because of this, metrics based on uniqueness (such as reach) can be overvalued when viewed over a range longer than one day.
**Initial backfill.** When the data source is created, the cache is filled for the last **93 days** at the ad account, campaign, ad set, and ad levels.
**Refresh schedule.** Report data refreshes 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 schedule covers the ad account, campaign, ad set, ad, and audience/geo breakdowns (device, country, location, age, gender, region). Data is considered reliable within the cache sync period; data outside this range may be incomplete, missing, or not fully accurate due to legacy caching behavior.
## Architecture levels
Ad account → Campaign → Ad set (ad group) → Ad
Keyword-level reporting is not supported for Display Ads and always returns empty.
## 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
**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 `Impressions` is the literal field returned by the Yahoo Ads Display API. *Italic text* describes how a value is produced when it is derived by Adriel rather than mapping to a single API field.
### Delivery & clicks
| Metric | Description | Data type | API Key |
| ------------ | -------------------------------------------------------------- | ---------- | ------------------------------------------------------------ |
| Impressions | Total times the ads were displayed, regardless of interaction. | Number | `Impressions` |
| Reach | Unique users who saw the ad at least once. | Number | *Uniqueness metric; may be overvalued over multi-day ranges* |
| Frequency | Average number of times each reached person saw the ad. | Ratio | *Adriel-computed (impressions ÷ reach)* |
| Clicks (all) | Total clicks across all interaction types. | 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* |
### Cost & spend
If an ad account's currency differs from the Adriel workspace currency, costs are converted to the workspace currency using the current day's exchange rate.
| Metric | Description | Data type | API Key |
| --------------- | --------------------------------------------------------- | --------- | ------------------------------- |
| Ad spend | Total amount spent on ads 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 ÷ results). | Currency | *Adriel-computed* |
| Budget | Budget set on the campaign or ad set (daily or lifetime). | Currency | *From campaign/ad set settings* |
| Daily budget | Daily budget on the campaign or ad set. | Currency | *From campaign/ad set settings* |
| Lifetime budget | Total budget allocated for the campaign's lifetime. | Currency | *From campaign/ad set settings* |
| Bid strategy | Bid strategy configured on the campaign or ad set. | Text | *From campaign/ad set settings* |
| Bid cap | Bid cap configured on the campaign or ad set. | Text | *From campaign/ad set settings* |
### Conversions & value
Any conversion event tracked in the ad account is imported automatically, but only appears on the dashboard when the underlying event is active in the account. For each imported conversion, Adriel also generates derived KPIs — CVR, CPA, and ROAS.
| Metric | Description | Data type | API Key |
| ------------------------ | -------------------------------------------------------------------------------------------------- | ---------- | -------------------- |
| Conversions | Attributed actions matching the defined conversion events (defaults to Purchase when none is set). | Number | `Conversions` |
| Conversions (all) | All conversions, including cross-device and view-through. | Number | `Conversions (all)` |
| Conversion value | Monetary value of attributed conversions. | Currency | `Conv. value` |
| Conversion value (all) | Monetary value of all conversions. | Currency | `Conv. value (all)` |
| Revenue | Monetary value of attributed conversions (defaults to Purchase when none is set). | Currency | `Conv. value` |
| Cross-device conversions | Conversions attributed across devices. | Number | `Cross-device conv.` |
| ROAS | Return on ad spend (conversion value ÷ spend). | Ratio | *Adriel-computed* |
| Results | Outcome count based on the campaign objective. | Number | *From objective* |
| Result rate | Results divided by clicks. | Percentage | *Adriel-computed* |
| Result indicator | The event type behind the result count. | Text | *From objective* |
#### Custom conversion events
Each conversion event active in the ad account produces its own set of metrics. For an event named `[conversion_name]`:
| Pattern | Metric | Data type | API Key |
| ------------------------------------- | ------------------------------------------------- | ---------- | ---------------------------- |
| `[conversion_name]` | Number of conversions for that goal. | Number | *Per-event conversion count* |
| `[conversion_name]: CVR` | Conversion rate (conversions ÷ all clicks × 100). | Percentage | *Adriel-computed* |
| `[conversion_name]: CPA` | Cost per action (spend ÷ conversions). | Currency | *Adriel-computed* |
| `[conversion_name]: Conversion value` | Conversion value for that goal. | Currency | *Per-event value* |
| `[conversion_name]: ROAS` | Return on ad spend for that goal (value ÷ spend). | Ratio | *Adriel-computed* |
### Video performance
| Metric | Description | Data type | API Key |
| ---------------------------------------------- | ------------------------------------------------------------------ | ---------- | -------------------------------------------- |
| Video impressions | Times video creatives started displaying. | Number | *Platform video field* |
| Views | Aggregated count of all qualified video views. | Number | `VIDEO_VIEWS` |
| Paid video views | Paid (billable) video views. | Number | `PAID_VIDEO_VIEWS` |
| Video play | Any play of the video, regardless of duration. | Number | *Platform video field* |
| 2s video plays | Views where the video played for at least two seconds. | Number | *Platform video field* |
| 3s video plays | Views of at least three continuous seconds. | Number | `VIDEO_VIEWS_TO_3_SEC` |
| 6s video plays | Six-second continuous video views. | Number | *Platform video field* |
| 15s video plays | Views lasting at least fifteen continuous seconds. | Number | *Platform video field* |
| 30s video plays | Views lasting 30 seconds or the entire video if shorter. | Number | *Platform video field* |
| ThruPlays | Video viewed to at least 97% or 15 seconds, whichever comes first. | Number | *Platform video field* |
| Video played to 25% / 50% / 75% / 100% (Views) | Plays reaching each completion threshold. | Number | `VIDEO_VIEWS_TO_25` / `_50` / `_75` / `_100` |
| Video played to 25% / 50% / 75% / 100% (%) | Each completion threshold as a rate over views. | Percentage | *Adriel-computed* |
| View rate | Video views divided by video impressions. | Percentage | *Adriel-computed* |
| CPV | Average cost for each counted video view (spend ÷ video views). | Currency | *Adriel-computed* |
| Average % video viewed | Average portion of the video watched. | Percentage | `AVG_PERCENT_VIDEO_VIEWED` |
| Average video duration viewed | Average time the video was watched. | Duration | `AVG_DURATION_VIDEO_VIEWED` |
### Viewability
Viewability metrics are specific to Display Ads. When the **Site** breakdown is active, `VIEWABLE_CLICK` and `MATERIAL_VIEWABLE_IMPS` are excluded from the results.
| Metric | Description | Data type | API Key |
| ----------------------------- | ----------------------------------------------------- | ---------- | ------------------------------ |
| Viewable impressions | Impressions that met the viewability criteria. | Number | `VIEWABLE_IMPS` |
| Measured impressions | Impressions measurable for viewability. | Number | `MEASURED_IMPS` |
| Viewable impression rate | Viewable impressions divided by measured impressions. | Percentage | `VIEWABLE_IMPS_RATE` |
| Measured impression rate | Measured impressions divided by total impressions. | Percentage | `MEASURED_IMPS_RATE` |
| Viewable clicks | Clicks on viewable impressions. | Number | `VIEWABLE_CLICKS` |
| Viewable click rate | Viewable clicks divided by viewable impressions. | Percentage | `VIEWABLE_CLICK_RATE` |
| Material viewable impressions | Viewable impressions of the ad material. | Number | `MATERIAL_VIEWABLE_IMPS` |
| Material viewable click rate | Viewable click rate for the ad material. | Percentage | `MATERIAL_VIEWABLE_CLICK_RATE` |
| Average vCPM | Average cost per thousand viewable impressions. | Currency | `AVG_VCPM` |
### Engagement
| Metric | Description | Data type | API Key |
| --------------- | ------------------------------------------------------------------- | --------- | --------------------------- |
| Engagement | Any user interaction with the ad (clicks, reactions, shares, etc.). | Number | *Platform engagement field* |
| Post engagement | Total engagements on the ad. | Number | *Platform engagement field* |
| Post reactions | Reactions on the ad. | Number | *Platform engagement field* |
| Post comments | Comments on the ad. | Number | *Platform engagement field* |
| Post shares | Shares of the ad. | Number | *Platform engagement field* |
| Post saves | Saves of the ad. | Number | *Platform engagement field* |
### Campaign structure & metadata
| Metric | Description | Data type | API Key |
| ----------------------- | --------------------------------------------- | --------- | --------------- |
| Ad account name | Name of the ad account. | Text | `accountName` |
| Campaign name | Campaign name. | Text | `campaignName` |
| Ad set name | Ad set (ad group) name. | Text | `adGroupName` |
| Ad name | Ad name. | Text | `adName` |
| Status | Campaign / ad set / ad status. | Text | *From platform* |
| Objective | Campaign objective. | Text | *From platform* |
| Channel | Channel (platform) where the ad is published. | Text | *From platform* |
| Creative type | Type of the ad creative. | Text | *From platform* |
| Creative URL | URL of the ad creative. | URL | *From platform* |
| Starts | Campaign / ad set start date. | Date | *From platform* |
| Ends | Campaign / ad set end date. | Date | *From platform* |
| Targeting type (Ad set) | Targeting type configured on the ad set. | Text | *From platform* |
The connector also exposes raw Yahoo Ads fields prefixed **"Yahoo Japan Ads:"** — including Title1–3, Description 1–2, Final URL, Display URL, Destination URL, Directory1–2, Tracking URL, Focus Device, Show ads on, Ad Type, Ad strength, Label, Custom parameter, and campaign / ad set / ad tracking IDs. Each maps to the platform field of the same name.
### UTM tracking
UTM values are parsed by Adriel, not returned by Yahoo. Adriel reads the UTM query parameters from each ad's configuration and landing URL and exposes them as metrics for rollup.
| Metric | Description | Data type | API Key |
| ------------ | -------------------------------- | --------- | ---------------------------------------------- |
| UTM Source | Parsed `utm_source` parameter. | Text | *Adriel-parsed from ad settings / 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` |
### Audience & geography
| Breakdown | Description | API Key |
| --------- | -------------------------------------------------------------- | ------------------- |
| Age | Group reports by audience age range. | `AGE` |
| Gender | Group reports by audience gender. | `GENDER` |
| Region | Split reports by prefecture. | `PREFECTURE` |
| Country | Split reports by impression location (two-digit country code). | `COUNTRY_TERRITORY` |
| Location | Split reports by impression location (city). | `CITY` |
### Device & placement
| Breakdown | Description | API Key |
| ------------- | -------------------------------------------------------------------- | ------------- |
| Device target | Split reports by device. | `DEVICE` |
| Site | Split reports by ad delivery URL (the site where the ad was served). | `DELIVER_URL` |
### Time & date grouping
Time and date breakdowns are Adriel-side aggregations of the same underlying daily data.
| Breakdown | Description |
| -------------------------- | ------------------------------------------------------------- |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily | Split reports by day (max 93 days). |
| Weekly (Start: Mon) | Split reports by week starting Monday (max 1 year). |
| Weekly (Start: Sun) | Split reports by week starting Sunday (max 1 year). |
| Week date breakdown | Group results 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 (max 2 years). |
| Quarterly | Split reports by calendar quarter. |
| Yearly | Split reports by calendar year. |
### Creative analysis
Adriel post-processes ad creatives to generate these breakdowns.
| Breakdown | Description |
| ---------------- | -------------------------------------------------------------------------------------- |
| Ad copy | Group ads that share the same ad copy. |
| Creative image | Group reports by image; Adriel clusters identical or visually similar images together. |
| Color Clustering | Group creative images by dominant visual color. |
| Emoji Analysis | Group ads by the emojis present in the ad copy. |
### UTM tracking
Yahoo does not return UTM values; Adriel parses them from each ad's configuration and landing URL and exposes them as breakdowns for grouping.
| 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`. |
### Overview & status
These grouping options are provided by Adriel for cross-connector consistency.
| Breakdown | Description |
| ----------- | ----------------------------------------------------------- |
| Channel | Constant grouping label used for cross-connector rollup. |
| Platform | Group results by the platform where the ads were broadcast. |
| No Grouping | Do not break down; return one aggregated row. |
| Objective | Group campaigns by their objectives. |
| Status | Group by campaign / ad set / ad status. |
## Limitations
* **Cache only** — report data comes from cached daily snapshots, not live queries. Uniqueness-based metrics (such as reach) can be overvalued over ranges longer than one day, and data outside the cache sync period may be incomplete or inaccurate.
* **No keyword reporting** — keyword-level reports and the keyword breakdown are not supported for Display Ads and return empty.
* **Site breakdown constraints** — the Site (ad delivery URL) breakdown cannot be combined with the ad level, and it drops the `VIEWABLE_CLICK` and `MATERIAL_VIEWABLE_IMPS` metrics.
* **Limited impression share** — only budget-loss and rank-loss impression share fields are available; exact-match, search-top, and absolute-top variants are not.
* **Date range caps** — daily 93 days, weekly 1 year, monthly 2 years.
## API references
* [Yahoo! JAPAN Ads Developers — Display Ads API](https://ads-developers.yahoo.co.jp/en/ads-api/)
## See also
* [How to connect Yahoo Japan Display Ads to Adriel](/data-sources/o-z/yahoo-japan-display-ads/how-to-connect) (paired how-to)
* [Yahoo Japan Search Ads data reference](/data-sources/o-z/yahoo-japan-search-ads/data-reference) — for the search-ads sibling connector