{ "openapi": "3.0.1", "info": { "title": "BBB Business Scraper - Ratings, Accreditation, Complaints", "description": "Scrape Better Business Bureau (bbb.org) business profiles in the US and Canada by category and city, or from bbb.org URLs: BBB rating and reasons, accreditation date, years in business, complaint and review counts, phone, website, hours, licences. Optional review and complaint texts.", "version": "0.1", "x-build-id": "MLyMXMW01UHMzz5CA" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/amitaviv~bbb-business-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-amitaviv-bbb-business-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/amitaviv~bbb-business-scraper/runs": { "post": { "operationId": "runs-sync-amitaviv-bbb-business-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/amitaviv~bbb-business-scraper/run-sync": { "post": { "operationId": "run-sync-amitaviv-bbb-business-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": { "searchTerms": { "title": "Search terms", "type": "array", "description": "What to search for on bbb.org: a category or keyword (\"plumber\", \"roofing contractors\", \"dentist\") or a business name. Each term is searched in each location below.", "items": { "type": "string" } }, "locations": { "title": "Locations", "type": "array", "description": "Where to search: \"City, ST\" (\"Denver, CO\"), \"City, Province\" (\"Calgary, AB\" or \"Calgary, Alberta\") or a ZIP / postal code. State and province names are turned into their codes. Canadian locations are recognised by the province or postal code (or choose Canada under \"Country\"). Leave empty to search all of the country. bbb.org matches a place it does not know to another one (\"Denver, Colorado\" would become Denver City, TX); when the place it chose does not match the city and state you wrote, that search fails with a message and nothing is charged for it. A city name alone (\"Austin\") is searched as bbb.org reads it, which can be another state (Austin, IN), with a warning in the log; add the state code (\"Austin, TX\") to be sure.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "USA", "CAN" ], "type": "string", "description": "Optional. Which bbb.org country to search. Leave empty to decide from each location (a Canadian province code, province name or postal code means Canada, anything else the US). Choose Canada to search Canadian cities by name alone (\"Toronto\")." }, "startUrls": { "title": "bbb.org URLs", "type": "array", "description": "Optional. Business profile URLs (www.bbb.org/us/…/profile/…; any tab of a profile works), search result URLs (www.bbb.org/search?find_text=…) or category pages (www.bbb.org/us/co/denver/category/plumber). Profiles are read in full; searches and category pages are read like search terms.", "items": { "type": "string" } }, "maxItemsPerSearch": { "title": "Maximum businesses per search", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop each search (term x location, or search URL) after this many businesses. bbb.org shows at most 225 businesses per search; see \"Split large searches\" to go further. Profile URLs are not limited by this.", "default": 100 }, "includeDetails": { "title": "Read each business's profile", "type": "boolean", "description": "On (default): each business is completed from its bbb.org profile: rating reasons, accreditation date, years in business, start date, complaint counts, review average and count, website, opening hours, licences, social links, contact roles. Off: only what the search results show (name, address, phone, rating, accredited, categories); faster, same price per business.", "default": true }, "accreditedOnly": { "title": "BBB Accredited businesses only", "type": "boolean", "description": "Return only BBB Accredited businesses.", "default": false }, "radiusMiles": { "title": "Radius (miles)", "minimum": 1, "maximum": 500, "type": "integer", "description": "Optional. Only businesses within this distance of each location. A ZIP code with a small radius is the way to get complete coverage of a large city." }, "includeBranches": { "title": "Include local branch listings", "type": "boolean", "description": "On (default): bbb.org lists a company's local branches as results of their own, and each is delivered as its own record (isLocalBranch: true, with its own address and its headquarters). In test searches 3-5% of records were branches of a company that was also delivered. Off: a branch result is replaced by its company's headquarters profile, so each company is delivered and charged once.", "default": true }, "splitLargeSearches": { "title": "Split large searches", "type": "boolean", "description": "bbb.org shows at most 225 businesses per search. When a search has more and your maximum is above 225, the actor also reads it in other orders (A-Z, Z-A, distance, rating) and narrowed by rating group, accreditation, state and category. On \"plumber\" in \"Denver, CO\" (1,943 results) this delivered 1,206 distinct businesses instead of 225. Each business is delivered and charged once. For complete coverage of a big area, also search ZIP codes with a radius.", "default": true }, "includeReviews": { "title": "Include customer review texts", "type": "boolean", "description": "Add the newest customer reviews of each business (date, star rating, text, and the replies of the business and the reviewer in order). Reviewer names are not included unless you also turn on \"Include reviewer names\". Review texts are as written by the reviewer and can mention names (the reviewer's own, or staff of the business); bbb.org does not mask them all. Charged as one \"review and complaint texts\" event per business.", "default": false }, "includeComplaints": { "title": "Include complaint texts", "type": "boolean", "description": "Add the newest complaints of each business (date, type, status, complaint text, the business's and the consumer's responses). bbb.org masks most consumer names in these texts; the actor also masks names after Mr/Mrs/Ms and in \"the customer, Name,\", but a name in other wording can remain. Charged as one \"review and complaint texts\" event per business.", "default": false }, "maxTextsPerBusiness": { "title": "Maximum reviews and complaints per business", "minimum": 1, "maximum": 500, "type": "integer", "description": "How many of the newest reviews, and how many complaints, to add per business.", "default": 20 }, "includeContactNames": { "title": "Include names of contact persons", "type": "boolean", "description": "Off (default): management contacts are returned as roles only (\"Owner\", \"President\"). On: contacts also get their names, and with \"Include email addresses\" on, addresses that may belong to a person are returned too. Turn this on only if you have a lawful basis to process personal data of the people named (for example GDPR Art. 6(1)(f) legitimate interest with a balancing test, or a CCPA-compliant purpose) and you will honour their rights. You are the data controller for what you collect.", "default": false }, "includeEmails": { "title": "Include email addresses", "type": "boolean", "description": "Off (default): no email addresses. bbb.org does not display email addresses on its profile pages (visitors get an \"Email this Business\" form); the addresses are in the page's data in disguised form, and this option decodes them. On: role and company addresses (info@, office@, an address made of the business's own name) are returned, and addresses that may name a person are withheld (counted in emailsWithheld) unless \"Include names of contact persons\" is also on. Turn this on only if you have a lawful basis to process these addresses (GDPR, CCPA, CASL), and do not use them for unsolicited commercial email: US CAN-SPAM treats addresses collected automatically from websites strictly. You are responsible for how you use them.", "default": false }, "includeReviewerNames": { "title": "Include reviewer names", "type": "boolean", "description": "Off (default): reviews come without the reviewer's name. Turn this on only if you confirm a lawful basis to process these consumers' personal data (for example GDPR Art. 6(1)(f) legitimate interest with a balancing test) and you will honour their rights.", "default": false }, "onlyNew": { "title": "Only new businesses (monitoring)", "type": "boolean", "description": "Deliver and charge only businesses that earlier runs of this actor in your account have not delivered for the same search. Useful on a schedule: each run returns the businesses that newly appear in the search. The memory is a key-value store named bbb-business-scraper-monitor in your account; delete it to start over.", "default": false }, "monitorKey": { "title": "Monitor name (optional)", "type": "string", "description": "Only with \"Only new businesses\". Runs with the same search and monitor name share one memory; give two schedules different names to keep their memories apart." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Leave off (default). The actor sends requests directly; when bbb.org's Cloudflare protection refuses a request, that request is retried through Apify Proxy on its own (datacenter first, then US residential). Set a proxy here only to send every request through it.", "default": { "useApifyProxy": false } } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }