BuildZoom scraper

Platform-neutral asynchronous scraper for public BuildZoom contractor profiles and city/listing pages. Apify packaging and adapters intentionally belong to the deployment stage.

Functional input

The input is a JSON object:

• startUrls (required): non-empty list of BuildZoom profile or listing URLs; strings and { "url": "..." } objects are accepted.
• maxContractors: 1–10,000, default 100.
• maxListingPages: 1–1,000, default 10.
• concurrency: 1–50, default 5.
• requestDelaySecs: 0–60, default 0.25.
• proxyConfiguration: optional Apify Proxy settings for the HTTP requests.

Output and charging

Each successfully parsed contractor is streamed as one normalized record containing identity, contact, address, coordinates, service categories, licenses/status, permit count/history, ratings/reviews, areas served, and sourceUrl. Unavailable fields are null or empty arrays.

Immediately after the record sink accepts a contractor, the scraper emits exactly one contractor-scraped event with quantity 1. Missing (404/410) and unparseable profiles are skipped and never emit an event. Records already returned before a later run failure retain their corresponding events.

The CLI is a local contract harness; it emits record/event JSON lines to stdout:

python -m buildzoom_scraper.cli input.json

Run verification with pytest -q.

Apify usage

The released Actor writes one contractor object per successfully parsed profile to the default dataset. It charges one contractor-scraped pay-per-event unit after each contractor record is accepted; missing or unparseable profiles are skipped without a charge. The monetary event price is configured by the Actor's Apify pricing settings.

For a small test run, use one public contractor profile and set maxContractors to 1. BuildZoom page markup can change, so optional fields may be null or empty arrays and selector maintenance may occasionally be required.