Multi-City Building Permits (Open Data API)

One call returns building permits from large US cities in a single normalized schema. Every source is an official open-data portal (Socrata/SODA, ArcGIS FeatureServer, or municipal CKAN) — see sources.md for the terms review. No HTML scraping, no logins, no Accela session automation.

Cities (v0.1)

id	Coverage	Portal
seattle	Seattle, WA	Socrata
nyc	New York City DOB NOW approved permits	Socrata
chicago	Chicago, IL	Socrata
los-angeles	Los Angeles issued permits (2020–present)	Socrata
san-francisco	San Francisco, CA	Socrata
austin	Austin, TX issued construction permits	Socrata
new-orleans	New Orleans, LA (BLDS)	Socrata
cincinnati	Cincinnati, OH	Socrata
mesa	Mesa, AZ	Socrata
montgomery-county-md	Montgomery County, MD (residential + commercial)	Socrata
norfolk	Norfolk, VA	Socrata
cambridge	Cambridge, MA (new + alterations)	Socrata
philadelphia	Philadelphia, PA	ArcGIS
denver	Denver, CO (residential + commercial)	ArcGIS
boston	Boston, MA approved building permits	CKAN
honolulu	Honolulu, HI (dump through 2025-06-30)	Socrata

Input

cities, keywords (whole word; solar* for prefix), matchMode, permitTypes (substring on type), minValuation, issuedAfter / issuedBefore (YYYY-MM-DD), issuedWithinDays (default 30 when issuedAfter omitted), socrataAppToken (secret, optional), maxResultsPerCity (200), maxResults (1000). Every field is documented in .actor/input_schema.json.

Output record

Normalized fields: permitNumber, type, status, address, valuation, issuedDate, description, contractor, city, sourceUrl, plus recordType (permit-record), source, sourceName, state, matchedKeywords, retrievedAt, and disclaimer where required (NYC, Montgomery County).

Errors never crash the run. They are written to the OUTPUT record as AUTH_ERROR, RATE_LIMITED, or SOURCE_ERROR.

Pricing (pay per event)

• permit-record (primary): one per record written to the dataset. Proposed price $0.002 (set via Apify API / Console).
• Keep apify-actor-start (synthetic). Remove apify-default-dataset-item so records aren't charged twice.
• The Actor follows the user's spending limit (eventChargeLimitReached stops the run cleanly). Events only (no "+ usage"), so it's eligible for Apify agentic payments once KYC is done.

Run

npm install
npm test                 # offline unit tests (all cities mocked)
LIVE=1 npm test          # plus a live smoke test
npm run demo             # recent permits → demo/demo-recent.json
npm start                # Actor locally (input in storage/key_value_stores/default/INPUT.json)
node src/cli.js --keywords "solar,ADU" --cities seattle,austin,los-angeles --min-valuation 10000

Demo results (live, 2026-10-05 PT)

• All cities, last 30 days, 50/city cap: 698 records in about 71 s. Chicago had one transient network error on that run (retried OK separately). Honolulu correctly returned 0 in the Sept–Oct 2026 window (dump ends 2025-06-30).
• Solar / ADU niche (solar, ADU, photovoltaic), 90-day window: see demo/demo-solar-adu.json (LA ADUs, Boston solar/PV short-form permits, Mesa ADUs, Montgomery County solar/ADU work).
• Local Actor run (Apify SDK), keywords solar,ADU on Seattle/Austin/LA/Boston: 3 records, permit-record charged 3 times (simulated).

Notes and limits

• Field coverage varies by city (not every portal publishes contractor or valuation).
• Honolulu is a fixed dump ending 2025-06-30; use an explicit issuedAfter/issuedBefore in that window.
• Disclaimers. Montgomery County and NYC disclaimer text is included in README/listing and attached to those records. Not affiliated with any government.
• Data is provided by the cities "as is"; always verify critical records on the official portal before business use.

Civic Data Tools (related Actors)

Same publisher (civic-data-tools) — useful together for agents monitoring local government:

Actor	Use when	Store
Public Bid & RFP Search	Open government bids/RFPs plus new federal contract awards (official APIs)	public-bid-search
City Council & County Agenda Search	Keyword/topic matches in council, board, and commission agendas	meeting-agenda-search

This Actor covers issued building permits. Pair agenda search for upstream land-use votes and bid search for public construction solicitations.