BBB API endpoint
Returns the live sort, category, and state/province values BBB currently advertises for one context. Supply query and location for text search, or category_url for the exact category-browse context; do not combine these modes. Category IDs and state/province codes are query-scoped; call this endpoint again when the search context changes. Static accepted values are country USA or CAN; sort Relevance, Distance, Rating, AToZ, or ZToA; distance 5, 10, 25, 50, or 100 miles; rating A, B, C, D, or F.
/bbb/search/filtersReturns the current sort, category, and state/province options BBB advertises for one context. Use either text-search mode (query + location) or category-browse mode (category_url). Category IDs and state/province codes depend on the query, location, country, category URL, and selected filters; this is not a global category or region catalog.
Query parameters:
query — business name or category/service keyword; required with location when category_url is omitted.location — city and state/province or ZIP/postal code; required with query when category_url is omitted.category_url — optional BBB category-browse URL from related_categories[].url. When supplied, omit query and location; the country is derived from the URL path.country — optional in text-search mode, default USA: USA or CAN. In category-browse mode, omit it or use the value matching the URL country.page (optional, default 1).sort (optional) — Relevance, Distance, Rating, AToZ, or ZToA.distance (optional) — 5, 10, 25, 50, or 100 miles; omit for all distances.rating (repeatable) — A, B, C, D, or F.category_id (repeatable) — currently selected category IDs for the discovery context.state (repeatable) — currently selected state/province codes for the discovery context.accredited, get_quote, and service_area (optional, boolean) — include these current filters in the discovery context.Use the returned categories[].value and states[].value with bbb-search or bbb-category for the same context. The result includes active values BBB still advertises after the current selection. A different query, location, or category URL may return a different set. Do not combine category_url with query or location.
Example response for query=plumber, location=Austin, TX, and country=USA:
{"code":200,"msg":"OK","data":{"query":"plumber","location":"Austin, TX","country":"USA","page":1,"total_results":2544,"sorts":[{"label":"Best Match","value":"Relevance","is_active":true},{"label":"Distance","value":"Distance","is_active":false},{"label":"Rating","value":"Rating","is_active":false},{"label":"A-Z","value":"AToZ","is_active":false},{"label":"Z-A","value":"ZToA","is_active":false}],"categories":[{"value":"10113-000","label":"Plumber"},{"value":"10113-100","label":"Commercial Plumber"},{"value":"10113-300","label":"Plumbing Renovation"},{"value":"10114-000","label":"Sewer Cleaning"},{"value":"10167-000","label":"Water Heater Repair"},{"value":"80781-010","label":"Water Heater Installation"},{"value":"50720-100","label":"Tankless Water Heaters"},{"value":"10043-010","label":"Drain Cleaning"},{"value":"10131-000","label":"Sewer Contractors"},{"value":"10113-010","label":"Plumbing and Heating"}],"states":[{"value":"MA","label":"MA"},{"value":"TX","label":"TX"},{"value":"VA","label":"VA"}]}}
| Field | Filled in, of 3 checked | Values in the sample |
|---|---|---|
| value | 3 | “MA” and 2 other values |
| label | 3 | “MA” and 2 other values |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| query | string | No | Business name or category/service keyword; use with location when category_url is omitted | plumber | |
| location | string | No | City and state/province or ZIP code; use with query when category_url is omitted | Austin, TX | |
| category_url | string | No | BBB category browse URL; use instead of query and location | https://www.bbb.org/us/tx/austin/category/plumber | |
| country | string | No | BBB country code Allowed values: USA, CAN. | ||
| 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 | Selected rating values Allowed values: A, B, C, D, F. Repeat this query parameter for multiple values. | ||
| category_id | array<string> | No | Selected category IDs previously returned for this search context Repeat this query parameter for multiple values. | ||
| state | array<string> | No | Selected state/province codes previously returned for this search context 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/search/filters?query=coffee&country=us&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": {
"query": "plumber",
"location": "Austin, TX",
"country": "USA",
"page": 1,
"total_results": 2544,
"sorts": [
{
"label": "Best Match",
"value": "Relevance",
"is_active": true
},
{
"label": "Distance",
"value": "Distance",
"is_active": false
},
{
"label": "Rating",
"value": "Rating",
"is_active": false
},
{
"label": "A-Z",
"value": "AToZ",
"is_active": false
},
{
"label": "Z-A",
"value": "ZToA",
"is_active": false
}
],
"categories": [
{
"value": "10113-000",
"label": "Plumber"
},
{
"value": "10113-100",
"label": "Commercial Plumber"
},
{
"value": "10113-300",
"label": "Plumbing Renovation"
},
{
"value": "10114-000",
"label": "Sewer Cleaning"
},
{
"value": "10167-000",
"label": "Water Heater Repair"
},
{
"value": "80781-010",
"label": "Water Heater Installation"
},
{
"value": "50720-100",
"label": "Tankless Water Heaters"
},
{
"value": "10043-010",
"label": "Drain Cleaning"
},
{
"value": "10131-000",
"label": "Sewer Contractors"
},
{
"value": "10113-010",
"label": "Plumbing and Heating"
}
],
"states": [
{
"value": "MA",
"label": "MA"
},
{
"value": "TX",
"label": "TX"
},
{
"value": "VA",
"label": "VA"
}
]
}
}Request schema
No body schema
Response schema
#/definitions/bbb.searchFiltersResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | bbb.SearchFiltersResponse | No | ||||
| data.categories | array | No | ||||
| data.categories[].label | string | No | Plumber | |||
| data.categories[].value | string | No | 10113-000 | |||
| data.country | string | No | USA, CAN | USA | ||
| data.location | string | No | Austin, TX | |||
| data.page | integer | No | 1 | |||
| data.query | string | No | plumber | |||
| data.sorts | array | No | ||||
| data.sorts[].is_active | boolean | No | false | |||
| data.sorts[].label | string | No | Distance | |||
| data.sorts[].value | string | No | Relevance, Distance, Rating, AToZ, ZToA | Distance | ||
| data.states | array | No | ||||
| data.states[].label | string | No | Plumber | |||
| data.states[].value | string | No | 10113-000 | |||
| data.total_results | integer | No | 2544 | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/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/search/filters?query=coffee&country=us&page=1&sort=Relevance&distance=5&rating=A&accredited=true&get_quote=true&service_area=true" \
-H "x-api-key: $CRAWLORA_API_KEY"