Search the BBB businesses dataset API

Endpoint facts

Method

GET

API path

/datasets/bbb-businesses/search

Auth

apiKey

Credits

1 credit/record returned · minimum 2

Charged on

Successful 2xx responses only

Platform

Datasets

Execution

Stored dataset records. No live scraping, browser session or proxy routing.

Response schema

#/definitions/datasets.bbbBusinessesSearchResponseDoc

How this endpoint behaves

Dataset id enum:

• bbb-businesses

Query parameters:

• q: optional full-text match on the business name/category, max 256 characters.
• category: optional exact category filter, e.g. Plumber (case-sensitive). Use the values returned by facets?facet=category.
• country: optional country filter parsed from the profile URL (case-insensitive). Allowed values: us, ca.
• address_country: optional country filter derived from the business address, separate from country (case-insensitive). Allowed values: us, ca.
• state: optional 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.
• city: optional exact city slug as in the profile URL, e.g. san-diego (case-insensitive). Use the values returned by facets?facet=city&state=<state>. The same slug exists in several states, so send state with it.
• rating: optional exact letter-grade rating filter. Allowed values: A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F.
• min_rating_rank: optional numeric floor against the numeric rating rank (A+=12 down to F=0), e.g. 10 for "A- and above".
• accredited: optional accreditation filter; true keeps only accredited businesses, false only the others.
• has_alerts: optional BBB-alert filter; true keeps businesses whose profile carries at least one BBB alert, false keeps refreshed records with none.
• alert_title: optional exact BBB alert title filter, e.g. Pattern of Complaint. Use the values returned by facets?facet=alert_title.
• min_complaints: optional floor against total_complaints (BBB's three-year complaint count), 0 or greater, e.g. 1 for businesses with at least one complaint.
• entity_type: optional exact entity-type filter, e.g. Limited Liability Company (LLC) (case-sensitive). Use the values returned by facets?facet=entity_type.
• run_id: optional exact crawl run id filter, e.g. bbb-20260906. Use the values returned by facets?facet=run_id.
• sort: optional sort order. Allowed values: relevance, rating_desc, rating_asc, accredited_first, name_asc, years_in_business_desc, complaints_desc. Defaults to relevance with q, otherwise accredited_first.
• page: optional page number, defaults to 1.
• page_size: optional page size, defaults to 20 and maxes at 100. page * page_size must not exceed 10000.

Response behavior:

• Each item carries business_id, bbb_local_id, name, url, country, state, city, address, phone, website, rating, rating_rank, rating_reasons, accredited, accredited_since, years_in_business, category, categories, business-detail fields (bbb_file_opened, business_started, business_incorporated, entity_type, alternate_names, business_management, additional_phone_numbers, additional_websites, social_media, licensing_note, hours, products_and_services), and the on-demand pointer fields complaints_url, reviews_url, more_info_url. address_country is included when a recognized address region code is present.
• country remains the country parsed from the profile URL. address_country is derived from a recognized state/territory/military or Canadian province code at the end of the business address; it is omitted when the address has no recognized code.
• Each item also carries BBB's counts from the profile page — total_complaints (the three-year figure the complaints page shows), complaints_closed_last_3_years, complaints_closed_last_12_months, total_reviews, average_review_rating — and the BBB alerts on the profile: has_alerts, alert_titles and alerts[] (each id, type_id, title, the complete text, links[], url; see bbb-business). BBB publishes no date field for an alert; dates are part of text.
• These fields are filled as records are re-crawled. A record not refreshed since they were added (2026-10) has none of the keys, so it matches neither has_alerts=true nor has_alerts=false and is excluded by min_complaints. crawled_at shows when a record was last read; a 0 count and an empty alerts array are real values, not gaps.
• complaints_desc sorts by total_complaints, records without a count last.
• rating_reasons on this record is the shallow rating-card list bbb-business itself returns — often a single generic boilerplate bullet. Fetch more_info_url for the fuller per-factor reasons on a lower-rated business.
• The maximum result window is 10000; page * page_size must not exceed 10000. To read a slice with more records than that, split it with the facets endpoint: list every state with facet=state, every city of a state with facet=city&state=<state> (paging with limit and offset), and search each state + city pair. No city holds more than 10,000 records.
• Invalid enum values return the standard invalid params envelope.
• Returns an empty items array (not an error) when nothing matches or the dataset has no data yet.
• Does not trigger live scraping.
• Billing: 1 credit per record returned, minimum 2. A search that returns 20 records costs 20 credits, a full page of 100 costs 100, and an empty or one-record result costs 2. You are charged for what comes back, not for the page_size you ask for, but your balance must cover the requested page_size for the call to be accepted. Use facets (1 credit) to size a query before paging through it.

Live monitoring

Monitored request

GET /datasets/bbb-businesses/search?category=Plumber

Checks passed, 7 days to 14 Oct 2026

100%

Median response time

0.56 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026

GET /datasets/bbb-businesses/search?category=Plumber&page_size=20

Items in items

20

Fields filled in every checked item

26

Fields empty in some or all items

12

Shared guides

Related