US Building Permit Leads Scraper (Socrata)

What this Actor scrapes

US municipal and county building-permit registries published via the Socrata SODA API (over 300 US portals at last count, including Chicago, New York, Seattle, Austin, Los Angeles, and dozens of smaller cities). The SODA API returns permit records as structured JSON rows — this Actor normalises the common fields that matter for contractor lead-gen and passes through every city-specific field in an extra dict, so you never lose data even when the schemas diverge.

Verified against: Chicago (data.cityofchicago.org / ydr8-5enu), with the same logic applicable to any Socrata-hosted permit dataset.

What we handle for you

• 🛡️ Proxy rotation via Apify Proxy — we absorb transient 429s and routing failures so your run completes even when a portal throttles a single IP.
• 🔁 Retries with exponential backoff on 429 / 503 and network errors — up to 5 attempts per request, Retry-After header honoured.
• 🧊 Normalized, typed dataset rows — Pydantic-validated, ISO-8601 dates, stable field names across all city schemas, JSON / CSV / Excel export from the Apify Console.
• 🗺️ Multi-city in a single run — pass an array of {domain, datasetId} objects and we fan out across all portals, respecting maxItemsPerDataset per source.
• 💰 Pay-Per-Event pricing — you pay only for permit records that land in your dataset. No data, no charge (beyond the small actor-start fee).

Use cases

• HVAC / roofing / solar contractor lead lists — filter by permit type (new construction, re-roof, HVAC installation) and harvest the applicant or contractor contact frame for outbound sales.
• Contractor-lead resellers — run nightly on multiple city datasets, normalize to a single schema, and deliver fresh permit leads to clients via the Apify API or webhook.
• Valuation monitoring — pull permits above a dollar threshold in a target ZIP code to watch development activity in a neighborhood.
• Construction analytics — aggregate permit counts by type, date, and district to report on building-activity trends for real-estate investors or municipalities.
• CRM enrichment pipeline — match permit applicant names or addresses against your existing contact records to surface warm leads before the competition does.

Input

Paste this into the Apify Console, or send it as the run input over the API. Proxy settings are on by default; you rarely need to touch them.

{
  "datasets": [
    {
      "domain": "data.cityofchicago.org",
      "datasetId": "ydr8-5enu",
      "label": "Chicago"
    }
  ],
  "issuedAfter": "2024-01-01",
  "maxItemsPerDataset": 1000,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}

Output

One row per result, schema-validated before it is written. Export JSON, CSV, Excel or XML from the run, or read it over the API.

source_domaindataset_idsource_labelpermit_idpermit_typestatuswork_descriptionissue_dateapplication_dateaddressstreet_numberstreet_namecitystatepostal_codevaluation

{
  "source_domain": "data.cityofchicago.org",
  "dataset_id": "ydr8-5enu",
  "source_label": "Chicago",
  "permit_id": "100987654",
  "permit_type": "PERMIT - NEW CONSTRUCTION",
  "status": "permit issued",
  "work_description": "ERECT A 2-STORY SINGLE FAMILY RESIDENCE",
  "issue_date": "2024-03-15",
  "application_date": "2024-01-10",
  "address": "1234 N MAIN ST, Chicago, IL 60614",
  "street_number": "1234",
  "street_name": "MAIN",
  "city": "Chicago",
  "state": "IL",
  "postal_code": "60614",
  "valuation": 350000.0,
  "fee_paid": 1850.0,
  "contractor_name": "ABC CONSTRUCTION LLC",
  "contractor_license": "LIC-2024-001",
  "applicant_name": "Jane Smith",
  "latitude": 41.9021,
  "longitude": -87.6346,
  "extra": {
    "review_type": "STANDARD PLAN EXAMINATION",
    "reported_cost": "350000"
  }
}

Pricing

You pay only for results that land. Cap any run with maxTotalChargeUsd. See pricing & billing for worked examples.

Limitations

• Socrata schema divergence — every city publishes slightly different column names. The Actor maps the most common field names (Chicago, Seattle, LA, etc.) but may miss aliases in less common portals. Unknown columns land in extra.
• Rate limits — Socrata portals are publicly throttled. Very large pulls (maxItemsPerDataset=0 on a 500k-row dataset) may be paced across multiple pages; expect runs of 5–15 minutes for large datasets.
• Authentication not supported — all supported portals require no API key on the public endpoints. Portals behind Socrata auth tokens are not currently supported.
• Not all US cities use Socrata — some municipalities use custom permit portals, Tyler Munis, or Accela. This Actor covers Socrata-hosted datasets only.