BBB API endpoint
Browses bbb.org businesses by category and location directly, without a free-text search query. Returns the same business-result shape as bbb-search. 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. Optional sort and filter parameters use the same values as bbb-search; query-scoped category and state/province values come from bbb-search-filters.
/bbb/categoryQuery parameters:
url (required) — a BBB category-browse URL, taken from a bbb-search result's related_categories[].url.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.When no filters or sort are supplied, the endpoint preserves the category page's existing browse behavior. With filters or a sort, it follows the category page's public search context and returns the same normalized business-result fields as bbb-search. Category IDs and state/province codes remain query-scoped; use bbb-search-filters for the category URL's search context before submitting them. The filter response includes active values BBB still advertises.
A verified empty first page returns results: [], total_results: 0, total_pages: 1, and has_more: false. An unavailable or unrecognized page returns an error, not an empty result.
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 category 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.
| Field | Filled in, of 15 checked | Values in the sample |
|---|---|---|
| name | 15 | “Team Flo-Right LLC” and 13 other values |
| url | 15 | bbb.org |
| categories | 15 | median 3 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 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| url | string | Yes | BBB category browse URL, from a bbb-search result's related_categories | https://www.bbb.org/us/tx/austin/category/plumber | |
| page | integer | No | Result page, default 1 | ||
| 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 -X GET "https://api.crawlora.net/api/v1/bbb/category?url=https%3A%2F%2Fwww.bbb.org%2Fus%2Ftx%2Faustin%2Fcategory%2Fplumber&page=1&sort=Relevance&distance=5&rating=A&accredited=true&get_quote=true&service_area=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"page": 1,
"total_results": 2398,
"results": [
{
"name": "Abundant Plumbing LLC",
"url": "https://www.bbb.org/us/tx/austin/profile/plumber/abundant-plumbing-llc-0825-1000237688",
"categories": [
"Plumber"
],
"rating": "A-",
"accredited": true,
"phone": "(512) 201-9978",
"address": "PO Box 40698, Austin, TX 78704-0012"
}
],
"source_url": "https://www.bbb.org/us/tx/austin/category/plumber"
}
}Request schema
No body schema
Response schema
#/definitions/bbb.categoryResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | bbb.CategoryResponse | No | ||||
| data.has_more | boolean | No | true | |||
| data.page | integer | No | 1 | |||
| data.results | array | No | BusinessSearchResult record, 11 fields: accredited, address, categories, hq_profile_url, image_url, name, phone, quote_url, rating, service_areas, url. Described under BBB Search API. | |||
| data.results_capped | boolean | No | true | |||
| data.source_url | string | No | ||||
| data.total_pages | integer | No | 15 | TotalPages, HasMore and ResultsCapped follow SearchResponse. | ||
| data.total_results | integer | No | ||||
| msg | string | No | OK |
| 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 |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/bbb/category?url=https%3A%2F%2Fwww.bbb.org%2Fus%2Ftx%2Faustin%2Fcategory%2Fplumber&page=1&sort=Relevance&distance=5&rating=A&accredited=true&get_quote=true&service_area=true" \
-H "x-api-key: $CRAWLORA_API_KEY"