---
title: "Facet the BBB businesses dataset"
method: GET
path: "/datasets/bbb-businesses/facets"
tags: ["Datasets"]
---

# Facet the BBB businesses dataset

`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`

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.

## Query parameters

- `facet` 'country' | 'address_country' | 'category' | 'state' | 'city' | 'rating' | 'accredited' | 'entity_type' | 'run_id' | 'alert_title' | 'has_alerts', required
- `limit` integer
- `offset` integer
- `q` string
- `category` string
- `country` 'us' | 'ca'
- `address_country` 'us' | 'ca'
- `state` string
- `city` string
- `rating` 'A+' | 'A' | 'A-' | 'B+' | 'B' | 'B-' | 'C+' | 'C' | 'C-' | 'D+' | 'D' | 'D-' | 'F'
- `min_rating_rank` integer
- `accredited` boolean
- `has_alerts` boolean
- `alert_title` string
- `min_complaints` integer
- `entity_type` string
- `run_id` string

## Headers

- `x-api-key` string, required

## Response `200`

OK

- DatasetsBbbBusinessesFacetResponseDoc
  - `code` integer
  - `data` DatasetsBBBBusinessesFacetResponse
    - `dataset` string: Dataset id, always bbb-businesses.
    - `facet` string: The facet that was aggregated, as requested.
    - `has_more` boolean: True while another page exists; request offset + limit next.
    - `items` EsBBBBusinessesFacetItem[]: One page of values, most frequent first, ties in value order.
      - `count` integer: Number of matching records with this value.
      - `value` string: The facet value, to use as the matching search or facet filter. For the accredited and has_alerts facets it is 1 (true) or 0 (false).
    - `limit` integer: Values per page that was applied.
    - `missing` integer: Number of matching records that have no value for this facet.
    - `offset` integer: Number of values skipped.
    - `total` integer: Number of records matching the filters.
    - `total_values` integer: Number of distinct values of the facet across all pages.
    - `values_truncated` boolean: Present and true only when the facet has more than 10000 values, the furthest offset can reach; add a filter such as state to split it. total_values is then an estimate.
  - `msg` string

## Other responses

- `400`: Bad Request
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)