{
  "openapi": "3.0.1",
  "info": {
    "title": "BBB Scraper & API - Better Business Bureau Leads & Ratings",
    "description": "BBB scraper for Better Business Bureau (bbb.org) leads, US and Canada. Input: keywords, cities or ZIPs, filters (accredited, rating grade, distance) or BBB URLs. One result = one business: name, category, BBB rating, accreditation, phone, address, coordinates, profile URL. $1.00 per 1,000 results.",
    "version": "1.0",
    "x-build-id": "DQYc9feb4t6rnEfhA"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/rel8ble~bbb-business-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-rel8ble-bbb-business-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/rel8ble~bbb-business-scraper/runs": {
      "post": {
        "operationId": "runs-sync-rel8ble-bbb-business-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/rel8ble~bbb-business-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-rel8ble-bbb-business-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "searchQueries": {
            "title": "Keywords or categories",
            "type": "array",
            "description": "Required unless startUrls is given. What to search for, as typed into the BBB search box, one per line: a trade or category (\"plumber\", \"roofing contractors\", \"dentist\", \"auto repair\") or a business name (\"Mr. Rooter\"). Each keyword is searched in each location and returns up to maxItems businesses. Typical: 1-10 keywords.",
            "items": {
              "type": "string"
            }
          },
          "locations": {
            "title": "Locations (US and Canada)",
            "type": "array",
            "description": "Optional. Where to search, one per line: \"City, ST\" (\"Denver, CO\", \"Toronto, ON\"), a US ZIP code (\"80212\"), a Canadian postal code (\"M5V 2T6\") or a state / province code (\"TX\"). Every keyword is searched in every location (2 keywords x 3 locations = 6 searches). BBB searches a wide area around the place (often 50-100 miles); use maxDistanceMiles to tighten it. Empty = all of the US and Canada. A place BBB does not recognise is skipped and reported, never charged.",
            "items": {
              "type": "string"
            }
          },
          "accreditedOnly": {
            "title": "BBB Accredited businesses only",
            "type": "boolean",
            "description": "Optional. true = only businesses that are BBB Accredited (BBB's own filter). Default false = all businesses. Every row has an \"accredited\" true / false field either way.",
            "default": false
          },
          "ratings": {
            "title": "BBB rating grades",
            "type": "array",
            "description": "Optional. Keep only businesses with these BBB letter grades: any of \"A\", \"B\", \"C\", \"D\", \"F\" (\"A\" includes A+, A and A-). Several values = any of them. Empty = all, including businesses BBB has not rated. Use [\"D\", \"F\"] to find poorly rated businesses, [\"A\"] for the best-rated.",
            "items": {
              "type": "string",
              "enum": [
                "A",
                "B",
                "C",
                "D",
                "F"
              ],
              "enumTitles": [
                "A+ / A / A-",
                "B+ / B / B-",
                "C+ / C / C-",
                "D+ / D / D-",
                "F"
              ]
            }
          },
          "maxDistanceMiles": {
            "title": "Max distance from location (miles)",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "Optional. Only businesses within this many miles of each location. BBB offers 5, 10, 25, 50 and 100; other numbers are rounded to the nearest of those. 0 or empty = BBB's default wide area. Ignored when locations is empty.",
            "default": 0
          },
          "states": {
            "title": "States / provinces",
            "type": "array",
            "description": "Optional. Keep only businesses in these states or provinces, two-letter codes, one per line: \"CO\", \"TX\", \"ON\". Useful because a city search can reach across state lines (Denver also returns Wyoming and Nebraska). Empty = all.",
            "items": {
              "type": "string"
            }
          },
          "categories": {
            "title": "BBB categories (exact)",
            "type": "array",
            "description": "Optional, advanced. Narrow each search to exact BBB categories by name, one per line, e.g. \"Water Heater Repair\", \"Commercial Plumber\". Names BBB offers as a filter for that search use BBB's own category filter; other names keep only businesses that list that category. Most users leave this empty and put the trade in searchQueries instead.",
            "items": {
              "type": "string"
            }
          },
          "servingAreaOnly": {
            "title": "Only businesses serving the area",
            "type": "boolean",
            "description": "Optional. true = BBB's \"Serving my Area\" filter: only businesses that say they serve the searched location (some are based elsewhere). Default false.",
            "default": false
          },
          "skipOutOfBusiness": {
            "title": "Skip out-of-business listings",
            "type": "boolean",
            "description": "Optional. true (default) = leave out businesses BBB marks as out of business; they are not saved and not charged. false = keep them, with outOfBusiness: true on the row.",
            "default": true
          },
          "sort": {
            "title": "Sort order",
            "enum": [
              "relevance",
              "distance",
              "rating",
              "atoz",
              "ztoa"
            ],
            "type": "string",
            "description": "Optional. Order of results: \"relevance\" (default, BBB's best match), \"distance\" (nearest first), \"rating\" (best rated first), \"atoz\" or \"ztoa\" (by name). Matters most when maxItems is small; with deep search the whole set is collected anyway.",
            "default": "relevance"
          },
          "maxItems": {
            "title": "Max businesses per search",
            "minimum": 0,
            "type": "integer",
            "description": "Optional. Maximum businesses saved per search (one keyword in one location), integer >= 0. Default 100; 0 = every business the search can reach. You pay per business saved ($0.001 each), so 100 businesses = $0.10. Use 10-20 for a quick answer.",
            "default": 100
          },
          "deepSearch": {
            "title": "Deep search past BBB's 225 limit",
            "type": "boolean",
            "description": "Optional. BBB shows at most 225 businesses (15 pages) for any one search. With deepSearch on (default) and maxItems above 225, the actor splits the search by rating grade, state, category, distance, sort order and nearby towns and merges the results without duplicates (tested: 78% of BBB's count for plumber near Denver, 1,954 listed; 72% for roofing contractors near Houston, 4,706 listed). Off = at most 225 per search.",
            "default": true
          },
          "startUrls": {
            "title": "BBB URLs",
            "type": "array",
            "description": "Optional. URLs copied from bbb.org, one per line. A search URL (\"https://www.bbb.org/search?find_text=plumber&find_loc=Denver%2C%20CO&filter_ratings=A\") is scraped with the keyword, place, sort and filters in the URL (the filter fields above are not applied to it). A category page (\"https://www.bbb.org/us/co/denver/category/plumber\") becomes that keyword near that city. Business profile URLs are not supported (BBB puts profile pages behind a bot check) and are skipped with a warning.",
            "items": {
              "type": "string"
            }
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Optional, advanced. Number of parallel requests, integer 1-10. Default 4. Requests are also spaced at most 5 a second whatever this is set to. Leave unset.",
            "default": 4
          },
          "maxRequestRetries": {
            "title": "Max retries per request",
            "minimum": 0,
            "maximum": 20,
            "type": "integer",
            "description": "Optional, advanced. How many times a failed request is retried on a new session, integer 0-20. Default 8. Leave unset.",
            "default": 8
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Optional, advanced. Apify Proxy settings object. Default {\"useApifyProxy\": false}: BBB's search answers direct requests, so no proxy is needed. Switch on datacenter proxy only if the run log shows repeated blocks. Leave unset.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}