{
  "openapi": "3.0.1",
  "info": {
    "title": "BBB Scraper — Ratings, Accreditation & Contacts",
    "description": "Scrape Better Business Bureau (bbb.org) businesses by keyword + location or profile URL. Returns BBB rating, accreditation, phone, website, address & contacts. MCP/API-ready.",
    "version": "0.1",
    "x-build-id": "tPfdAcUQx9T6e7q7R"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~bbb-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-bbb-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/khadinakbar~bbb-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-bbb-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/khadinakbar~bbb-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-bbb-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": {
          "searchKeyword": {
            "title": "Search keyword",
            "type": "string",
            "description": "Business type or name to look up on bbb.org, for example 'plumber', 'hvac contractor' or a company name. Combine with 'location' to scope it to one city. Leave empty if you use 'searchKeywords' for a batch or paste profile links in 'startUrls'. This is a search word, not a web address: for one known business use 'startUrls'."
          },
          "searchKeywords": {
            "title": "More keywords (batch)",
            "type": "array",
            "description": "Optional list of extra keywords to search in the same run, for example ['plumber','electrician','roofer']. Every keyword is searched in every location, so 3 keywords and 4 locations run 12 searches (limit 100 searches per run). Results are de-duplicated across searches. Leave empty for a single keyword.",
            "items": {
              "type": "string"
            }
          },
          "location": {
            "title": "Location (City, State)",
            "type": "string",
            "description": "Area to search, written as 'City, ST' for the US or 'City, Province' for Canada, for example 'Los Angeles, CA'. Optional: leave empty for a nationwide search. Not used when you only paste profile links in 'startUrls'. A ZIP code on its own is not understood."
          },
          "locations": {
            "title": "More locations (batch)",
            "type": "array",
            "description": "Optional list of extra cities to search in the same run, for example ['Austin, TX','Denver, CO']. Each city is combined with every keyword (limit 100 searches per run). One search returns at most 225 businesses on bbb.org, so adding cities is how you collect more. Leave empty for a single location.",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Country",
            "enum": [
              "US",
              "CA"
            ],
            "type": "string",
            "description": "Which bbb.org directory to search: US (United States) or CA (Canada). Defaults to US. It also sets the region of the fallback network route. It does not change pasted profile links, which already contain their country.",
            "default": "US"
          },
          "startUrls": {
            "title": "BBB profile URLs",
            "type": "array",
            "description": "Direct bbb.org business profile links to collect in full detail, for example https://www.bbb.org/us/ca/los-angeles/profile/plumber/example-1216-907682 . Use them instead of, or together with, a keyword search. Only '/profile/' pages are accepted here: search or category pages are skipped.",
            "items": {
              "type": "string"
            }
          },
          "maxResults": {
            "title": "Max businesses",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Maximum number of businesses to return across the whole run. Defaults to 100 and can be raised to 5000. Customer reviews do not count toward this number. Bigger runs automatically get more memory and faster parallel fetching. You are billed per business returned, so this is also your cost control.",
            "default": 100
          },
          "enrichDetails": {
            "title": "Full profile details",
            "type": "boolean",
            "description": "When on (default), each business is opened and its full profile is collected: accreditation date, years in business, hours, contacts with roles, licences, social links, description and payment methods. When off, only the lighter search-listing fields are returned, which is cheaper. Pasted profile links and customer reviews always include the full profile.",
            "default": true
          },
          "includeReviews": {
            "title": "Include customer reviews",
            "type": "boolean",
            "description": "When on, each business also returns its public customer reviews as separate rows (recordType 'review'): reviewer name, star rating, date, review text and the business reply. Billed per review at the review price. Turning this on also turns on full profile details. Defaults to off.",
            "default": false
          },
          "maxReviewsPerBusiness": {
            "title": "Max reviews per business",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many customer reviews to collect for each business when 'Include customer reviews' is on. Defaults to 10, maximum 100. Reviews come 10 per page, newest first. Ignored when reviews are off. Lower it to keep cost down on large lists.",
            "default": 10
          },
          "minRating": {
            "title": "Minimum BBB rating",
            "enum": [
              "Any",
              "A+",
              "A",
              "B",
              "C",
              "D",
              "F"
            ],
            "type": "string",
            "description": "Only return businesses with at least this BBB letter grade (A+ is best, F is worst). Defaults to 'Any' (no filter). Businesses without a published grade are left out when a minimum is set. Applied to each business before it is returned and billed.",
            "default": "Any"
          },
          "accreditedOnly": {
            "title": "BBB-accredited businesses only",
            "type": "boolean",
            "description": "When on, only BBB-Accredited businesses are returned and billed; all others are skipped. Defaults to off (return everything). Handy for lead lists that require accreditation.",
            "default": false
          },
          "storeRawSample": {
            "title": "Save raw page sample (debug)",
            "type": "boolean",
            "description": "Debug option. When on, the first search page and first profile page data are saved to the run's key-value store so you can inspect the source fields. Defaults to off. It does not change the dataset or the price.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Fallback network route",
            "type": "object",
            "description": "Advanced. Settings for the backup route used only when the main route cannot fetch a page. Defaults to Apify Residential proxies pinned to the chosen country, which bbb.org requires. Change only if you know why: datacenter proxies are blocked by bbb.org.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}