Chicago Building Permits Scraper

Scrape City of Chicago building permit records straight from the city's public Socrata Open Data API. Search and filter by permit type, status, milestone, work type, review type, community area, ward, date range, work description or contractor/owner name keyword, or reported cost / processing-time range. Look up exact permits by permit number, or pull the full permitting history for any street address.

What this actor does

• Three modes: search, byPermitNumbers, byAddress
• Rich filtering: permit type, permit status, permit milestone, work type, review type, community area (all 77), ward (1-50), issue date range, application date range, work description keyword, contractor/owner name keyword, reported cost range, processing-time range, "near me" latitude/longitude radius search
• Configurable sort: sort by issue date, application date, reported cost, or processing time, ascending or descending
• Full financial detail: building/zoning/other fees paid, unpaid, waived, and per-category subtotal, plus total fee and reported project cost
• Contractor/owner records: every contact slot (owner, general contractor, engineer, architect, etc.) attached to a permit
• Geolocation: latitude/longitude and Cook County tax parcel PIN(s)
• Empty fields are omitted

Output per permit

• rowId — unique Socrata row identifier for this permit record
• permitNumber, permitStatus, permitMilestone, permitType, reviewType
• applicationStartDate, issueDate, processingTimeDays
• streetNumber, streetDirection, streetName, fullAddress
• workType, workDescription, permitCondition
• buildingFeePaid, zoningFeePaid, otherFeePaid, subtotalPaid
• buildingFeeUnpaid, zoningFeeUnpaid, otherFeeUnpaid, subtotalUnpaid
• buildingFeeWaived, zoningFeeWaived, otherFeeWaived, subtotalWaived
• buildingFeeSubtotal, zoningFeeSubtotal, otherFeeSubtotal — per-category total (paid + unpaid + waived)
• totalFee, reportedCost
• pinList[] — Cook County tax parcel PIN(s)
• contractors[] — {type, name, city, state, zipCode} for every owner/contractor/engineer/architect on the permit
• communityArea, communityAreaName, censusTract, ward
• latitude, longitude
• sourceUrl — the exact Socrata API query for this permit
• recordType: "buildingPermit", scrapedAt

Input

Field	Type	Default	Description
mode	string	search	search / byPermitNumbers / byAddress
permitType	select	–	e.g. New Construction, Renovation/Alteration, Signs
permitStatus	select	–	Active / Complete / Expired / Revoked / etc.
permitMilestone	select	–	Workflow milestone (Inspections, Certificate of Occupancy Issued, etc.)
workType	select	–	Electrical Work, Masonry Work, Reroofing, etc.
reviewType	select	–	Express Permit Program, Easy Permit, Standard Plan Review, etc.
communityArea	select	–	One of Chicago's 77 official community areas
ward	select	–	Chicago City Council ward, 1-50
workDescriptionContains	string	–	Case-insensitive substring match, e.g. kitchen, solar
contractorNameContains	string	–	Case-insensitive substring match against any owner/contractor/architect/engineer name on the permit
issueDateFrom	string	2024-01-01	YYYY-MM-DD. Clear it to search the full history back to 2006
issueDateTo	string	–	YYYY-MM-DD
applicationDateFrom / applicationDateTo	string	–	YYYY-MM-DD
minReportedCost / maxReportedCost	int	–	USD project cost bounds
minProcessingTimeDays / maxProcessingTimeDays	int	–	Application-to-issue processing time bounds, in days
latitude / longitude	number	–	Center point for a "near me" radius search (mode=search)
radiusKm	number	1	Radius in km around latitude/longitude, 0.1-50
permitNumbers	array	–	Exact permit number(s) (mode=byPermitNumbers)
streetNumber / streetDirection / streetName	–	–	Address lookup (mode=byAddress)
sortBy	select	issueDate	issueDate / applicationStartDate / reportedCost / processingTime
sortAscending	bool	false	Oldest/lowest-first instead of newest/highest-first
maxItems	int	50	Hard cap (1-10000)

Example: recent new-construction permits in the Loop

{
  "mode": "search",
  "permitType": "PERMIT - NEW CONSTRUCTION",
  "communityArea": "32",
  "maxItems": 50
}

Example: full permit history for an address

{
  "mode": "byAddress",
  "streetNumber": 401,
  "streetDirection": "N",
  "streetName": "ABERDEEN ST"
}

Example: lookup by permit number

{
  "mode": "byPermitNumbers",
  "permitNumbers": ["100109616", "B100522727"]
}

Example: permits near a point (Loop, 1 km radius)

{
  "mode": "search",
  "latitude": 41.8781,
  "longitude": -87.6298,
  "radiusKm": 1,
  "maxItems": 50
}

Use cases

• Real estate diligence — pull the full permit history for a property before purchase
• Contractor research — track competitors' permit volume by type and community area
• Construction market intelligence — monitor new-construction and renovation trends by ward
• Compliance monitoring — flag stop-work, revoked, or suspended permits
• Journalism / civic research — analyze development patterns across Chicago's community areas

FAQ

What's the data source? The City of Chicago's public Socrata Open Data API (data.cityofchicago.org), dataset ydr8-5enu — "Building Permits". No account, cookies, or API key required.

How far back does the data go? From 2006 to the present, excluding permits voided or revoked after issuance.

Why are ward/community area sometimes missing? A small fraction of permits (under 10%) have no ward or community area recorded in the source data, or use 0 as a placeholder for "not assigned" — these are omitted rather than showing a fake 0.

What are the contractors[] entries? Every permit can list up to 15 parties (owner, general contractor, sub-contractors, engineers, architects). Each entry includes their role (type), name, and city/state/ZIP where available.

What is pinList? Cook County Property Index Number(s) (tax parcel identifiers) tied to the permit.

How fresh is the data? The city updates this dataset regularly (typically daily).

Data Source / Limitations

This actor reads exclusively from the City of Chicago's public Socrata SODA API for the Building Permits dataset (ydr8-5enu) — no scraping, no authentication, no cookies. Every filter and output field above maps to a real column in that dataset; nothing is inferred or fabricated.

What's intentionally NOT exposed, and why:

• permitCondition is not filterable. It's shown in the output when present, but the underlying values are thousands of distinct free-text inspector notes (not a finite/stable set), so it can't be a select enum, and a substring filter over it would rarely match usefully — use workDescriptionContains for keyword search instead.
• ZIP code is not a search filter. The dataset has no permit-level ZIP column; ZIP only appears per-contractor (contractors[].zipCode), which isn't a reliable proxy for the permit's own location. Use communityArea/ward for boundary-based geographic filtering, or latitude/longitude/radiusKm for a precise "near me" radius search.
• Contact/contractor "type" (e.g. ELECTRICAL CONTRACTOR, EXPEDITOR) is not a select enum filter. Each of the 15 contact slots has its own inconsistent free-text vocabulary (43+ variants observed on slot 1 alone, with spelling drift like EXPEDITOR vs EXPEDITER and MASONRY CONTRACTOR vs MASON CONTRACTOR) — not a stable finite set. Use contractorNameContains to search by name instead.
• Illinois State Plane X/Y coordinates and the internal Socrata "computed region" join columns (ZIP-code/community-area/census-tract/ward boundary IDs) are present upstream but omitted — they're redundant with latitude/longitude and communityArea/ward, which are already exposed in a directly usable form.
• No account/login-gated data. The Socrata API is fully public; there is no additional "premium" or authenticated tier of this dataset to expose.

Known upstream data quirks (not actor bugs):

• ~8 of 844K+ rows (well under 0.01%) have no reviewType recorded — filtering by reviewType will simply not match those rows, same as any other real-world null.
• A small fraction of permits (well under 10%) have no ward/communityArea recorded, or use 0 as an "unassigned" placeholder — these are omitted from the output rather than emitting a misleading 0.