datasets_bbb_businesses_facets
Facet BBB businesses data by field such as state or city, honoring search filters, to count records and split searches over 10,000 results.
Instructions
Facet the BBB businesses dataset. Returns the values of one field of the BBB businesses index (dataset id enum value bbb-businesses) with the number of records for each, honoring the same filters as search. Facet enum: country, address_country, category, state, city, rating, accredited, entity_type, run_id, alert_title, has_alerts. The country facet is parsed from profile URLs; address_country is derived from business addresses. Both enums are us, ca. Values come most frequent first, 50 per page by default; page through all of them with limit (up to 1000) and offset while has_more is true. The response also returns total (records matching the filters), total_values (distinct values) and missing (records with no value for the facet), so the counts can be checked against the total. Values of the accredited and has_alerts facets are 1 (true) and 0 (false). Use it to split a search that would exceed 10,000 records: facet=state lists every state and province, and facet=city with a state filter lists every city in it.
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 facet=city with a state filter | |
| facet | Yes | Facet enum: country, address_country, category, state, city, rating, accredited, entity_type, run_id, alert_title, has_alerts | |
| limit | No | Values per page, 1 to 1000, defaults to 50 | |
| state | No | Exact 2-letter state or province code as in the profile URL, e.g. tx (case-insensitive). Use the values returned by facet=state | |
| offset | No | Values to skip, 0 or greater, defaults to 0; offset + limit must be <= 10000. Request offset + limit next while has_more is true | |
| 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 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 facet=category | |
| 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 (case-sensitive). Use the values returned by facet=alert_title | |
| entity_type | No | Exact entity-type filter, e.g. Limited Liability Company (LLC) (case-sensitive). Use the values returned by 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' |