--- agentTools: projectIndex: https://docs.developer.yelp.com/llms.txt --- # Request Monthly Report Requests a report containing monthly business/advertiser metrics for a specified list of businesses over a date range. The start month can be up to 730 days (2 years) ago, and the date range cannot exceed 3 months. Use [get_monthly_reports_v3](https://docs.developer.yelp.com/reference/get_monthly_reports_v3) to poll for report completion and retrieve the report. [block:callout] { "type": "info", "body": "This endpoint is part of the Reporting API, visit [Reporting API](https://docs.developer.yelp.com/docs/reporting-api) to learn more." } [/block] # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Reporting API V3", "version": "1.0" }, "servers": [ { "url": "https://api.yelp.com/v3/reporting/" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "To authenticate API calls with the API Key, set the Authorization HTTP header value as `Bearer API_KEY`.\n\nExample: `Bearer 23813239889e947efd3e787cc41b0b839f442a85c5bfd30bd4b9a85ec3a54d5cae4d52b37ff52e64deb9c83bd04883812a6cebde04f2f25752f31be0ac74b514`.\n\nYou can create or find your API Key at [yelp.com](https://www.yelp.com/developers/v3/manage_app).\n" } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/businesses/daily": { "post": { "summary": "Request Daily Report", "tags": [ "Daily Reports" ], "description": "Requests a report containing daily business/advertiser metrics for a specified list of businesses over a date range. The start date can be up to 730 days (2 years) ago, and the date range (end minus start) cannot exceed 89 days.\n\nUse [get_daily_reports_v3](https://docs.developer.yelp.com/reference/get_daily_reports_v3) to poll for report completion and retrieve the report.\n", "operationId": "create_daily_reports_v3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start": { "type": "string", "format": "date", "description": "Start date. (Format `YYYY-MM-dd`)" }, "end": { "type": "string", "format": "date", "description": "End date. (Format `YYYY-MM-dd`)" }, "ids": { "description": "A list of Yelp Business IDs", "type": "array", "items": { "type": "string", "description": "Yelp Encrypted Business ID." } }, "metrics": { "description": "Business and Advertising Metrics to be included in report.\n See [Business Metrics](https://docs.developer.yelp.com/docs/reporting-api#business-metrics) and [Advertiser Metrics](https://docs.developer.yelp.com/docs/reporting-api#advertiser-metrics) for a detailed description of all available metrics.\n", "type": "array", "items": { "description": "Business and Advertising Metric name.", "type": "string", "enum": [ "num_total_page_views", "num_calls", "num_directions_and_map_views", "url_clicks", "num_check_ins", "num_user_photos", "num_bookmarks", "num_desktop_cta_clicks", "num_mobile_cta_clicks", "num_messages_to_business", "num_mobile_page_views", "num_desktop_search_appearances", "num_mobile_search_appearances", "num_desktop_page_views", "tracking_calls", "deals_sold", "online_orders", "online_bookings", "check_in_offer_redemptions", "collection_item_added", "rapc_initiated", "waitlist_visit_created", "median_response_time_in_sec", "reply_rate", "organic_biz_page_views", "organic_biz_page_views_percentage", "rating", "reviews", "total_leads", "billed_impressions", "billed_clicks", "ad_cost", "ad_driven_bookmarks", "ad_driven_calls", "ad_driven_cta_clicks", "ad_driven_check_ins", "ad_driven_deals_sold", "ad_driven_directions_and_map_views", "ad_driven_messages_to_business", "ad_driven_user_photos", "ad_driven_online_reservations", "ad_driven_url_clicks", "ad_click_through_rate", "average_cost_per_click", "billable_ad_clicks", "billable_ad_impressions", "ad_driven_biz_page_views", "ad_driven_calls_tracked", "ad_driven_rapc_initiated", "ad_driven_waitlist_visit_created", "ad_driven_total_leads", "ad_driven_platform_purchase_made", "ad_driven_biz_page_views_percentage" ] } } }, "required": [ "start", "end", "ids", "metrics" ] }, "example": { "value": { "start": "2020-01-01", "end": "2020-02-28", "ids": [ "w-WAiKJe__oZV13M34pTFw", "ThncHZzfDNaNYYMXk88hLQ" ], "metrics": [ "billed_clicks", "billed_impressions", "ad_cost", "num_calls", "num_total_page_views", "num_directions_and_map_views" ] } } } } }, "responses": { "202": { "description": "202 - Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID of the report.", "type": "string" } }, "required": [ "id" ] }, "examples": { "Report created successfully": { "value": { "id": "f046a18a-4192-4600-b2df-52633e8f5" } } } } } }, "400": { "description": "Bad Request. Message varies depending on failure scenario\n\n| code | description |\n| ------------- | ------------- |\n| VALIDATION_ERROR | Validation Error. |\n| INVALID_REQUEST | Invalid Request. |\n| MAX_NUM_OF_DAILY_LOOKBACK_ERROR | The number of days to look up daily business metrics exceeded the maximum (730). Please use a start date less than 730 days from now |\n| MAX_NUM_OF_DAILY_RANGE_ERROR | The date range for daily business metrics exceeded the maximum (89 days). Please use a date range of less than 89 days |\n| END_DATE_EARLIER_THAN_START_DATE | The start date has to be earlier or equal to the end date. |\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "description": "The error code, something like `VALIDATION_ERROR` or `INVALID_REQUEST`", "type": "string" }, "description": { "description": "The error description, some error codes may have multiple description describing in detail what went wrong.", "type": "string" }, "field": { "description": "In case of VALIDATION_ERROR's this field may be present and may contain the field that failed validation.", "type": "string", "x-nullable": true }, "instance": { "description": "In case of VALIDATION_ERROR's this field may be present and may contain the instance that failed validation.", "type": "string", "x-nullable": true } } } } }, "examples": { "INVALID_REQUEST": { "value": { "error": { "code": "INVALID_REQUEST", "description": "Invalid Request" } } }, "MAX_NUM_OF_DAILY_LOOKBACK_ERROR": { "value": { "error": { "code": "MAX_NUM_OF_DAILY_LOOKBACK_ERROR", "description": "The number of days to look up daily business metrics exceeded the maximum (730). Please use a start date less than 730 days from now" } } }, "MAX_NUM_OF_DAILY_RANGE_ERROR": { "value": { "error": { "code": "MAX_NUM_OF_DAILY_RANGE_ERROR", "description": "The date range for daily business metrics exceeded the maximum (89 days). Please use a date range of less than 89 days" } } }, "END_DATE_EARLIER_THAN_START_DATE": { "value": { "error": { "code": "END_DATE_EARLIER_THAN_START_DATE", "description": "The start date has to be earlier or equal to the end date." } } } } } } }, "401": { "description": "The API key has either expired or doesn't have the required scopes to query this endpoint.\n\n| code | description |\n| ------------- | ------------- |\n| UNAUTHORIZED_API_KEY | The API key provided is not currently able to query this endpoint. |\n| TOKEN_INVALID | Invalid API key or authorization header. |\n", "content": { "application/json": { "examples": { "Unauthorized": { "value": { "error": { "code": "UNAUTHORIZED_API_KEY", "description": "The API key provided is not currently able to query this endpoint." } } }, "Invalid Token": { "value": { "error": { "code": "TOKEN_INVALID", "description": "Invalid API key or authorization header." } } } }, "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "type": "string", "description": "The error code." }, "description": { "type": "string", "description": "The description of the error." } } } } } } } }, "403": { "description": "Partner API endpoints require set up by Yelp before they can be used. You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1businesses~1daily/post/responses/401/content/application~1json/schema" }, "examples": { "Endpoint Disabled": { "value": { "error": { "code": "PARTNER_ENDPOINT_DISABLED", "description": "You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information." } } } } } } }, "413": { "description": "The number of businesses in the request exceeded the maximum (500)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "description": "The error code, something like `VALIDATION_ERROR` or `INVALID_REQUEST`", "type": "string" }, "description": { "description": "The error description, some error codes may have multiple description describing in detail what went wrong.", "type": "string" } } } } }, "examples": { "NUMBER_OF_BUSINESS_LIMIT_ERROR": { "value": { "error": { "code": "NUMBER_OF_BUSINESS_LIMIT_ERROR", "description": "The number of businesses in the request exceeded the maximum (500)" } } } } } } }, "429": { "description": "You have either exceeded your daily quota, or have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "error": { "code": "TOO_MANY_REQUESTS_PER_SECOND", "description": "You have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries." } } } }, "schema": { "$ref": "#/paths/~1businesses~1daily/post/responses/401/content/application~1json/schema" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "examples": { "Internal Server Error": { "value": { "error": { "code": "INTERNAL_ERROR", "description": "Something went wrong internally, please try again later." } } } }, "schema": { "$ref": "#/paths/~1businesses~1daily/post/responses/401/content/application~1json/schema" } } } } } } }, "/businesses/monthly": { "post": { "summary": "Request Monthly Report", "tags": [ "Monthly Reports" ], "description": "Requests a report containing monthly business/advertiser metrics for a specified list of businesses over a date range. The start month can be up to 730 days (2 years) ago, and the date range cannot exceed 3 months.\n\nUse [get_monthly_reports_v3](https://docs.developer.yelp.com/reference/get_monthly_reports_v3) to poll for report completion and retrieve the report.\n", "operationId": "create_monthly_reports_v3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start": { "type": "string", "pattern": "\\d{4}-\\d{2}", "description": "Start month. (Format `YYYY-MM`)" }, "end": { "type": "string", "pattern": "\\d{4}-\\d{2}", "description": "End month. (Format `YYYY-MM`)" }, "ids": { "$ref": "#/paths/~1businesses~1daily/post/requestBody/content/application~1json/schema/properties/ids" }, "metrics": { "$ref": "#/paths/~1businesses~1daily/post/requestBody/content/application~1json/schema/properties/metrics" } }, "required": [ "start", "end", "ids", "metrics" ] }, "example": { "value": { "start": "2020-01", "end": "2020-02", "ids": [ "w-WAiKJe__oZV13M34pTFw", "ThncHZzfDNaNYYMXk88hLQ" ], "metrics": [ "billed_clicks", "billed_impressions", "ad_cost", "num_calls", "num_total_page_views", "num_directions_and_map_views" ] } } } } }, "responses": { "202": { "description": "202 - Accepted", "content": { "application/json": { "schema": { "$ref": "#/paths/~1businesses~1daily/post/responses/202/content/application~1json/schema" }, "examples": { "Report created successfully": { "value": { "id": "f046a18a-4192-4600-b2df-52633e8f5" } } } } } }, "400": { "description": "Bad Request. Message varies depending on failure scenario\n\n| code | description |\n| ------------- | ------------- |\n| VALIDATION_ERROR | Validation Error. |\n| INVALID_REQUEST | Invalid Request. |\n| MAX_NUM_OF_DAILY_LOOKBACK_ERROR | The number of days to look up monthly business metrics exceeded the maximum (730). Please use a start date less than 730 days from now |\n| MAX_NUM_OF_MONTHS_RANGE_ERROR | The date range for monthly business metrics exceeded the maximum (3 months). Please use a date range of less than 3 months |\n| END_DATE_EARLIER_THAN_START_DATE | The start date has to be earlier or equal to the end date. |\n", "content": { "application/json": { "schema": { "$ref": "#/paths/~1businesses~1daily/post/responses/400/content/application~1json/schema" }, "examples": { "INVALID_REQUEST": { "value": { "error": { "code": "INVALID_REQUEST", "description": "Invalid Request" } } }, "MAX_NUM_OF_DAILY_LOOKBACK_ERROR": { "value": { "error": { "code": "MAX_NUM_OF_DAILY_LOOKBACK_ERROR", "description": "The number of days to look up monthly business metrics exceeded the maximum (730). Please use a start date less than 730 days from now" } } }, "MAX_NUM_OF_MONTHS_RANGE_ERROR": { "value": { "error": { "code": "MAX_NUM_OF_MONTHS_RANGE_ERROR", "description": "The date range for monthly business metrics exceeded the maximum (3 months). Please use a date range of less than 3 months" } } }, "END_DATE_EARLIER_THAN_START_DATE": { "value": { "error": { "code": "END_DATE_EARLIER_THAN_START_DATE", "description": "The start date has to be earlier or equal to the end date." } } } } } } }, "401": { "$ref": "#/paths/~1businesses~1daily/post/responses/401" }, "403": { "$ref": "#/paths/~1businesses~1daily/post/responses/403" }, "413": { "$ref": "#/paths/~1businesses~1daily/post/responses/413" }, "429": { "$ref": "#/paths/~1businesses~1daily/post/responses/429" }, "500": { "$ref": "#/paths/~1businesses~1daily/post/responses/500" } } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": false, "samples-enabled": true }, "_id": { "buffer": { "0": 99, "1": 54, "2": 230, "3": 71, "4": 95, "5": 26, "6": 132, "7": 0, "8": 29, "9": 86, "10": 152, "11": 234 } } } ```