Datasets

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.

get/datasets/bbb-businesses/facets

Request

  • Base URL: https://api.crawlora.net/api/v1
  • URL: https://api.crawlora.net/api/v1/datasets/bbb-businesses/facets
  • Auth: API key in header x-api-key

Query parameters

facet'country' | 'address_country' | 'category' | 'state' | 'city' | 'rating' | 'accredited' | 'entity_type' | 'run_id' | 'alert_title' | 'has_alerts' required

Facet enum: country, address_country, category, state, city, rating, accredited, entity_type, run_id, alert_title, has_alerts

limitinteger

Values per page, 1 to 1000, defaults to 50

offsetinteger

Values to skip, 0 or greater, defaults to 0; offset + limit must be <= 10000. Request offset + limit next while has_more is true

qstring

Full-text match on the business name/category, max 256 characters

categorystring

Exact category filter, e.g. Plumber (case-sensitive). Use the values returned by facet=category

country'us' | 'ca'

Country filter, parsed from the profile URL (case-insensitive). Enum: us, ca

address_country'us' | 'ca'

Country filter derived from the business address, separate from the profile-URL country (case-insensitive). Enum: us, ca

statestring

Exact 2-letter state or province code as in the profile URL, e.g. tx (case-insensitive). Use the values returned by facet=state

citystring

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

rating'A+' | 'A' | 'A-' | 'B+' | 'B' | 'B-' | 'C+' | 'C' | 'C-' | 'D+' | 'D' | 'D-' | 'F'

Exact letter-grade rating filter. Enum: A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F

min_rating_rankinteger

Numeric floor against the denormalized rating rank (A+=12 down to F=0), e.g. 10 for 'A- and above'

accreditedboolean

Accreditation filter; true keeps only accredited businesses, false only the others

has_alertsboolean

BBB-alert filter; true keeps businesses whose profile carries at least one BBB alert, false keeps refreshed records with none

alert_titlestring

Exact BBB alert title filter, e.g. Pattern of Complaint (case-sensitive). Use the values returned by facet=alert_title

min_complaintsinteger

Floor against total_complaints (BBB's three-year complaint count), 0 or greater

entity_typestring

Exact entity-type filter, e.g. Limited Liability Company (LLC) (case-sensitive). Use the values returned by facet=entity_type

run_idstring

Exact crawl run id filter, e.g. bbb-20260906. Use the values returned by facet=run_id

Headers

x-api-keystring required

API key required

Response

OK

codeinteger
msgstring

Example response

{
  "code": 200,
  "data": {
    "dataset": "bbb-businesses",
    "facet": "city",
    "has_more": true,
    "items": [
      {
        "count": 3438,
        "value": "san-diego"
      }
    ],
    "limit": 50,
    "total": 44730,
    "total_values": 1128
  },
  "msg": "OK"
}

Changes

No recorded changes to this operation across all 3 revisions of this API.