# Facebook Reviews Scraper (`crawlerbros/facebook-reviews-scraper`) Actor Scrape public Facebook business page reviews by URL, business name search, or Page ID. Filters by date range, keyword, recommendation status, and sort order - **URL**: https://apify.com/crawlerbros/facebook-reviews-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Social media, Developer tools, Automation - **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 8 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Facebook Reviews Scraper Scrape public Facebook business page reviews by direct URL, business name search, or Facebook Page ID. Returns full review data including author details, recommendation status, photos, reaction counts, and page-level aggregate statistics. ### What This Actor Does - Scrape reviews from any **public Facebook business page** — restaurants, hotels, retailers, services - Three input modes: paste a `/reviews` URL, search by business name + city, or supply a numeric Page ID - **Filter results** by date range, recommendation status (Recommended / Not Recommended), or keyword in review text - Choose sort order: **Most Recent** or **Most Helpful** - Extracts **review photos**, **top comments**, author review count, and page aggregate stats - Handles Facebook's bot detection using Playwright stealth + Apify residential proxy ### Input | Field | Description | Default | |-------|-------------|---------| | `mode` | `url` / `search` / `pageId` | `url` | | `startUrls` | Direct `/reviews` page URLs | — | | `searchQueries` | Business name + location (e.g. `"Starbucks Dallas TX"`) | — | | `pageIds` | Numeric Facebook Page IDs | — | | `maxReviews` | Max reviews per page (1–500) | 100 | | `sortBy` | `most_recent` or `most_helpful` | `most_recent` | | `filterByRecommendation` | `all` / `recommended` / `not_recommended` | `all` | | `filterByDateFrom` | Only reviews on or after this date (`YYYY-MM-DD`) | — | | `filterByDateTo` | Only reviews on or before this date (`YYYY-MM-DD`) | — | | `filterByKeyword` | Only reviews containing this word/phrase | — | ### Output One record per review. Fields only present when data is available. | Field | Example | |-------|---------| | `reviewId` | `"UzpfSTEwMDAy..."` | | `text` | `"Amazing food and great service!"` | | `isRecommended` | `true` | | `createdAt` | `"2024-03-15T10:22:00+00:00"` | | `authorName` | `"Julia Odan"` | | `authorReviewCount` | `14` | | `reactionCount` | `3` | | `reviewPhotos` | `["https://scontent.fbcdn.net/..."]` | | `topComments` | `[{"authorName": "Bob", "text": "Agree!"}]` | | `page.name` | `"McDonald's"` | | `page.totalReviewCount` | `4821` | | `page.recommendationPercentage` | `87` | ### FAQ **Does this require a Facebook account or cookies?** No. The actor scrapes publicly visible reviews on public business pages without login. **Why does Facebook use Recommended/Not Recommended instead of star ratings?** Facebook changed its review system to a binary recommendation model in 2018. There are no 1–5 star ratings. **How many reviews can I get per page?** Up to 500 reviews per page. Facebook's pagination becomes unreliable beyond this volume. **Why is a residential proxy required?** Facebook aggressively detects and blocks datacenter IP addresses. Residential proxies provide real-user IP addresses that avoid detection. This is handled automatically by the actor using Apify's proxy infrastructure. **Will search mode always find the right business?** For common business names (e.g. "McDonald's"), the top result is usually correct. For precision, use `url` or `pageId` mode. **What if a page has no reviews?** An error record is pushed with `"recordType": "error"` and a description. No crash. **Are review photo URLs permanent?** Facebook CDN URLs expire after some time. Use the `scrapedAt` timestamp to track freshness. ### Limitations - **500 review cap per page** — scraping beyond 500 is unreliable and costly - **Public pages only** — private groups, user profiles, and Marketplace are not supported - **Sort selector targets English UI** — `most_helpful` sort may not work on non-English Facebook interfaces - **Search mode is best-effort** — ambiguous queries may return incorrect page matches # Actor input Schema ## `mode` (type: `string`): How to specify which Facebook page to scrape reviews from. ## `startUrls` (type: `array`): Links to Facebook page review sections (e.g. https://www.facebook.com/mcdonalds/reviews). Used when mode is 'Direct URL'. ## `searchQueries` (type: `array`): Business name and location to search on Facebook (e.g. 'Starbucks Dallas TX'). Used when mode is 'Business Name Search'. ## `pageIds` (type: `array`): Numeric Facebook Page IDs (e.g. '123456789'). Used when mode is 'Facebook Page ID'. ## `maxReviews` (type: `integer`): Maximum total reviews to scrape across all input pages (1–500). Collection stops once this global cap is reached. ## `maxReviewsPerPage` (type: `integer`): Maximum reviews to scrape from each individual Facebook page (1–500). Useful when scraping multiple URLs to get an even spread of reviews per page. ## `sortBy` (type: `string`): Order in which to load reviews from the page. ## `filterByRecommendation` (type: `string`): Only return reviews with the selected recommendation status. Facebook uses binary Recommended/Not Recommended (no star ratings). ## `filterByDateFrom` (type: `string`): Only return reviews posted on or after this date. Format: YYYY-MM-DD (e.g. 2024-01-01). ## `filterByDateTo` (type: `string`): Only return reviews posted on or before this date. Format: YYYY-MM-DD (e.g. 2024-12-31). ## `filterByKeyword` (type: `string`): Only return reviews containing this word or phrase (case-insensitive). ## `cookies` (type: `array`): Optional Facebook session cookies (from a logged-in browser) to unlock more reviews. Without cookies, Facebook limits results to ~10–15 per page. Use a browser extension like 'EditThisCookie' to export cookies as JSON. Each entry must have at minimum 'name', 'value', and 'domain' fields. ## `proxyConfiguration` (type: `object`): Proxy settings for bypassing Facebook's bot detection. Recommended: use RESIDENTIAL proxy group for best results. Without proxy, Facebook may block requests from datacenter IPs. ## Actor input object example ```json { "mode": "url", "startUrls": [ { "url": "https://www.facebook.com/mcdonalds/reviews" } ], "maxReviews": 5, "sortBy": "most_recent", "filterByRecommendation": "all", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ```` # Actor output Schema ## `reviews` (type: `string`): Dataset of scraped Facebook reviews with author info, recommendation status, text, reactions, and page metadata. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "url", "startUrls": [ { "url": "https://www.facebook.com/mcdonalds/reviews" } ], "maxReviews": 5, "sortBy": "most_recent", "filterByRecommendation": "all", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/facebook-reviews-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "url", "startUrls": [{ "url": "https://www.facebook.com/mcdonalds/reviews" }], "maxReviews": 5, "sortBy": "most_recent", "filterByRecommendation": "all", "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/facebook-reviews-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "url", "startUrls": [ { "url": "https://www.facebook.com/mcdonalds/reviews" } ], "maxReviews": 5, "sortBy": "most_recent", "filterByRecommendation": "all", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call crawlerbros/facebook-reviews-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/facebook-reviews-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Reviews Scraper", "description": "Scrape public Facebook business page reviews by URL, business name search, or Page ID. Filters by date range, keyword, recommendation status, and sort order", "version": "0.1", "x-build-id": "yB4dCJhn8Ok4LX1dz" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~facebook-reviews-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-facebook-reviews-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~facebook-reviews-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-facebook-reviews-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~facebook-reviews-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-facebook-reviews-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Input Mode", "enum": [ "url", "search", "pageId" ], "type": "string", "description": "How to specify which Facebook page to scrape reviews from.", "default": "url" }, "startUrls": { "title": "Facebook Reviews URLs", "type": "array", "description": "Links to Facebook page review sections (e.g. https://www.facebook.com/mcdonalds/reviews). Used when mode is 'Direct URL'.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "searchQueries": { "title": "Business Search Queries", "type": "array", "description": "Business name and location to search on Facebook (e.g. 'Starbucks Dallas TX'). Used when mode is 'Business Name Search'.", "items": { "type": "string" } }, "pageIds": { "title": "Facebook Page IDs", "type": "array", "description": "Numeric Facebook Page IDs (e.g. '123456789'). Used when mode is 'Facebook Page ID'.", "items": { "type": "string" } }, "maxReviews": { "title": "Max Reviews (Global)", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum total reviews to scrape across all input pages (1–500). Collection stops once this global cap is reached.", "default": 100 }, "maxReviewsPerPage": { "title": "Max Reviews Per Page", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum reviews to scrape from each individual Facebook page (1–500). Useful when scraping multiple URLs to get an even spread of reviews per page." }, "sortBy": { "title": "Sort Order", "enum": [ "most_recent", "most_helpful" ], "type": "string", "description": "Order in which to load reviews from the page.", "default": "most_recent" }, "filterByRecommendation": { "title": "Recommendation Filter", "enum": [ "all", "recommended", "not_recommended" ], "type": "string", "description": "Only return reviews with the selected recommendation status. Facebook uses binary Recommended/Not Recommended (no star ratings).", "default": "all" }, "filterByDateFrom": { "title": "Date From (YYYY-MM-DD)", "type": "string", "description": "Only return reviews posted on or after this date. Format: YYYY-MM-DD (e.g. 2024-01-01)." }, "filterByDateTo": { "title": "Date To (YYYY-MM-DD)", "type": "string", "description": "Only return reviews posted on or before this date. Format: YYYY-MM-DD (e.g. 2024-12-31)." }, "filterByKeyword": { "title": "Keyword Filter", "type": "string", "description": "Only return reviews containing this word or phrase (case-insensitive)." }, "cookies": { "title": "Facebook Cookies", "type": "array", "description": "Optional Facebook session cookies (from a logged-in browser) to unlock more reviews. Without cookies, Facebook limits results to ~10–15 per page. Use a browser extension like 'EditThisCookie' to export cookies as JSON. Each entry must have at minimum 'name', 'value', and 'domain' fields." }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings for bypassing Facebook's bot detection. Recommended: use RESIDENTIAL proxy group for best results. Without proxy, Facebook may block requests from datacenter IPs." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```