datasets_bbb_businesses_search
Search the Better Business Bureau business dataset by name, category, location, rating, accreditation, alerts, or complaints to find matching profiles.
Instructions
Search the BBB businesses dataset. Searches the BBB (Better Business Bureau) businesses index (dataset id enum value bbb-businesses) — business profiles crawled from bbb.org's own search/category-browse pages: computed A+-F letter-grade rating, paid-accreditation status, category, contact info, business details, operating hours, and products/services. Complaints, full reviews, and the full "reasons for rating"/service-area detail are NOT embedded here; each record instead carries complaints_url/reviews_url/more_info_url pointing at the live bbb-business-complaints/bbb-business-reviews/bbb-business-more-info endpoints for on-demand lookup. rating enum: A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F. Each record also stores BBB's complaint and review counts (total_complaints and related fields) and the BBB alerts on the profile (has_alerts, alert_titles, alerts[] with full text), so businesses with complaints or with a given alert can be listed without calling the live endpoints; these fields are filled as records are re-crawled and are absent on a record not refreshed since they were added. country is parsed from the profile URL; address_country is derived separately from the business address. Both enums are us, ca. sort enum: relevance, rating_desc, rating_asc, accredited_first, name_asc, years_in_business_desc, complaints_desc. A query returns at most 10,000 records; to read more, split it with the values and counts from the facets endpoint (for example one request per state, then per city) so each part stays under that limit. Billing: this search costs 1 credit per record returned, with a minimum of 2 (an empty result costs 2, a full page of 100 costs 100); the item and facets endpoints cost 1.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Full-text match on the business name/category, max 256 characters | |
| city | No | Exact city slug as in the profile URL, e.g. san-diego (case-insensitive). Use the values returned by facets?facet=city with a state filter; the same slug exists in several states, so send state with it | |
| page | No | Page number, defaults to 1 | |
| sort | No | Sort enum: relevance, rating_desc, rating_asc, accredited_first, name_asc, years_in_business_desc, complaints_desc | |
| state | No | Exact 2-letter state or province code as in the profile URL, e.g. tx (case-insensitive). Use the values returned by facets?facet=state | |
| rating | No | Exact letter-grade rating filter. Enum: A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F | |
| run_id | No | Exact crawl run id filter, e.g. bbb-20260906. Use the values returned by facets?facet=run_id | |
| country | No | Country filter, parsed from the profile URL (case-insensitive). Enum: us, ca | |
| category | No | Exact category filter, e.g. Plumber (case-sensitive). Use the values returned by facets?facet=category | |
| page_size | No | Page size, defaults to 20 and maxes at 100; page * page_size must be <= 10000 | |
| accredited | No | Accreditation filter; true keeps only accredited businesses, false only the others | |
| has_alerts | No | BBB-alert filter; true keeps businesses whose profile carries at least one BBB alert, false keeps refreshed records with none | |
| alert_title | No | Exact BBB alert title filter, e.g. Pattern of Complaint. Use the values returned by facets?facet=alert_title | |
| entity_type | No | Exact entity-type filter, e.g. Limited Liability Company (LLC) (case-sensitive). Use the values returned by facets?facet=entity_type | |
| min_complaints | No | Floor against total_complaints (BBB's three-year complaint count), 0 or greater | |
| address_country | No | Country filter derived from the business address, separate from the profile-URL country (case-insensitive). Enum: us, ca | |
| min_rating_rank | No | Numeric floor against the denormalized rating rank (A+=12 down to F=0), e.g. 10 for 'A- and above' |