Building Permit Properties and Details Scraper

What does Building Permit Properties and Details Scraper do?

This Actor reads public building-permit rows from HTTPS Socrata resource endpoints and normalizes permit, work, fee, property-location, and contact fields when the source provides them. It defaults to the City of Chicago's Building Permits dataset, whose portal documents 116 columns. It does not invent missing contact details or property attributes.

Why use this Actor?

Use the structured records to review public permit activity, project descriptions, reported costs, fees, and geographic fields. Output preserves flat fields for existing integrations and adds nested permit, property, work, fee, and contact objects. Each record includes its dataset provenance and a lead score based only on available values. This is a bounded, single-request data reader: it does not crawl detail pages or contact permit applicants.

What data can it extract?

Group	Fields when present
Permit	Source row ID, permit number, type, status, milestone, review type, application and issue dates, processing time
Work	Work type, description, permit conditions
Property	Street components, city/state context, ZIP, PIN, community area, census tract, ward, coordinates
Fees	Reported project cost, paid/unpaid/waived fees, fee subtotals and total
Contacts	Up to 15 source contact slots with role and public name/location fields; phone/email only if the selected source supplies them
Provenance and score	Dataset URL, source host, score, and HOT/WARM/COLD temperature

Fields stay absent when a source row does not provide them. The Chicago dataset's location is associated with Chicago, Illinois; its permit rows do not have separate city/state columns. Its published columns provide contact role/name/city/state/ZIP, not phone or email.

How to scrape Chicago building permits

1. Open the Actor's Input tab and keep the default Chicago endpoint, or enter another public Socrata resource endpoint.
2. Add a keyword such as ROOF if you want to search the dataset's searchable fields.
3. Set the maximum number of records and request timeout, then start the Actor.
4. Review the Dataset output. Download it as JSON, CSV, Excel, or another available format.

How much does a run cost?

Apify charges depend on your platform plan and the resources used by the run. This Actor makes one bounded dataset request, so the selected item limit and response size affect runtime and memory. Review the run's usage in Apify Console; this Actor does not promise a fixed price.

Input

See the input tab for the complete configuration. Example:

{
  "datasetUrl": "https://data.cityofchicago.org/resource/ydr8-5enu.json",
  "search": "ROOF",
  "maxItems": 100,
  "requestTimeoutSeconds": 45
}

datasetUrl must be an HTTPS /resource/<dataset-id>.json endpoint on a data.* or *.socrata.com host. search is optional and limited to 200 characters. maxItems defaults to 100 and is bounded from 1 to 1,000. requestTimeoutSeconds defaults to 45 and is bounded from 5 to 120. Optional city and state filters are applied only when the selected source has corresponding permit-level fields. They cannot filter Chicago rows because those columns are absent. Redirects are not followed. Failed runs do not create dataset records.

Output

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

Example based on a row visible in the City of Chicago dataset:

{
  "recordType": "permit_lead",
  "recordId": "permit:100123862",
  "sourceRecordId": "1697816",
  "permitId": "100123862",
  "permitType": "PERMIT - EASY PERMIT PROCESS",
  "applicationDate": "2006-07-12T00:00:00.000Z",
  "issueDate": "2006-07-12T00:00:00.000Z",
  "address": "3749 W WRIGHTWOOD AVE",
  "city": "Chicago",
  "state": "IL",
  "description": "ROOF REPAIRS",
  "permit": {
    "number": "100123862",
    "type": "PERMIT - EASY PERMIT PROCESS",
    "applicationDate": "2006-07-12T00:00:00.000Z",
    "issueDate": "2006-07-12T00:00:00.000Z"
  },
  "property": {
    "address": {
      "streetNumber": "3749",
      "streetDirection": "W",
      "streetName": "WRIGHTWOOD AVE",
      "city": "Chicago",
      "state": "IL"
    }
  },
  "work": {
    "description": "ROOF REPAIRS"
  },
  "leadScore": 15,
  "leadTemperature": "COLD"
}

The dataset contains permit records only. A source or processing failure with no permit records reports FAILED / FAILED; an empty but valid response reports SUCCEEDED / COMPLETED; and records saved before a later storage failure keep the run SUCCEEDED / PARTIAL. The OUTPUT key-value record reports standardized status and last-run counts. The five local dataset rows are historical records accumulated across runs; the saved summary's itemsStored: 2 describes its prior run, not the cumulative local dataset size.

Tips and advanced options

• Start with a small maxItems value to inspect the source's fields and response size.
• A source's own city/state fields are needed for the optional city/state filters to narrow rows.
• Keep search terms and item limits small enough for a single bounded response.
• This Actor does not use proxy rotation. It does not follow redirects, log in, or bypass site access controls.
• Check the selected portal's current license, agency terms, rate limits, and privacy rules before running it.

FAQ, support, and responsible use

Why are some fields missing? Sources expose different columns, and older permit rows can be sparse. The Actor omits absent values rather than guessing.

Why did a run fail? The endpoint may be unavailable, return invalid JSON, redirect, or contain no permit rows the Actor can identify. Check the run log and OUTPUT summary. Failure details are not written as dataset records.

Is this Actor affiliated with the City of Chicago or Socrata? No. Users must follow the selected source's terms, robots guidance, rate limits, and applicable law. The City of Chicago Data Terms of Use require secondary applications to include this notice:

This site provides applications using data that has been modified for use from its original source, www.cityofchicago.org, the official website of the City of Chicago. The City of Chicago makes no claims as to the content, accuracy, timeliness, or completeness of any of the data provided at this site. The data provided at this site is subject to change at any time. It is understood that the data provided at this site is being used at one’s own risk.

Permit contacts can contain personal information. Use such data only for a lawful, legitimate purpose and follow applicable privacy rules. For bugs or feature requests, use the Actor's Issues tab and include a run ID and a short description.