Reporting API

Overview

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.

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

Authentication

The API uses basic authentication over HTTPS. Credentials are provided separately.

Note: Reporting API requires separate credentials from Data Ingestion or Reseller API. Please send your GPG key to [email protected]. More info about GPG keys here: https://kb.iu.edu/d/awio.

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 v2 and all endpoints are located at https://partner-api.yelp.com/analytics/v2/.

Format

Response bodies use the application/json content type and should be encoded in UTF-8.

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 Metric Display Name Value Description
num_total_page_views Total User Views String Number of total page views on desktop and mobile devices.
num_calls Mobile Calls String Number of phone calls initiated from the Yelp business profile.
num_directions_and_map_views Directions & Map Views String Number of direction and map views from the Yelp business profile.
url_clicks Clicks to Website String Number of clicks to the business URL from the Yelp business profile.
num_check_ins Mobile Check-ins String Number of mobile check-ins from the Yelp business profile.
num_user_photos User Uploaded Photos String Number of user generated photos added to the Yelp business profile.
num_bookmarks Yelp Bookmarks String Number of times a business has been bookmarked by users.
num_desktop_cta_clicks Desktop Call to Action Clicks String Number of Call-to-Action clicks on desktop devices.
num_mobile_cta_clicks Mobile Call to Action Clicks String Number of Call-to-Action clicks on mobile devices.
num_messages_to_business Request a Quote - messages String Number of messages sent to a business, including messages sent through Request a Quote.
num_mobile_page_views Mobile User Views String Number of page views on mobile devices.
num_desktop_search_appearances Desktop Appearances in Search String Number of times a business appeared in search on desktop devices.
num_mobile_search_appearances Mobile Appearances in Search String Number of times a business appeared in search on mobile devices.
num_desktop_page_views Desktop User Views String Number of page views on desktop devices.
tracking_calls Calls Tracked String Number of calls tracked.
deals_sold Deals Sold String Number of deals sold.
online_orders Online Orders String Number of online orders.
online_bookings Online Bookings String Number of online bookings

Advertiser Metrics

Advertiser Metric Display Name Value Description
billed_impressions Billed Ad Impressions String Number of times Ad is displayed and will be billed.
billed_clicks Billed Ad Clicks String Number of clicks from a billed impression.
ad_cost Ad Cost String Cost of Ad when billed (in cents).
ad_driven_bookmarks AD DRIVEN Yelp Bookmarks String 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 String 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 String 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 String 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 String Number of deals sold that can be attributed to an Ad impression.
ad_driven_directions_and_map_views AD DRIVEN Directions & Map Views String 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 String 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 String 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 String 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 String Number of clicks to the business URL from the Yelp business profile that can be attributed to an Ad impression.

Endpoints

Overview

HTTP Method Resource Description
POST businesses/daily_reports 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 businesses/monthly_reports 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 businesses/daily_reports/{report_id} Fetch the daily report associated with {report_id}.
GET businesses/monthly_reports/{report_id} Fetch the monthly report associated with {report_id}.

Daily Reports

POST

https://partner-api.yelp.com/analytics/v2/businesses/daily_reports

Body Format:

{
  "start": "{YYYY-MM-DD}",
  "end": "{YYYY-MM-DD}",
  "metrics": [
    "{Business Metric}", 
    "{Advertiser Metric}",
    ...
  ],
  "ids": [
    "{Business Identifier}",
    ...,
  ]
}

Response Format:

{
  "id": "{report_id}"
}

Example Request:

curl \
  -X POST \
  -H "Content-type: application/json" \
  -d '{"ids": ["IAlDtL3mIEK5vAokXv6K_Q", "sqsTqzJPLEO9ZMtOC2BdFw", "Kob8joi91eloBspEXFKhEw"], "metrics": ["num_total_page_views", "billed_impressions","num_desktop_page_views"], "start": "2017-07-01", "end": "2017-07-02"}' \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/analytics/v2/businesses/daily_reports

Example Response:

{
  "id": "312kf55a-ea3c-4aee-121J-98a124d56abc"
}

GET

https://partner-api.yelp.com/analytics/v2/businesses/daily_reports/{report_id}

Request params:

report_id A report identifier returned from the daily reports POST endpoint.

Response Format:

{
  "errors": {
    "inactive_ids": ["{Business Identifier}", ...],
    "unauthorized_ids": ["{Business Identifier}", ...]
  },
  "data": [
    "metrics": [
      {
        "programs": [
          {
            "billed_impressions": {int},
            "billed_clicks": {int},
            "ad_cost": {
              "currency": "{ISO 4217 Currency Code}",
              "cost": {int}
            },
            "program_type": "{string}",
            "program_id": "{Program Identifier}"
          },
          ...
        ]
        "date": "{YYYY-MM-DD}",
        "{Business Metric}": {int},
        ...
        "{Business Metric}": {int},
      },
      ...
    ]
  ]
}

Example Request:

curl \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/analytics/v2/businesses/daily_reports/312kf55a-ea3c-4aee-121J-98a124d56abc

Example Response

{
  "errors": {
    "inactive_ids": ["sqsTqzJPLEO9ZMtOC2BdFw"],
    "unauthorized_ids": ["Kob8joi91eloBspEXFKhEw"]
  },
  "data": [
    {
      "metrics": [
        {
          "programs": [
            {
              "billed_impressions": 10,
              "program_id": "Yz5k8ez5_keJV0AyzkePbD",
              "program_type": "cpc"
            }
          ],
          "num_desktop_page_views": 100,
          "date": "2017-07-02",
          "num_total_page_views": 173
        },
        {
          "programs": [
            {
              "billed_impressions": 5,
              "program_id": "Yz5k8ez5_keJV0AyzkePbD",
              "program_type": "cpc"
            }
          ],
          "num_desktop_page_views": 96,
          "date": "2017-07-01",
          "num_total_page_views": 121
        }
      ],
      "business_id": "IAlDtL3mIEK5vAokXv6K_Q"
    }
  ],
  "report_id": "312kf55a-ea3c-4aee-121J-98a124d56abc"
}

Monthly Reports

POST

https://partner-api.yelp.com/analytics/v2/businesses/monthly_reports

Body Format:

{
  "start": "{YYYY-MM}",
  "end": "{YYYY-MM}",
  "metrics": [
    "{Business Metric}", 
    "{Advertiser Metric}",
    ...
  ],
  "ids": [
    "{Business Identifier}",
    ...,
  ]
}

Response Format:

{
  "id": "{report_id}"
}

Example Request:

curl \
  -X POST \
  -H "Content-type: application/json" \
  -d '{"ids": ["IAlDtL3mIEK5vAokXv6K_Q", "sqsTqzJPLEO9ZMtOC2BdFw", "Kob8joi91eloBspEXFKhEw"], "metrics": ["num_total_page_views", "billed_impressions","num_desktop_page_views"], "start": "2017-07", "end": "2017-07"}' \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/analytics/v2/businesses/monthly

Example Response:

{
  "id": "18837jke-007e-3a47-6f14-d0d12d9911g"
}

GET

https://partner-api.yelp.com/analytics/v2/businesses/monthly_reports/{report_id}

Request Params:

report_id A report identifier returned from the monthly reports POST endpoint.

Response Format:

{
  "errors": {
    "inactive_ids": ["{Business Identifier}", ...],
    "unauthorized_ids": ["{Business Identifier}", ...]
  },
  "data": [
    "metrics": [
      {
        "programs": [
          {
            "billed_impressions": {int},
            "billed_clicks": {int},
            "ad_cost": {
              "currency": "{ISO 4217 Currency Code}",
              "cost": {int}
            },
            "program_type": "{string}",
            "program_id": "{Program Identifier}"
          },
          ...
        ]
        "date": "{YYYY-MM}",
        "{Business Metric}": {int},
        ...
        "{Business Metric}": {int},
      },
      ...
    ]
  ]
}

Example Request:

curl \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/analytics/v2/businesses/monthly_reports/18837jke-007e-3a47-6f14-d0d12d9911g

Example Response

{
  "errors": {
    "inactive_ids": ["sqsTqzJPLEO9ZMtOC2BdFw"],
    "unauthorized_ids": ["Kob8joi91eloBspEXFKhEw"]
  },
  "data": [
    {
      "metrics": [
        {
          "programs": [
            {
              "billed_impressions": 120,
              "program_id": "xmvb76ClY5Zmqhp0FGZcuw",
              "program_type": "cpc"
            },
            {
              "billed_impressions": 5,
              "program_id": "QPAu0c4SYovgPYkViddDgQ",
              "program_type": "cpc"
            },
            {
              "billed_impressions": 190,
              "program_id": "Vy6d6xz5_jfTV9QQzKeBdQ",
              "program_type": "cpc"
            },
            {
              "billed_impressions": 99,
              "program_id": "mkWXvFGlO5Rpihxh3tWmHQ",
              "program_type": "cpc"
            }
          ],
          "num_desktop_page_views": 5200,
          "date": "2017-07",
          "num_total_page_views": 9001
        }
      ],
      "business_id": "IAlDtL3mIEK5vAokXv6K_Q"
    }
  ],
  "report_id": "18837jke-007e-3a47-6f14-d0d12d9911g"
}

Error Response

The following error codes will be returned by the API:

Error Code Message
202 Job Not Complete
400 Varies depending on failure scenario
401 Authentication Error
403 Authorization Error
404 Resource Not Found
413 The number of businesses in the request exceeded the maximum {max_allowed_businesses}
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable

Example Error Response 1:

This is a sample response when the API is unavailable and hence the request failed.

{
  "code": 500,
  "message": "Internal Server Error",
  "more_info": None 
}

Example Error response 2:

This is a sample response when the requested ID is still being processed.

{
  "code": 202,
  "message": "Job Not Complete",
}

πŸ“˜

Check out our Reporting API Reference Page

:owlbert: Reporting API Endpoints


Did this page help you?