> ## 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 Yelp data source in Adriel.
## Introduction
Yelp is a local business listing and advertising platform. This connector pulls both organic engagement signals (page views, calls, directions, reviews, and ratings) from the Yelp business profile and paid advertising performance (impressions, clicks, ad cost, and ad-driven conversions) for any advertising programs associated with the connected businesses, using the Yelp Reporting API v3.
Reports are requested asynchronously, polled until ready, and then cached per asset and served from cache to the dashboard. Both business-level (organic) and program-level (advertising) metrics are available, and the metric set is automatically narrowed by the breakdown applied to a widget.
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 Yelp to Adriel](/data-sources/o-z/yelp/how-to-connect).
## Data refresh strategy
### Architecture data
Business listings and any associated advertising programs are discovered through the Yelp Fusion API at connection time and on subsequent refreshes. Newly added businesses become available after the next refresh cycle.
### Reports data
This is a simple-cache connector. For each collection, report data is fetched again on every refresh and the cache is replaced atomically, so the dashboard always reads from the cache rather than the live API. The default cadence is **every 6 hours, at 0 minutes past the hour (UTC)**. Each refresh requests a rolling 88-day report window.
## Architecture levels
Yelp account → Business (location) → Advertising program
## Date range limits
| Limit | Value |
| ---------------------------------- | ------- |
| Maximum query window | 89 days |
| Maximum fetched window per refresh | 88 days |
Date ranges that exceed the maximum query window are rejected at validation.
## 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 `num_total_page_views` is the literal Yelp Reporting API field name.
Metric availability depends on the breakdown applied to a widget. With no breakdown or a time breakdown (day, week, month), both business and advertiser metrics are available. A business-level breakdown exposes business metrics only, and a program breakdown exposes advertiser metrics only. See [Breakdowns](#breakdowns).
### Business metrics
Organic engagement on the Yelp business profile.
| Metric | Description | Data type | API Key |
| ----------------------------- | --------------------------------------------------------- | ---------- | ----------------------------------- |
| Total User Views | Total page views on desktop and mobile devices. | Number | `num_total_page_views` |
| Desktop User Views | Page views on desktop devices. | Number | `num_desktop_page_views` |
| Mobile User Views | Page views on mobile devices. | Number | `num_mobile_page_views` |
| Desktop Appearances In Search | Times the listing appeared in desktop search results. | Number | `num_desktop_search_appearances` |
| Mobile Appearances In Search | Times the listing appeared in mobile search results. | Number | `num_mobile_search_appearances` |
| Mobile Calls | Phone calls initiated from the business profile. | Number | `num_calls` |
| Calls Tracked | Calls tracked. | Number | `tracking_calls` |
| Directions & Map Views | Directions and map views from the profile. | Number | `num_directions_and_map_views` |
| Clicks To Website | Clicks to the business URL from the profile. | Number | `url_clicks` |
| Mobile Check-ins | Mobile check-ins from the profile. | Number | `num_check_ins` |
| User Uploaded Photos | User-generated photos added to the profile. | Number | `num_user_photos` |
| Yelp Bookmarks | Times the business was bookmarked by users. | Number | `num_bookmarks` |
| Desktop Call To Action Clicks | Call-to-Action clicks on desktop. | Number | `num_desktop_cta_clicks` |
| Mobile Call To Action Clicks | Call-to-Action clicks on mobile. | Number | `num_mobile_cta_clicks` |
| Request A Quote - Messages | Messages sent to the business, including Request a Quote. | Number | `num_messages_to_business` |
| Reply Rate | Percentage of messages replied to. | Percentage | `reply_rate` |
| Median Response Time (Secs) | Median time to answer messages. | Duration | `median_response_time_in_sec` |
| Deals Sold | Number of deals sold. | Number | `deals_sold` |
| Online Orders | Number of online orders. | Number | `online_orders` |
| Online Bookings | Number of online bookings. | Number | `online_bookings` |
| Check In Offer Redemptions | Users that redeemed a check-in offer. | Number | `check_in_offer_redemptions` |
| Collections | Times the business was added to a collection. | Number | `collection_item_added` |
| Ra PC Initiated | Times Request-a-Phone-Call was initiated. | Number | `rapc_initiated` |
| Waitlist Visit Created | Times someone joined the Yelp Waitlist. | Number | `waitlist_visit_created` |
| Organic Page Visits | Page views not driven by ads. | Number | `organic_biz_page_views` |
| % Biz Page Views Organic | Share of page views not driven by ads. | Percentage | `organic_biz_page_views_percentage` |
| Rating | Average rating (1-5 star scale). | Number | `rating` |
| Reviews | Count of unfiltered reviews of the listing. | Number | `reviews` |
| Total # Of Leads | Sum of all lead metrics. | Number | `total_leads` |
### Advertiser metrics
Paid advertising performance for programs associated with the business.
| Metric | Description | Data type | API Key |
| ------------------------------------- | ------------------------------------------------------------------------------ | ---------- | ------------------------------------- |
| Billed Ad Impressions | Billable ad displays. | Number | `billed_impressions` |
| Billed Ad Clicks | Billable ad clicks that reached the business page. | Number | `billed_clicks` |
| Billable Ad Impressions | Times the listing was displayed in an ad. | Number | `billable_ad_impressions` |
| Billable Ad Clicks | Times a search-ad click reached the business page. | Number | `billable_ad_clicks` |
| Ad Cost | Cost of ad when billed (reported in cents). | Currency | `ad_cost` |
| Ad Currency | Currency code reported with ad cost. | Text | `ad_currency` |
| Ad Click Through Rate | Ad click-through rate. | Percentage | `ad_click_through_rate` |
| Average Cost Per Click | Average cost per click across click-based campaigns. | Currency | `average_cost_per_click` |
| Ad Driven Page Visits | Page visits attributed to an ad (30-day click, 1-day impression). | Number | `ad_driven_biz_page_views` |
| % Biz Page Views Ad Driven | Share of page views driven by ads. | Percentage | `ad_driven_biz_page_views_percentage` |
| Ad Driven Mobile Calls | Click-to-call actions attributed to an ad. | Number | `ad_driven_calls` |
| Ad Driven Calls Tracked | Calls answered after seeing or clicking an ad (via Yelp Call Reporting). | Number | `ad_driven_calls_tracked` |
| Ad Driven Directions & Map Views | Directions and map views attributed to an ad. | Number | `ad_driven_directions_and_map_views` |
| Ad Driven Clicks To Website | Clicks to the business URL attributed to an ad. | Number | `ad_driven_url_clicks` |
| Ad Driven Total Call To Action Clicks | CTA clicks attributed to an ad. | Number | `ad_driven_cta_clicks` |
| Ad Driven Mobile Check-ins | Mobile check-ins attributed to an ad. | Number | `ad_driven_check_ins` |
| Ad Driven User Uploaded Photos | User-generated photos attributed to an ad. | Number | `ad_driven_user_photos` |
| Ad Driven Yelp Bookmarks | Bookmarks attributed to an ad. | Number | `ad_driven_bookmarks` |
| Ad Driven Request A Quote - Messages | Messages (including Request a Quote) attributed to an ad. | Number | `ad_driven_messages_to_business` |
| Ad Driven Online Reservations | Yelp Reservations and Nowait bookings attributed to an ad. | Number | `ad_driven_online_reservations` |
| Ad Driven Deals Sold | Deals sold attributed to an ad. | Number | `ad_driven_deals_sold` |
| Ad Driven Ra PC Initiated | Request-a-Phone-Call initiations attributed to an ad. | Number | `ad_driven_rapc_initiated` |
| Ad Driven Waitlist Visit Created | Yelp Waitlist sign-ups attributed to an ad. | Number | `ad_driven_waitlist_visit_created` |
| Ad Driven Platform Purchases | Third-party platform purchases (food, tickets, and so on) attributed to an ad. | Number | `ad_driven_platform_purchase_made` |
| Total # Of Ad Driven Leads | Sum of all ad-driven lead metrics. | Number | `ad_driven_total_leads` |
## Breakdowns
Metric availability follows the breakdown. Selecting a business breakdown (ID, alias, or name) hides advertiser metrics; selecting the program breakdown hides business metrics. With no breakdown or a time breakdown, both sets are available. This prevents nonsensical aggregations across organic and paid contexts.
### Business and program
| Breakdown | Description | API Key |
| --------------- | ------------------------------------------------ | --------------- |
| Business Name | Group by the business display name. | `businessName` |
| Business Alias | Group by the URL-friendly business alias (slug). | `businessAlias` |
| Business API ID | Group by the Yelp business identifier. | `businessId` |
| Program ID | Group by the advertising program identifier. | `programId` |
### Time grouping
Yelp returns daily records; Adriel groups them into these views for reporting.
| Breakdown | Description |
| ------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily | Split reports by day. |
| Weekly (Start: Mon) | Split reports by week, starting Monday. |
| Monthly | Split reports by calendar month. |
| Quarterly | Split reports by calendar quarter. |
| Yearly | Split reports by calendar year. |
### General
These groupings are provided by Adriel and are not tied to a Yelp API field.
| Breakdown | Description |
| --------------- | --------------------------------------------- |
| No Grouping | Do not break down; return one aggregated row. |
| Datasource Name | Group by the Adriel data source name. |
## Limitations
* **Metric availability follows the breakdown** — business and advertiser metrics cannot be combined under a business or program breakdown; use no breakdown or a time breakdown to see both sets together.
* **Ad cost reported in cents** — `ad_cost` is reported in cents at the source, with the currency provided separately by `ad_currency`. It is converted to major units only under the program breakdown; under a date breakdown the value remains in cents.
* **Single currency per data source** — the currency from the first advertising program encountered is applied to the data source; programs reporting a different currency are not tracked separately.
* **Business must have reviews** — a Yelp business with no reviews cannot be connected (a Yelp API requirement).
* **No deleted-data exclusion** — deleted or historical data is not filtered out separately by this connector.
## API references
* [Yelp Fusion API](https://docs.developer.yelp.com/docs/fusion-intro)
* [Yelp Fusion API reference](https://docs.developer.yelp.com/reference)
## See also
* [How to connect Yelp to Adriel](/data-sources/o-z/yelp/how-to-connect) (paired how-to)
* [Google Business Profile data reference](/data-sources/g-n/google-business-profile/data-reference) — for organic local business metrics