BBB Scraper | Better Business Bureau

Slug: fatihtahta/bbb-scraper

Overview

BBB Scraper | Better Business Bureau collects structured business records from BBB search results, category pages, and individual business profiles, including business identity, contact details, locations, service areas, categories, BBB organization metadata, ratings, accreditation signals, and relevant profile links. BBB.org is a widely used public source for business profiles, reputation indicators, and local service-provider discovery, making its data valuable for research, enrichment, monitoring, and operational reporting. The actor turns public BBB pages into repeatable JSON records that can be used in analytics tools, CRMs, data pipelines, and reporting workflows. It is designed for automated, recurring data acquisition where consistent structure and predictable output are more important than manual browsing. Results reflect the public information available at run time, enabling dependable collection workflows without making assumptions about future availability or completeness.

Why Use This Actor

• Market research and analytics: collect structured extraction outputs for category coverage, geographic distribution, BBB ratings, service areas, and business classification analysis.
• Product and content teams: build normalized business directories, vendor indexes, local-service pages, and internal research datasets from public profile attributes.
• Developers and data engineering teams: feed repeatable collection results into downstream systems, ETL jobs, warehouses, enrichment pipelines, and operational reporting flows.
• Lead generation and enrichment teams: create focused prospect lists from BBB search, category, or profile URLs with contact, location, category, and reputation attributes.
• Monitoring and competitive tracking teams: schedule recurring data acquisition to observe market movement, provider presence, profile changes, and category-level coverage over time.

Common Use Cases

• Market intelligence: monitor business coverage, category movement, ratings, locations, and service-area patterns across BBB listings.
• Lead generation: build targeted prospect lists from public BBB business profiles and category searches.
• Competitive monitoring: track public profile attributes for businesses, service providers, and organizations in specific markets.
• Catalog and directory building: populate internal databases with structured public business records.
• Data enrichment: add current public BBB attributes to CRM, BI, vendor, or analytics datasets.
• Recurring reporting: schedule periodic runs for dashboards, alerts, trend analysis, and operational review.

Quick Start

1. Choose one or more BBB search, category, or business profile URLs that define the businesses you want to collect.
2. Add those URLs to startUrls.
3. Set a small limit, such as 10, for the first validation run.
4. Run the actor in Apify Console.
5. Inspect the first dataset records to confirm the fields match your use case.
6. Increase the limit, add more BBB URLs, or schedule the actor once the output is verified.

Input Parameters

The actor accepts BBB URLs, a maximum business-record limit, and an optional Apify connection configuration.

Parameter	Type	Description	Default
startUrls	array	One or more BBB.org search result, category, or individual business profile URLs. This field defines the target scope for the run and can combine multiple BBB URL types in the same input.	-
limit	integer	Maximum number of business records to save from each BBB search or category target. Minimum value: 10.	50000
proxyConfiguration	object	Apify connection configuration for region-specific access or more controlled connection behavior.	{"useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"]}

Choosing Inputs

Use startUrls to define the scope of collection. A BBB search or category URL is useful when you want multiple businesses from a segment, while a direct business profile URL is useful when you need a specific organization. Broader BBB URLs improve discovery, and more focused BBB URLs produce more targeted datasets.

Start with a small limit to validate record shape and relevance before collecting larger datasets. Increase limit after confirming the output quality, or split work into multiple runs when you want separate datasets by geography, category, market, or monitoring segment.

Example Inputs

Search or Category Run

{
  "startUrls": [
    "https://www.bbb.org/search?find_text=Roofing%20Contractors&find_entity=10126-000&find_type=Category&find_country=USA"
  ],
  "limit": 25
}

Direct Business Profile Run

{
  "startUrls": [
    "https://www.bbb.org/us/il/danville/profile/home-improvement/u-nailed-it-contracting-llc-0724-1000021781"
  ],
  "limit": 10
}

Multi-Target Discovery Run

{
  "startUrls": [
    "https://www.bbb.org/search?find_text=Auto+Brokers&find_entity=50032-000&find_type=Category&find_loc=19901&find_country=USA",
    "https://www.bbb.org/search?find_text=Home+Improvement&find_entity=10079-000&find_type=Category&find_country=USA"
  ],
  "limit": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}

Output

Output Destination

The actor writes results to an Apify dataset as JSON records. The dataset is designed for direct consumption by analytics tools, ETL pipelines, and downstream APIs with minimal post-processing.

When multiple entity types or record shapes exist, this README documents each shape separately based on the provided Example Output.

Record Envelope And Stable Identifiers

Each output record is a business record with top-level fields such as type, id, url, name, and record_type. The recommended idempotency key is id, with url as a useful secondary key when syncing into systems that prefer URL-based identity. For repeated runs, use id to deduplicate records or upsert existing business profiles instead of creating duplicates. Stable identifiers make records easier to merge, deduplicate, and sync across repeated runs.

The source_context.source_url field identifies the BBB source URL associated with the collected record, while source_context.seed_value identifies the input seed that led to the result.

Examples

Example: business (type = "business")

{
  "type": "business",
  "id": "0724_1000021781_75268",
  "url": "https://www.bbb.org/us/il/danville/profile/home-improvement/u-nailed-it-contracting-llc-0724-1000021781",
  "name": "U Nailed It Contracting LLC",
  "record_type": "business",
  "business": {
    "business_id": "1000021781",
    "listing_id": "0724_1000021781_75268"
  },
  "contact": {
    "phone": "(217) 304-7547",
    "phones": [
      "(217) 304-7547"
    ]
  },
  "location": {
    "address": {
      "street": "440 Avenue C",
      "city": "Danville",
      "region": "IL",
      "postal_code": "61832-5510"
    },
    "coordinates": {
      "latitude": 40.121929168701165,
      "longitude": -87.64965057373047
    },
    "service_area": {
      "has_service_area": true,
      "description": "Danville and 30 miles",
      "summary": [
        "47832",
        "47847",
        "47854",
        "47875",
        "47917",
        "47918",
        "47921",
        "47928",
        "47932",
        "47949",
        "47952",
        "47958",
        "47966",
        "47969",
        "47974",
        "47975",
        "47982",
        "47984",
        "47987",
        "47991",
        "47993",
        "60924",
        "60932",
        "60939",
        "60942",
        "60949",
        "60960",
        "60963",
        "60973",
        "61801",
        "61802",
        "61803",
        "61810",
        "61811",
        "61812",
        "61814",
        "61816",
        "61817",
        "61831",
        "61832",
        "61833",
        "61834",
        "61841",
        "61844",
        "61846",
        "61847",
        "61848",
        "61849",
        "61850",
        "61852",
        "61857",
        "61858",
        "61859",
        "61862",
        "61864",
        "61865",
        "61866",
        "61870",
        "61871",
        "61873",
        "61876",
        "61877",
        "61878",
        "61883",
        "61924",
        "61932",
        "61940",
        "61942",
        "IL",
        "IN",
        "USA"
      ]
    }
  },
  "classification": {
    "primary_category": {
      "id": "10079-000",
      "name": "Home Improvement"
    },
    "categories": [
      {
        "name": "Home Improvement",
        "id": "10079-000"
      },
      {
        "name": "Roofing Contractors",
        "id": "10126-000"
      },
      {
        "name": "General Contractor",
        "id": "10035-000"
      },
      {
        "name": "Painting Contractors",
        "id": "10095-000"
      }
    ],
    "bbb": {
      "bbb_id": "0724",
      "bbb_name": "BBB of Central Illinois"
    },
    "charity": {
      "is_charity": false,
      "has_charity_seal": false,
      "is_accredited_charity": true
    }
  },
  "reputation": {
    "bbb_rating": "A+",
    "rating_score": 100.0,
    "is_bbb_member": true
  },
  "media": {
    "logo_url": "https://m.bbb.org/prod/ProfileImages/1720140e-d166-466c-9483-3a34e76d684c.jpeg"
  },
  "links": {
    "request_quote": "https://www.bbb.org/central-illinois/quote/request-u-nailed-it-contracting-llc-1000021781",
    "leave_review": "https://www.bbb.org/us/il/danville/profile/home-improvement/u-nailed-it-contracting-llc-0724-1000021781/leave-a-review",
    "business_login": "https://www.bbb.org/central-illinois/login"
  },
  "attributes": {
    "request_quote_enabled": true,
    "request_quote_url_id": 739
  },
  "source_context": {
    "seed_type": "url",
    "seed_value": "https://www.bbb.org/search?find_text=Roofing%20Contractors&find_entity=10126-000&find_type=Category&find_country=USA&page=1",
    "source_url": "https://www.bbb.org/search?find_country=USA&find_entity=10126-000&find_text=Roofing+Contractors&find_type=Category&page=1",
    "page_index": 1,
    "domain": "www.bbb.org",
    "scraped_time": "2026-05-03T22:02:51.082755+00:00"
  }
}

Field Reference

Business Record

• type (string, required): Record entity type. In the example output, this is business.
• id (string, required): Stable business record identifier and recommended idempotency key.
• url (string, required): Public BBB business profile URL.
• name (string, required): Business name.
• record_type (string, required): Record classification. In the example output, this is business.
• business.business_id (string, optional): BBB business identifier.
• business.listing_id (string, optional): BBB listing identifier.
• contact.phone (string, optional): Primary phone number when publicly available.
• contact.phones (array, optional): List of phone numbers when publicly available.
• location.address.street (string, optional): Street address.
• location.address.city (string, optional): City.
• location.address.region (string, optional): State, province, or region code.
• location.address.postal_code (string, optional): Postal code.
• location.coordinates.latitude (number, optional): Latitude coordinate.
• location.coordinates.longitude (number, optional): Longitude coordinate.
• location.service_area.has_service_area (boolean, optional): Indicates whether a service area is listed.
• location.service_area.description (string, optional): Human-readable service-area description.
• location.service_area.summary (array, optional): Service-area entries such as postal codes, regions, or countries.
• classification.primary_category.id (string, optional): Primary BBB category identifier.
• classification.primary_category.name (string, optional): Primary BBB category name.
• classification.categories (array, optional): List of BBB categories associated with the business.
• classification.categories[].name (string, optional): Category name.
• classification.categories[].id (string, optional): Category identifier.
• classification.bbb.bbb_id (string, optional): BBB organization identifier.
• classification.bbb.bbb_name (string, optional): BBB organization name.
• classification.charity.is_charity (boolean, optional): Indicates whether the record is marked as a charity.
• classification.charity.has_charity_seal (boolean, optional): Indicates whether a charity seal is shown.
• classification.charity.is_accredited_charity (boolean, optional): Indicates whether the charity accreditation flag is present.
• reputation.bbb_rating (string, optional): BBB rating, such as A+, when available.
• reputation.rating_score (number, optional): Numeric rating score when available.
• reputation.is_bbb_member (boolean, optional): Indicates BBB membership or accreditation status when available.
• media.logo_url (string, optional): Public logo image URL when available.
• links.request_quote (string, optional): Public request-quote URL when available.
• links.leave_review (string, optional): Public review submission URL when available.
• links.business_login (string, optional): Public BBB business login URL when available.
• attributes.request_quote_enabled (boolean, optional): Indicates whether request-quote functionality is available.
• attributes.request_quote_url_id (number, optional): Request-quote URL identifier when available.
• source_context.seed_type (string, optional): Type of input seed associated with the record.
• source_context.seed_value (string, optional): Input seed value associated with the record.
• source_context.source_url (string, optional): BBB source URL associated with the collected record.
• source_context.page_index (number, optional): Source page index when applicable.
• source_context.domain (string, optional): Source domain.
• source_context.scraped_time (string, optional): Collection timestamp in ISO 8601 format.

Data Quality, Guarantees, And Handling

• Structured records: results are normalized into predictable JSON objects for downstream use.
• Best-effort extraction: fields may vary by region, session, availability, or public website presentation.
• Optional fields: null-check optional fields in downstream code because public profiles can differ in completeness.
• Deduplication: use id as the strongest stable key from the output, with url as a secondary reference when needed.
• Freshness: results reflect the publicly available data at run time.
• Repeated runs: use the recommended idempotency key when syncing data into warehouses, CRMs, or search indexes.

Tips For Best Results

• Start with a small limit to validate output shape before scaling up.
• Use one BBB geography, category, or segment per run when you need cleaner segmentation.
• Use direct business profile URLs when you need specific organizations.
• Use BBB search or category URLs when the goal is broader discovery.
• Increase limit only after confirming the first records match your use case.
• Schedule recurring runs for monitoring workflows instead of relying on manual one-off exports.
• Use id for deduplication when storing records over time.

How To Run On Apify

1. Open the Actor in Apify Console.
2. Configure the available input fields for the target scope.
3. Set the maximum number of outputs to collect.
4. Click Start and wait for the run to finish.
5. Download results in JSON, CSV, Excel, or other supported formats.

Scheduling & Automation

Scheduling

Automated Data Collection

Schedule runs to keep BBB business datasets fresh for monitoring, enrichment, and reporting workflows. Recurring runs are useful when teams need updated public profile attributes without manual collection.

• Navigate to Schedules in Apify Console
• Create a new schedule, such as daily, weekly, or a custom cron schedule
• Configure input parameters
• Enable notifications for run completion
• Add webhooks for automated processing

Integration Options

• CRM enrichment: sync public BBB profile, contact, location, category, and reputation attributes into account or lead records.
• Google Sheets or Airtable: review smaller prospect lists, vendor datasets, or market samples with non-technical teams.
• Webhooks: trigger validation, notification, or ingestion workflows after each completed run.
• Data enrichment pipelines: join BBB profile attributes to existing company, vendor, or location records.
• BI dashboards: monitor category coverage, ratings, geographic distribution, and recurring collection trends.
• Warehouse exports: store repeated runs for historical analysis, deduplication, and operational reporting.

Export Formats And Downstream Use

Apify datasets can be exported or consumed by downstream systems for review, reporting, enrichment, and automated ingestion.

• JSON: for APIs, applications, and data pipelines
• CSV or Excel: for spreadsheet workflows and manual review
• API access: for automated ingestion into internal systems
• BI and warehouses: for reporting, dashboards, and historical analysis

Performance

Estimated run times:

• Small runs (< 1,000 outputs): ~3-5 minutes
• Medium runs (1,000-5,000 outputs): ~5-15 minutes
• Large runs (5,000+ outputs): ~15-30 minutes

Execution time varies based on filters, result volume, and how much information is returned per record. Highly filtered runs can finish faster, while broad discovery or detail-rich records may take longer.

Limitations

• Availability depends on what BBB.org publicly exposes at run time.
• Some optional fields may be missing on sparse or limited public records.
• Very broad searches may take longer or require higher limit values.
• Target-side changes can affect field availability, naming, or record completeness.
• Regional, account, or availability differences may change visible results.

Troubleshooting

• No results returned: check the BBB URLs, category or location spelling in the source URL, and whether the target has matching public records.
• Fewer results than expected: broaden the BBB URL scope, raise limit, or verify that the target contains enough matching public records.
• Some fields are empty: optional fields depend on what each record publicly provides.
• Run takes longer than expected: reduce scope, lower limit for validation, or split broad collection into smaller segments.
• Output changed: compare the current output with the field reference and report a small sample if support is needed.

FAQ

What data does this actor collect?

It collects public BBB business profile data, including business names, BBB profile URLs, contact details, locations, service areas, categories, BBB organization metadata, ratings, accreditation indicators, profile links, and source context when available.

Can I filter by location, category, date, price, or other criteria?

The actor accepts BBB search, category, and business profile URLs through startUrls. Use the filters available on BBB.org to create the target URL, then provide that URL as input. The input schema does not include separate date, price, sort, or radius fields.

Why did I receive fewer results than my limit?

The limit is a maximum, not a guarantee. A run may return fewer records if the supplied BBB URL has fewer matching public records or if some records do not expose enough usable information.

Can I schedule recurring runs?

Yes. Use Apify schedules to run the actor daily, weekly, or on a custom schedule for monitoring, reporting, and enrichment workflows.

How do I avoid duplicates across runs?

Use id as the primary idempotency key when storing or syncing records. You can also retain url and source_context.source_url for traceability.

Can I export the data to CSV, Excel, or JSON?

Yes. Apify datasets support common export formats including JSON, CSV, and Excel, as well as API-based access for automated ingestion.

Does this actor collect private data?

No. The actor is intended to collect publicly available BBB business information from https://www.bbb.org.

What should I include when reporting an issue?

Include the input used, the run ID, expected versus actual behavior, and a small output sample when available. Redact anything sensitive before sharing.

Compliance & Ethics

Responsible Data Collection

This actor collects publicly available business profile information from https://www.bbb.org for legitimate business purposes, including:

• Local services and vendor research and market analysis
• Lead enrichment and business-directory maintenance
• Competitive monitoring and operational reporting

Users are responsible for ensuring their use of collected data complies with applicable laws, regulations, and site terms. This section is informational and not legal advice.

Best Practices

• Use collected data in accordance with applicable laws, regulations, and the target site's terms
• Respect individual privacy and personal information
• Use data responsibly and avoid disruptive or excessive collection
• Do not use this actor for spamming, harassment, or other harmful purposes
• Follow relevant data protection requirements where applicable, such as GDPR and CCPA

Support

For help, use the Issues tab or the actor page. Include the input used with sensitive values redacted, the run ID, the expected versus actual behavior, and a small output sample when useful.