Docs menu

BBB API endpoint

BBB Search API

Searches bbb.org for businesses by name or category near a location. Returns each business's BBB rating letter grade, accreditation status, categories, service areas, contact info, and profile URL. A verified empty first page returns results: [] and total_results: 0; an unavailable or unrecognized page returns an error. A page beyond the exact last page returns 404, and a page beyond BBB's 15-page accessible limit returns 404 naming that limit. Category IDs and state/province codes are query-scoped; call bbb-search-filters to discover values for this query and location.

GETapiKey2 credits/requestBBBbbb.searchResponseDoc/bbb/search

Endpoint facts

Method: GET
API path: /bbb/search
Auth: apiKey
Credits: 2 credits/request
Charged on: Successful 2xx responses only
Platform: BBB
Response schema: #/definitions/bbb.searchResponseDoc

BBB Scraper API Try BBB Search API in Playground BBB API documentation

How this endpoint behaves

Query parameters:

query (required) — business name or category/service keyword, e.g. plumber.
location (required) — city and state/province (e.g. Austin, TX or Toronto, ON) or a ZIP/postal code.
country (optional, default USA) — USA or CAN.
page (optional, default 1).
sort (optional) — Relevance, Distance, Rating, AToZ, or ZToA.
distance (optional) — maximum distance in miles: 5, 10, 25, 50, or 100. Omit it to include all distances.
rating (repeatable) — A, B, C, D, or F.
category_id (repeatable) — category IDs returned for the same query context by bbb-search-filters.
state (repeatable) — state or province codes returned for the same query context by bbb-search-filters.
accredited (optional, boolean) — only BBB-accredited businesses.
get_quote (optional, boolean) — only businesses offering quote requests.
service_area (optional, boolean) — only businesses serving the searched area.

total_results is the upstream total match count, not just this page. BBB returns 15 results per page. results[] carries the business's BBB rating, accreditation status, categories, service areas, contact information, and profile URL. hq_profile_url is set only when BBB shows a separate headquarters rating link for a local profile; pass that URL instead of url to the business/complaints endpoints to look up the headquarters profile. related_categories[] lists category-browse links for the same location.

Category IDs and state/province codes are query-scoped, not global enums. Fetch bbb-search-filters for the same query, location, country, and selected filters before using them. The response includes active values that BBB still advertises in the current context.

A genuine no-match search returns results: [], total_results: 0, total_pages: 1, and has_more: false. A failed or unrecognized source read returns an error, never an empty search.

Paging: results come 15 per page. total_pages is the last page BBB serves for the query and has_more is true while page is before it. A page beyond an exact last page returns 404 naming that page. BBB serves at most 15 pages (225 results) of any listing, whatever total_results says; results_capped: true marks results that extend beyond BBB's accessible page limit. A request beyond that limit returns 404 naming the accessible page limit. Narrow the search (rating, state, category, distance, or a smaller location) to reach more results. The three paging fields are omitted when BBB's listing data did not carry a page count.

Live monitoring

Monitored request: GET /bbb/search?location=Austin%2C+TX&query=plumber
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 10.70 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /bbb/search?location=Austin%2C+TX&query=plumber
Items in results: 15
Fields filled in every checked item: 8
Fields empty in some or all items: 3

Field	Filled in, of 15 checked	Values in the sample
name	15	“Calixto Plumbing” and 13 other values
url	15	bbb.org
categories	15	median 4 entries
rating	15	A+ (12), A (3)
accredited	15	true in 15 of 15
phone	15
address	15
image_url	11	m.bbb.org
service_areas	15	median 6 entries
quote_url	14	bbb.org
hq_profile_url	2	bbb.org

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	Business name or category/service keyword	plumber
location	string	Yes	City and state (e.g. 'Austin, TX') or a ZIP code	Austin, TX
page	integer	No	Result page, default 1
country	string	No	BBB country code Allowed values: USA, CAN.
sort	string	No	Sort order Allowed values: Relevance, Distance, Rating, AToZ, ZToA.
distance	string	No	Maximum distance in miles; omit for all distances Allowed values: 5, 10, 25, 50, 100.
rating	array<string>	No	One or more BBB rating buckets Allowed values: A, B, C, D, F. Repeat this query parameter for multiple values.
category_id	array<string>	No	Query-scoped category ID from bbb-search-filters Repeat this query parameter for multiple values.
state	array<string>	No	Query-scoped state or province code from bbb-search-filters Repeat this query parameter for multiple values.
accredited	boolean	No	Only BBB-accredited businesses
get_quote	boolean	No	Only businesses offering quote requests
service_area	boolean	No	Only businesses serving the searched area
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/bbb/search?query=plumber&location=Austin%2C+TX&page=1&country=us&sort=Relevance&distance=5&rating=A&accredited=true&get_quote=true&service_area=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "plumber",
    "location": "Austin, TX",
    "page": 1,
    "total_results": 2544,
    "results": [
      {
        "name": "Calixto Plumbing",
        "url": "https://www.bbb.org/us/tx/austin/profile/plumber/calixto-plumbing-0825-1000223803",
        "categories": [
          "Plumber",
          "Plumbing Renovation",
          "Commercial Plumber",
          "Plumbing and Heating"
        ],
        "rating": "A+",
        "accredited": true,
        "phone": "(512) 945-3143",
        "address": "8410 Georgian Dr # B, Austin, TX 78753-6003",
        "image_url": "https://m.bbb.org/prod/ProfileImages/2024/1f7a8bd4-fdd2-45ca-8963-5c246e1d3b85.png",
        "service_areas": [
          "Bell County, TX",
          "Travis County, TX"
        ],
        "quote_url": "https://www.bbb.org/central-texas/quote/request-calixto-plumbing-1000223803"
      }
    ],
    "related_categories": [
      {
        "name": "Plumber",
        "url": "https://www.bbb.org/us/tx/austin/category/plumber"
      }
    ],
    "source_url": "https://www.bbb.org/search?find_country=USA&find_loc=Austin%2C+TX&find_text=plumber"
  }
}

Request schema

No body schema

Response schema

#/definitions/bbb.searchResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	bbb.SearchResponse	No
data.has_more	boolean	No	true
data.location	string	No	Austin, TX
data.page	integer	No	1
data.query	string	No	plumber
data.related_categories	array	No
data.related_categories[].name	string	No	Plumber
data.related_categories[].url	string	No
data.results	array	No
data.results[].accredited	boolean	No
data.results[].address	string	No
data.results[].categories	array	No
data.results[].hq_profile_url	string	No
data.results[].image_url	string	No
data.results[].name	string	No
data.results[].phone	string	No
data.results[].quote_url	string	No
data.results[].rating	string	No	A+
data.results[].service_areas	array	No
data.results[].url	string	No
data.results_capped	boolean	No	true
data.source_url	string	No
data.total_pages	integer	No	15	TotalPages is the last page BBB serves for this query and HasMore is true while Page is before it. BBB stops a listing at 15 pages of 15, so ResultsCapped marks a query whose TotalResults cannot all be reached by paging; narrow it with filters to reach the rest. All three are left out when BBB's listing data did not carry the page count.
data.total_results	integer	No	2514
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
404	Not Found	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/bbb/search?query=plumber&location=Austin%2C+TX&page=1&country=us&sort=Relevance&distance=5&rating=A&accredited=true&get_quote=true&service_area=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More BBB endpoint docs BBB Scraper API Get a BBB article API documentation BBB Business API documentation BBB Business Complaints API documentation BBB Business More Info API documentation BBB Business Reviews API documentation BBB Category API documentation

Open in Playground Back to group

Docs menu

BBB API endpoint

BBB Search API

GETapiKey2 credits/requestBBBbbb.searchResponseDoc/bbb/search

Endpoint facts

Method: GET
API path: /bbb/search
Auth: apiKey
Credits: 2 credits/request
Charged on: Successful 2xx responses only
Platform: BBB
Response schema: #/definitions/bbb.searchResponseDoc

BBB Scraper API Try BBB Search API in Playground BBB API documentation

How this endpoint behaves

Query parameters:

query (required) — business name or category/service keyword, e.g. plumber.
location (required) — city and state/province (e.g. Austin, TX or Toronto, ON) or a ZIP/postal code.
country (optional, default USA) — USA or CAN.
page (optional, default 1).
sort (optional) — Relevance, Distance, Rating, AToZ, or ZToA.
distance (optional) — maximum distance in miles: 5, 10, 25, 50, or 100. Omit it to include all distances.
rating (repeatable) — A, B, C, D, or F.
category_id (repeatable) — category IDs returned for the same query context by bbb-search-filters.
state (repeatable) — state or province codes returned for the same query context by bbb-search-filters.
accredited (optional, boolean) — only BBB-accredited businesses.
get_quote (optional, boolean) — only businesses offering quote requests.
service_area (optional, boolean) — only businesses serving the searched area.

A genuine no-match search returns results: [], total_results: 0, total_pages: 1, and has_more: false. A failed or unrecognized source read returns an error, never an empty search.

Live monitoring

Monitored request: GET /bbb/search?location=Austin%2C+TX&query=plumber
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 10.70 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /bbb/search?location=Austin%2C+TX&query=plumber
Items in results: 15
Fields filled in every checked item: 8
Fields empty in some or all items: 3

Field	Filled in, of 15 checked	Values in the sample
name	15	“Calixto Plumbing” and 13 other values
url	15	bbb.org
categories	15	median 4 entries
rating	15	A+ (12), A (3)
accredited	15	true in 15 of 15
phone	15
address	15
image_url	11	m.bbb.org
service_areas	15	median 6 entries
quote_url	14	bbb.org
hq_profile_url	2	bbb.org

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	Business name or category/service keyword	plumber
location	string	Yes	City and state (e.g. 'Austin, TX') or a ZIP code	Austin, TX
page	integer	No	Result page, default 1
country	string	No	BBB country code Allowed values: USA, CAN.
sort	string	No	Sort order Allowed values: Relevance, Distance, Rating, AToZ, ZToA.
distance	string	No	Maximum distance in miles; omit for all distances Allowed values: 5, 10, 25, 50, 100.
rating	array<string>	No	One or more BBB rating buckets Allowed values: A, B, C, D, F. Repeat this query parameter for multiple values.
category_id	array<string>	No	Query-scoped category ID from bbb-search-filters Repeat this query parameter for multiple values.
state	array<string>	No	Query-scoped state or province code from bbb-search-filters Repeat this query parameter for multiple values.
accredited	boolean	No	Only BBB-accredited businesses
get_quote	boolean	No	Only businesses offering quote requests
service_area	boolean	No	Only businesses serving the searched area
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/bbb/search?query=plumber&location=Austin%2C+TX&page=1&country=us&sort=Relevance&distance=5&rating=A&accredited=true&get_quote=true&service_area=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "plumber",
    "location": "Austin, TX",
    "page": 1,
    "total_results": 2544,
    "results": [
      {
        "name": "Calixto Plumbing",
        "url": "https://www.bbb.org/us/tx/austin/profile/plumber/calixto-plumbing-0825-1000223803",
        "categories": [
          "Plumber",
          "Plumbing Renovation",
          "Commercial Plumber",
          "Plumbing and Heating"
        ],
        "rating": "A+",
        "accredited": true,
        "phone": "(512) 945-3143",
        "address": "8410 Georgian Dr # B, Austin, TX 78753-6003",
        "image_url": "https://m.bbb.org/prod/ProfileImages/2024/1f7a8bd4-fdd2-45ca-8963-5c246e1d3b85.png",
        "service_areas": [
          "Bell County, TX",
          "Travis County, TX"
        ],
        "quote_url": "https://www.bbb.org/central-texas/quote/request-calixto-plumbing-1000223803"
      }
    ],
    "related_categories": [
      {
        "name": "Plumber",
        "url": "https://www.bbb.org/us/tx/austin/category/plumber"
      }
    ],
    "source_url": "https://www.bbb.org/search?find_country=USA&find_loc=Austin%2C+TX&find_text=plumber"
  }
}

Request schema

No body schema

Response schema

#/definitions/bbb.searchResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	bbb.SearchResponse	No
data.has_more	boolean	No	true
data.location	string	No	Austin, TX
data.page	integer	No	1
data.query	string	No	plumber
data.related_categories	array	No
data.related_categories[].name	string	No	Plumber
data.related_categories[].url	string	No
data.results	array	No
data.results[].accredited	boolean	No
data.results[].address	string	No
data.results[].categories	array	No
data.results[].hq_profile_url	string	No
data.results[].image_url	string	No
data.results[].name	string	No
data.results[].phone	string	No
data.results[].quote_url	string	No
data.results[].rating	string	No	A+
data.results[].service_areas	array	No
data.results[].url	string	No
data.results_capped	boolean	No	true
data.source_url	string	No
data.total_pages	integer	No	15	TotalPages is the last page BBB serves for this query and HasMore is true while Page is before it. BBB stops a listing at 15 pages of 15, so ResultsCapped marks a query whose TotalResults cannot all be reached by paging; narrow it with filters to reach the rest. All three are left out when BBB's listing data did not carry the page count.
data.total_results	integer	No	2514
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
404	Not Found	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/bbb/search?query=plumber&location=Austin%2C+TX&page=1&country=us&sort=Relevance&distance=5&rating=A&accredited=true&get_quote=true&service_area=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

BBB Search API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

BBB Search API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related