Skip to content

About

BBB scraper for Python and the command line: Better Business Bureau search results for a trade or business name in a US city, with letter grade, accreditation, phones, full address, categories and service areas, as JSON or CSV. Free and open source; sign in with your QuanticData account, no proxies or headless browser to run.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

BBB Scraper

ci python license dependencies

Scrape the Better Business Bureau from Python or the command line: the businesses a BBB search returns for a trade or a business name in a US city, with the BBB letter grade, the accreditation flag, every listed phone, the full address and map point, the categories each business is filed under, the local bureau and its service areas, as JSON or CSV. The code is free and open source (MIT). It runs on the QuanticData Data API, so there are no proxies to rotate and no headless browser to keep alive: sign in once and run a command.

pip install git+https://github.com/quantumproxies/bbb-scraper
bbb-scraper login
bbb-scraper search plumber --location "Chicago, IL" --max-results 60 -o plumbers.csv

login opens the QuanticData sign-in page in your browser. New accounts get $2 of free usage every month, no card required: create one.

What it scrapes

Command Input Returns Per run
bbb-scraper search trade or business name, US city Name, BBB grade, accreditation, phones, address, categories, 20 fields per row (fields and price) up to 200

--location takes a US city and state ("Chicago, IL", "Austin, TX"). Each row carries the BBB letter grade (A+ to F, NR when the BBB has not rated the business), the accreditation flag, every phone the BBB lists, the categories the business is filed under, the local bureau that keeps the profile, up to 25 service areas, and out_of_business when the BBB marks it so.

Sample output

A real row from bbb-scraper search plumber --location "Chicago, IL" --max-results 3 (2026-10-23):

{
  "id": "0654-38001111",
  "url": "https://www.bbb.org/us/il/chicago/profile/general-contractor/ames-construction-inc-of-illinois-0654-38001111",
  "city": "Chicago",
  "name": "Ames Construction, Inc of Illinois",
  "rank": 2,
  "phone": "(773) 379-2637",
  "state": "IL",
  "bureau": "BBB of Chicago & Northern Illinois",
  "phones": [
    "(773) 379-2637",
    "(312) 321-9325"
  ],
  "rating": "A+",
  "street": "1021 W Adams St",
  "country": "US",
  "category": "General Contractor",
  "latitude": 41.87878036499023,
  "longitude": -87.65272521972656,
  "accredited": true,
  "categories": [
    "General Contractor",
    "Roofing Contractors",
    "Construction Services",
    "Plumber"
  ],
  "postal_code": "60607-2934",
  "service_areas": [
    "Ashburn Park, IL",
    "Bedford Park, IL",
    "Burnham, IL",
    "Calumet Park, IL",
    "Chestnut Street, IL"
  ],
  "out_of_business": false
}

Python

from quanticdata_bbb_scraper import BBBScraper

bbb = BBBScraper()  # saved login, or QUANTICDATA_API_KEY

plumbers = bbb.search("plumber", location="Chicago, IL", max_results=60)
for b in plumbers:
    print(b["rating"], b["accredited"], b["name"], b["phone"], b["city"])
plumbers.to_csv("chicago_plumbers.csv")

accredited = [b for b in plumbers if b["accredited"] and not b["out_of_business"]]
print(len(accredited), "of", len(plumbers), "are BBB Accredited")

Each call returns a Run: iterate it for the rows (plain dicts), take len(), or save it with to_csv(), to_json(), to_jsonl() or to_dataframe() (pandas). Errors are specific: InsufficientCredit, RateLimited, InvalidInput, JobFailed, AuthError.

Examples

  • Contractor lead lists: Run a few trades in a few cities and keep the businesses that are accredited, rated A- or better and still in business, with phones, address and categories. See examples/accredited_leads.py.
  • Grade breakdown of a market: For one trade in one city, count the businesses per BBB letter grade and the share that is accredited, from up to 200 results. See examples/grade_report.py.
  • Vendor checks: Look up a list of company names in their city and get the BBB grade, accreditation and profile link of the best match for each. See examples/check_vendors.py.

Command line

Results print as a table; -o file.csv, -o file.json or -o file.jsonl writes a file. List inputs take a b c, a,b,c, @file.txt (one per line) or - (stdin). --no-wait starts a long run in the background and prints its id; bbb-scraper run <id> -o out.csv collects it later.

bbb-scraper search

Businesses from a Better Business Bureau search for a trade or a business name in a US city: grade, accreditation, phones, full address.

bbb-scraper search QUERY [options]
Option Type Default Description
QUERY string What to search for, e.g. "plumber" or "roofing".
--location string US city and state, e.g. "Chicago, IL". Required.
--country string Country to run the request from, as an ISO 3166-1 alpha-2 code (us, gb, de...).
--max-results integer 30 How many businesses to deliver at most (1–200). You pay only for delivered businesses.

Output fields

bbb-scraper search: 20 fields
Field Type Description
rank integer 1-based position across pages, after duplicates are removed.
id string or null BBB business id. A company listed both as a main profile and as a per-location entry shares one id and is delivered once.
name string Business name.
phone string or null Phone number as published.
street string or null Street address.
city string or null City.
state string or null State code.
postal_code string or null ZIP code.
country string or null Country code.
url string or null BBB profile URL.
rating string or null BBB letter grade (A+ to F). "NR" when the BBB has not rated the business.
accredited boolean or null True when the business is BBB Accredited.
phones string[] or null Every phone number the BBB lists for the business; phone is the first.
category string or null Primary type of business as the BBB files it ("Plumber", "General Contractor").
categories string[] or null All BBB categories the business is filed under.
latitude number or null Latitude of the business as the BBB publishes it. Null when the BBB has no point for the business (it then shows the searched city's centre, which is not delivered).
longitude number or null Longitude of the business; null together with latitude.
bureau string or null The local BBB that maintains the profile.
service_areas string[] or null Areas served (ZIP codes or towns), up to 25.
out_of_business boolean True when the BBB marks the business as out of business.

Sign-in and API keys

  • bbb-scraper login signs you in with OAuth 2.1 and PKCE in the browser. The token is stored in ~/.config/quanticdata/credentials.json (readable only by you) and refreshed automatically. One login serves every QuanticData tool on the machine.
  • No browser on the machine (SSH, Docker, Colab): run bbb-scraper login --no-browser, open the link anywhere, then paste back the address the browser ends on.
  • Scripts and CI: set QUANTICDATA_API_KEY to a key from the dashboard, or store one with bbb-scraper login --api-key.
  • bbb-scraper logout revokes the token. The connection is listed under API keys in the dashboard as "API · QuanticData CLI"; deleting that key disconnects every machine that uses it.

Pricing

The code is free and MIT-licensed. Runs are billed to your QuanticData account per delivered row, at the price shown on each collector page linked above; $2 of usage is free every month and failed runs are never billed. Plans with higher limits: pricing.

Other ways to call it

The same data over plain HTTP:

curl -X POST https://api.quanticdata.io/v1/scraper/collectors/bbb_businesses/run \
  -H "Authorization: Bearer $QUANTICDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"query": "plumber", "location": "Chicago, IL", "max_results": 3}}'
  • API reference with Python, Node, PHP and curl examples.
  • MCP server to give Claude, Cursor or any MCP client the same tools.
  • n8n node for no-code workflows.

FAQ

Is this BBB scraper free?

The code is free and MIT-licensed. Scraping runs on your QuanticData account: $2 of usage is free every month with no card, then you pay per delivered row at the price shown on each collector page. Failed runs are never billed.

Do I need proxies or a headless browser?

No. You send a trade or a business name and a city, and get rows back; the requests run on QuanticData's side.

Which locations does it cover?

US cities, given as city and state ("Chicago, IL"). Each row says whether the business is BBB Accredited and which local bureau keeps its profile.

How many businesses can one run return?

Up to 200 businesses per run; ask for fewer with --max-results and you pay only for what is delivered. Duplicate entries of the same company are removed before delivery.

Can I export to CSV or Excel?

Add -o results.csv (or .json, .jsonl). Lists such as phones, categories and service areas are joined with '; ', so the CSV opens cleanly in Excel or Google Sheets.

Can I run it on a schedule?

Yes. Set QUANTICDATA_API_KEY in the environment and call the CLI or examples/accredited_leads.py from cron, GitHub Actions or any scheduler.

Related scrapers

License

MIT. Built and maintained by QuanticData.

About

BBB scraper for Python and the command line: Better Business Bureau search results for a trade or business name in a US city, with letter grade, accreditation, phones, full address, categories and service areas, as JSON or CSV. Free and open source; sign in with your QuanticData account, no proxies or headless browser to run.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages