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

VersionStatusDescriptionTimeline
v1DeprecatedSuperseded by v2 in October 2017End of Support: June - 2023
Retirement: December 2023
v2DeprecatedSuperseded by v3 in December 2022End of Support: June - 2023
Retirement: December 2023
v3Current

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. On Yelp they are identified as "organic" metrics.

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 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.

๐Ÿ“˜

Check out our Reporting API Reference Page

:owlbert: Reporting API Endpoints

Revision History

Revision NumberDateEditorSummary
1.0Initial Version.
2.0October 11, 2017Cathy Chou1. 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.0December 2022Florian TraberRelease of Reporting API V3