Building Permit Lead Scraper

Turn recent public municipal building permits into normalized, filterable leads for contractors, suppliers, property services, real-estate research, and local market analysis.

The Actor reads credential-free public Socrata open-data portals, applies a consistent lead schema, removes duplicates, and stores a truthful run summary separately from the result dataset. Ready-made sources cover Chicago, San Francisco, Austin, Seattle, and New York City. You can also provide up to ten other public Socrata building-permit dataset URLs.

What building permit data it extracts

Each dataset item is one permit lead. Fields remain stable even when a source does not publish every value; unavailable fields are returned as null.

Field	Meaning
permitNumber, leadId	Municipal identifier and stable deduplication key
jurisdiction, permitType, permitStatus	Issuing city, permit classification, and status
issueDate, applicationDate, expirationDate	Normalized dates in YYYY-MM-DD when parseable
workDescription, propertyUse, housingUnits	Project scope and use indicators
projectValue, fees	Published valuation and permit fees in USD
address, city, state, postalCode	Project location
latitude, longitude	Published WGS84 coordinates
contactName, contactCompany, contactRole, contactPhone	Public contractor, permittee, or applicant data when available
ownerName	Public owner name or organization when available
sourceDatasetId, sourceDatasetName, sourceUrl, scrapedAt	Attribution and extraction provenance
rawData	Optional original Socrata row for audits and custom fields

The default dataset contains only permit records. Outcome and error diagnostics are written to the SUMMARY key-value-store record, so an empty or blocked run never fabricates a lead.

Good uses—and important limits

Use this Actor to build timely prospect lists for roofing, solar, HVAC, electrical, plumbing, construction materials, inspection, landscaping, insurance, or commercial real-estate workflows. It also works for local development research, construction trend analysis, and territory planning.

Do not use it as proof of legal permit status, a complete national permit database, or a substitute for the issuing authority. Municipal portals publish different fields and update on different schedules. San Francisco does not expose contractor contacts in its main permit dataset, for example, while Austin exposes richer contractor fields. New York City stores issuance dates as text and its public view can contain older records, so use a wider lookbackDays window for historical NYC permittee research; the Actor still applies the requested date filter locally. For any source with very selective filters, the Actor scans at most 10,000 rows per dataset and reports that bound in SUMMARY.

Input

Input	Default	Notes
jurisdictions	['chicago-il']	One or more supported city presets
customDatasetUrls	[]	Public HTTPS Socrata /resource/, /api/views/, or /d/ URLs
lookbackDays	30	Rolling period ending on endDate or today
startDate, endDate	unset / today	Fixed YYYY-MM-DD issue-date range; startDate overrides the rolling period
keywords	[]	Match any term across work, type, address, company, contact, and property use
permitTypes, statuses	[]	Case-insensitive contains filters using each portal's vocabulary
postalCodes	[]	Exact project ZIP/postal-code filters
minProjectValue	0	Minimum reported valuation; values above zero exclude unknown valuations
maxResults	100	Global cap from 1 to 5,000 leads for paying users; free-plan runs are capped at 5 leads even when a higher value is requested
includeContactDetails	true	Set false to suppress contact and owner fields
includeRawData	false	Include the original, source-specific row
maxRequestRetries	2	Bounded retries for 429, 5xx, and network failures

Example: recent Chicago roofing leads

{
  "jurisdictions": ["chicago-il"],
  "lookbackDays": 60,
  "keywords": ["roof", "roofing"],
  "minProjectValue": 25000,
  "maxResults": 100
}

Example: multi-city commercial projects

{
  "jurisdictions": ["austin-tx", "seattle-wa", "san-francisco-ca"],
  "lookbackDays": 90,
  "keywords": ["commercial", "retail", "office"],
  "minProjectValue": 100000,
  "maxResults": 250,
  "includeContactDetails": true
}

Example: custom public Socrata dataset

{
  "jurisdictions": [],
  "customDatasetUrls": [
    "https://data.example.gov/resource/abcd-1234.json"
  ],
  "startDate": "2026-08-01",
  "endDate": "2026-08-31",
  "maxResults": 50
}

Custom datasets must expose a recognizable issue-date field. Common Socrata field names are normalized automatically, but unusual local schemas may produce fewer populated fields. Enable includeRawData to inspect those original fields.

Output example

{
  "leadId": "austin-tx:2026-012345 BP",
  "permitNumber": "2026-012345 BP",
  "jurisdiction": "Austin, TX",
  "permitType": "Building Permit",
  "permitStatus": "Active",
  "issueDate": "2026-09-03",
  "workDescription": "Interior remodel of commercial tenant space",
  "projectValue": 250000,
  "address": "500 CONGRESS AVE",
  "city": "Austin",
  "state": "TX",
  "postalCode": "78701",
  "contactName": "Alex Builder",
  "contactCompany": "Example Construction LLC",
  "contactRole": "General Contractor",
  "contactPhone": "512-555-0100",
  "sourceDatasetId": "3syk-w9eu",
  "sourceDatasetName": "Issued Construction Permits",
  "sourceUrl": "https://data.austintexas.gov/d/3syk-w9eu",
  "scrapedAt": "2026-09-12T08:00:00.000Z",
  "rawData": null
}

API and AI-agent use

Call the Actor through the Apify API and read its default dataset:

curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~building-permit-lead-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jurisdictions":["austin-tx"],"lookbackDays":30,"maxResults":25}'

For an Apify MCP connection, choose this Actor when the user asks for public building permits, construction leads, contractor prospecting, or municipal development data in the supported cities. The stable dataset schema helps an agent map results into a CRM, spreadsheet, enrichment step, or follow-up workflow. It does not search planning applications outside the configured permit datasets.

Pay-per-event pricing

Event	Price	Charged when
Actor start	$0.0002	A run starts
Building permit lead	$0.002	One validated item is written to the default dataset

A 25-lead run costs up to $0.0502; a 100-lead run costs up to $0.2002. Empty runs incur only the start event. The Actor checks the run's maximum charge before writing each result and stops cleanly when the remaining limit cannot cover another lead. Platform usage is intended to be included in these event prices rather than passed through separately.

Free-plan protection: Apify identifies the account that started the run through APIFY_USER_IS_PAYING. When that value indicates a non-paying user, the Actor enforces a hard five-lead output limit, even if maxResults is higher. The SUMMARY record reports requestedMaxResults, effectiveMaxResults, and freePlanLimited so downstream workflows can distinguish an intentional plan limit from an empty or failed search. Paying users retain the requested maxResults (up to 5,000).

Reliability and diagnostics

The Actor calls each municipality's public Socrata metadata and resource endpoints directly with bounded timeouts, stable request headers, deterministic pagination, and error-specific retries. Calendar date fields are filtered server-side. Text dates are normalized and filtered locally. A failed city does not discard valid leads from other selected cities: successful records are preserved, the run becomes partial, and the source-specific warning appears in SUMMARY.

Outcomes are explicit:

• data: leads were delivered without warnings.
• partial: leads were delivered, but at least one source or scan bound produced a warning.
• empty: sources worked but no permit matched.
• rejected: input was invalid before billable result work.
• blocked: every requested source failed; no result event was charged.

The Actor does not solve CAPTCHAs, bypass authentication, or use private municipal systems. Public portal outages and schema changes are reported rather than hidden behind synthetic results.

Responsible use

Permit records are public government data, but public availability does not remove privacy, marketing, licensing, or consumer-protection obligations. Check each source's license and terms, honor do-not-call and anti-spam rules, minimize personal data, and use contacts only for lawful, relevant outreach. Set includeContactDetails to false when names and phone numbers are unnecessary. Always verify a permit on the linked municipal source before making a high-impact decision.

For support, include the run ID, source jurisdiction, redacted input, and the SUMMARY record. Never post tokens or personal-data exports in a public issue.