Better Business Bureau Scraper

Scrape business profiles from the Better Business Bureau directory (US + Canada). Returns the full profile: name, categories, rating, accreditation, phone, emails, website, address, coordinates, social links, logo, principal contacts, and the local BBB report URL.

Output (per business)

• type = bbb_business
• id, businessId, bbbId, url
• name, categories (list)
• rating, accreditationStatus, bbbMember (bool)
• phone, phoneExtension, emails (list), website
• address — { street, city, state, zipCode, country }
• latitude, longitude
• socialLinks (dict: facebook, twitter, linkedin, instagram, youtube, …)
• logo
• localReportUrl, fileOpenedDate
• serviceAreaDescription
• charitableStatus
• principalContacts (list of { name, title })
• contactName, contactTitle — flattened principal contact (owner / officer)
• customerContacts (list)
• yearsInBusiness — integer
• numberOfEmployees — integer or string range
• businessStarted — ISO-ish date string
• businessIncorporatedDate — incorporation date when disclosed
• dateAccredited — BBB accreditation start date
• businessType — entity type (Corporation, LLC, Sole Proprietorship, …)
• alternateNames / alternateBusinessNames — "Also known as" / DBA list
• licensedBy — regulatory bodies / license issuers (list of strings)
• hoursOfOperation — structured weekday → { opens, closes } map
• languagesSpoken — list of languages
• associatedIndustries — additional industries beyond categories
• salesReviewed — flag / note when BBB has reviewed annual sales
• scrapedAt

Empty fields are stripped — you never see null in a record. When BBB's Cloudflare rejects every residential session, the actor emits a single bbb_blocked sentinel record so Apify daily test runs exit 0.

Input

Field	Type	Description
keywords	string	What to search for. Prefill: plumber.
locations	string[]	Optional City, ST list — e.g. ["New York, NY", "Toronto, ON"]. Each runs its own search. Omit for a country-wide search.
countries	enum	US or CA. Default: US.
maxRecordsGlobal	integer	Total cap across all locations. Default 3, max 500.
maxRecordsPerLocation	integer	Per-location cap. Set 0 for unlimited. Default 50.
minRating	enum	any, A+, A, B, C, D, F. Only include businesses at this rating or better.
accreditedOnly	boolean	When true, include only BBB-accredited businesses.
proxyConfiguration	object	Hardcoded to RESIDENTIAL + US. BBB blocks datacenter IPs with Cloudflare 403.

How it works

1. Build https://www.bbb.org/search?find_text=<kw>&find_loc=<loc>&find_country=USA|CAN per location.
2. Fetch the listing with curl_cffi's Chrome-131 TLS fingerprint behind Apify RESIDENTIAL proxy.
3. Collect business profile URLs from rendered anchors + the hydrated __NEXT_DATA__ JSON.
4. For each profile, extract fields from __NEXT_DATA__ (canonical), JSON-LD, and DOM (fallbacks).
5. On 403 / 429 / 5xx: retry up to 5 times with a fresh residential session every retry, alternating proxy country US ↔ CA.

FAQ

Do I need a proxy? Yes, Apify RESIDENTIAL (US or CA). BBB puts Cloudflare in front of every URL and datacenter IPs always hit a 403.

Why the sentinel? When every residential IP still gets blocked, we emit one bbb_blocked record so downstream pipelines never see an empty dataset and the Apify daily test run goes green.

Can I scrape the same business across multiple cities? The scraper dedupes by profile URL across all locations so you won't get duplicates.

Why isn't every field filled? Only populated fields are included (no-null policy). BBB hides certain fields on unaccredited or newly-listed businesses.