Reporting API
This is a Yelp Partner API
Access is disabled by default. See Yelp Partner APIs on how to get access.
Migrating from v2?
Check out the Migration Guide
Overview
This API access is currently only available to Yelp advertising, listing management, & knowledge partners. Please inquire about becoming a partner on those pages if you'd like to access this API.
The Reporting API provides a means for Yelp partners to retrieve business metrics and CPC advertiser metrics for a specified set of businesses over a specified time range. Access to the Reporting API is reserved for contracted Yelp partners or direct Yelp advertisers that meet certain spend levels. Feature eligibility is subject to spend level, please reach out to your Yelp representative to learn more.
When a request is made for a report, a corresponding report ID will be returned. The report ID can then be used to retrieve data for the requested set of metrics across the requested set of businesses. A report usually takes 30 minutes to process.
Yelp metrics are batch processed once every 24 hours. Each analytics run captures one day of data (starting and ending at midnight PST). Business Metrics are usually complete by 1:00 PM PST the following day. Advertiser Metrics are usually complete by 10:00 AM PST the following day. Once metrics are available in Reporting API, they do not change.
The metrics available in the Reporting API are simply tracking the different types of actions a consumer can take on either the Yelp profile page or the advertising unit/copy. Reporting information like pixels, store visit attribution, or call tracking are not reflected today in the reporting API.
There may be more than a 24-hour lag between delivery and reporting (e.g. if an ad is delivered at 12:01AM on Monday and our analytics run completes at 10AM on Tuesday). The batch itself runs every day.
Authentication
The API uses your Yelp Fusion Api Key for authentication. See Fusion Authentication for details.
Your Yelp Fusion Client needs to be enabled for Reporting API. Please send your Client ID to [email protected].
Note: Reporting API requires separate set up from Data Ingestion or Ads API.
Versioning
To maintain backwards-compatibility with partner-developed applications, the Yelp Reporting API is versioned with the version encoded in the URI. The current and latest version is v3 and all endpoints are located at https://api.yelp.com/v3/reporting/.
Deprecation
| Version | Status | Description | Timeline |
|---|---|---|---|
| v1 | Deprecated | Superseded by v2 in October 2017 | End of Support: June - 2023 Retirement: December 2023 |
| v2 | Deprecated | Superseded by v3 in December 2022 | End of new access: June - 2023 Retirement: December 2024 |
| v3 | Current |
Identifiers
Yelp identifiers are unique within its own type; they are not globally unique. For example, a report and business may share the same identifier, WavvLdfdP6g8aZTtbBQHTw, but no other report or business will have that same identifier.
Value Types
All datetime properties should use the ISO 8601 format and be stored in UTC.
All time properties should use the format HH:MM[:SS] and be timezone-agnostic.
Yelp Business IDs
The Reporting API requires encrypted Business IDs to create reports. Please reference our Business Match API documentation on how to pull these values for Yelp listings. There is a maximum of 500 business ids per request.
Metrics
Below are the metrics available for reporting through this API. Examples for querying our API with these metrics are presented in the Endpoints section.
Business Metrics
Business Metrics count various kinds of interactions a user has with a business listing on Yelp. These counts are total metrics for the business_id, inclusive of organic plus ad-driven.
| Business Metric | Display Name | Description |
|---|---|---|
| num_total_page_views | Total User Views | Number of total page views on desktop and mobile devices. |
| num_calls | Mobile Calls | Number of phone calls initiated from the Yelp business profile. |
| num_directions_and_map_views | Directions & Map Views | Number of direction and map views from the Yelp business profile. |
| url_clicks | Clicks to Website | Number of clicks to the business URL from the Yelp business profile. |
| num_check_ins | Mobile Check-ins | Number of mobile check-ins from the Yelp business profile. |
| num_user_photos | User Uploaded Photos | Number of user generated photos added to the Yelp business profile. |
| num_bookmarks | Yelp Bookmarks | Number of times a business has been bookmarked by users. |
| num_desktop_cta_clicks | Desktop Call to Action Clicks | Number of Call-to-Action clicks on desktop devices. |
| num_mobile_cta_clicks | Mobile Call to Action Clicks | Number of Call-to-Action clicks on mobile devices. |
| num_messages_to_business | Request a Quote - messages | Number of messages sent to a business, including messages sent through Request a Quote. |
| num_desktop_search_appearances | Desktop Appearances in Search | Number of times a business listing appeared in search results on desktop devices. |
| num_mobile_search_appearances | Mobile Appearances in Search | Number of times a business listing appeared in search results on mobile devices. |
| num_desktop_page_views | Desktop User Views | Number of times the business page was accessed on desktop devices. |
| num_mobile_page_views | Mobile User Views | Number of times the business page was accessed on mobile devices. |
| tracking_calls | Calls Tracked | Number of calls tracked. |
| deals_sold | Deals Sold | Number of deals sold. |
| online_orders | Online Orders | Number of online orders. |
| online_bookings | Online Bookings | Number of online bookings. |
| check_in_offer_redemptions | Check In Offer Redemptions | The number of users that redeemed a check in offer for your listing (if applicable). |
| collection_item_added | Collections | The number of time your business was added to a collection other than the default bookmark collection. |
| rapc_initiated | RaPC Initiated | Number of times RaPC (request a phone call) was initiated. |
| waitlist_visit_created | Waitlist Visit Created | Number of times someone got in line on the Yelp Waitlist. |
| median_response_time_in_sec | Median response time (secs) | The median time it took for your business to answer messages. |
| reply_rate | Reply rate | The percentage of messages replied. |
| organic_biz_page_views | Organic Page Visits | The amount of organic page views of your listing, which were not occurring as a consequence of ad clicks and ad impressions. |
| organic_biz_page_views_percentage | % Biz Page Views Organic | It measures which percentage of biz page views didn't derive from ads. |
| rating | Rating | Average Rating (1-5 star scale). |
| reviews | Reviews | The number of unfiltered reviews of your listing. |
| total_leads | Total # of leads | Total # of leads (sums all Leads metrics). |
Advertiser Metrics
Advertiser Metrics report campaign related metrics. These include metrics like number of ad clicks or impressions but also various kinds of interactions a user has with a business listing which can be attributed to an ad impression. On Yelp they are identified as "ads" metrics.
| Advertiser Metric | Display Name | Description |
|---|---|---|
| billed_impressions | Billed Ad Impressions | Number of times an Ad is displayed and will be billed. |
| billed_clicks | Billed Ad Clicks | Number of times a user clicked on an advertisement for the business and visited its business page. |
| ad_cost | Ad Cost | Cost of Ad when billed (in cents). |
| ad_driven_bookmarks | Ad Driven Yelp Bookmarks | Number of times a business has been bookmarked by users that can be attributed to an Ad impression. |
| ad_driven_calls | Ad Driven Mobile Calls | Number of phone calls initiated from the Yelp business profile that can be attributed to an Ad impression. |
| ad_driven_cta_clicks | Ad Driven Total Call to Action Clicks | Number of Call-to-Action clicks on desktop devices that can be attributed to an Ad impression. |
| ad_driven_check_ins | Ad Driven Mobile Check-ins | Number of mobile check-ins from the Yelp business profile that can be attributed to an Ad impression. |
| ad_driven_deals_sold | Ad Driven Deals Sold | Number of deals sold that can be attributed to an Ad impression. |
| ad_driven_directions_and_map_views | Ad Driven Directions & Map Views | Number of direction and map views from the Yelp business profile that can be attributed to an Ad impression. |
| ad_driven_messages_to_business | Ad Driven Request a Quote - messages | Number of messages sent to a business, including messages sent through Request a Quote that can be attributed to an Ad impression |
| ad_driven_user_photos | Ad Driven User Uploaded Photos | Number of user generated photos added to the Yelp business profile that can be attributed to an Ad impression. |
| ad_driven_online_reservations | Ad Driven Online Reservations | Number of Yelp Reservations and Yelp Nowait bookings through Yelp that can be attributed to an Ad impression. |
| ad_driven_url_clicks | Ad Driven Clicks to Website | Number of clicks to the business URL from the Yelp business profile that can be attributed to an Ad impression. |
| ad_click_through_rate | Ad Click Through Rate | Ad CTR measures how well Yelp performs at getting users to click on your ads. |
| average_cost_per_click | Average Cost Per Click | This metric measures, on average, the amount of cost per clicks that Yelp attributed to your Yelp business page for all clicks-based ad campaigns (if applicable). |
| billable_ad_clicks | Billable Ad Clicks | The number of times a user clicked on a search advertisement for your listing and came to its Yelp business page across all platforms. |
| billable_ad_impressions | Billable Ad Impressions | The number of times your listing was displayed in an advertisement. |
| ad_driven_biz_page_views | Ad Driven Page Visits | Ad Driven Yelp page visits is a measure of how many times your Yelp page was accessed or viewed on the Yelp website, mobile website, and mobile apps after seeing or clicking on an ad. This amount of pages visits is calculated using our 30 days attribution logic for ad clicks and 1 day for ad impressions. |
| ad_driven_calls_tracked | Ad Driven Calls Tracked | The number of calls made by Yelp users after seeing or clicking on your ad which were successfully answered by your business, when you're using Yelp's Call Reporting feature. |
| ad_driven_rapc_initiated | Ad Driven RaPC Initiated | Number of times RaPC was initiated. |
| ad_driven_waitlist_visit_created | Ad Driven Waitlist Visit Created | Number of times someone got in line on the Yelp Waitlist after seeing or clicking an ad. |
| ad_driven_total_leads | Total # of ad driven leads | Total # of ad driven leads (sums all AdDrivenLeads metrics). |
| ad_driven_platform_purchase_made | Ad Driven Platform Purchases | Number of platform purchases that were to be fulfilled by third parties (GrubHub for food ordering, GoldStar for tickets etc.) and are attributed to an ad. |
| ad_driven_biz_page_views_percentage | % Biz Page Views Ad Driven | It measures which percentage of biz page views derived from ads. |
Endpoints
Overview
| HTTP Method | Resource | Description |
|---|---|---|
| POST | reporting/businesses/daily | Request a report containing daily business/advertiser metrics for a specified list of businesses over a date range. Daily metrics can be requested up to 89 days ago. |
| POST | reporting/businesses/monthly | Request a report containing monthly business/advertiser metrics for a specified list of businesses over a specified month range. Monthly metrics can be requested up to 2 months ago. |
| GET | reporting/businesses/daily/{report_id} | Fetch the daily report associated with {report_id}. |
| GET | reporting/businesses/monthly/{report_id} | Fetch the monthly report associated with {report_id}. |
Details
The detailed description of the endpoints has moved into the API Reference section. Please see there for detailed description, request and response schemas and examples.
Click on any of the following Endpoints to view the API Reference section.
docs.developer.yelp.comCheck out our Reporting API Reference Page
Revision History
| Revision Number | Date | Editor | Summary |
|---|---|---|---|
| 1.0 | Initial Version. | ||
| 2.0 | October 11, 2017 | Cathy Chou | 1. Added 'Revision History' section 2. Added Descriptions to Business Metrics 3.Revised Business Metrics nomenclature: num_total_page_views, num_user_photos, num_desktop_page_views 4.Minor style fixes |
| 3.0 | December 2022 | Florian Traber | Release of Reporting API V3 |
Updated about 1 month ago