# Building Permits API: SF, Seattle, Austin & more (open data) (`gapforge/building-permit-feed`) Actor

Roofing, solar, HVAC, pool permit leads from five US cities, with contractor company where published, optional scope fields and lead score, and SF soft-story retrofit buildings. Stale city feeds are flagged and not charged. No owner, applicant or private individual contact names, phones or emails.

- **URL**: https://apify.com/gapforge/building-permit-feed.md
- **Developed by:** [GapForge](https://apify.com/gapforge) (community)
- **Categories:** Lead generation, Real estate, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 permits

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Building Permit Feed do?

It collects new building permits from official US city open-data portals and returns them in one tidy table: what
is being built, where, the estimated cost and when the permit was issued. It reads only city datasets whose own
metadata states a public-domain or open licence, and it checks that licence again on every run. Each row says when
the city last updated its feed. A city whose feed has not been updated in 30 days gets a free notice row and is not
charged. It never outputs owner, applicant or private-individual contact names, phones or emails, and it does not copy
the cities' free-text work descriptions. Contractor company, trade, business address, business phone and licence
numbers are included where the source publishes them and the company name passes a business-marker rule.

Contractors, roofers, solar and HVAC installers, building-supply sales teams and real-estate analysts use permit
data to find new projects. Each city publishes its own columns in its own way; this tool puts them all in one shape.

### Which cities are covered?

| City | Licence | Updates |
|---|---|---|
| San Francisco, CA | PDDL | Daily |
| Seattle, WA | Public domain | Daily |
| Austin, TX | Public domain (US gov.) | Daily |
| Cambridge, MA | PDDL | Daily |
| Cincinnati, OH | Public domain | Daily |

"Updates" is the publishing frequency the city states for its dataset. The tool reads the real last-update time on
each run and writes it into `cityDataUpdatedAt`.

### What data do you get?

One row per permit record. Cincinnati sometimes issues several records under one permit number (for example an excavation record and a building record); each comes as its own row, with its own `id` and cost.

- `city`, `state`
- `permitNumber`: the city's permit number (`id` is `city:permitNumber`; for Cincinnati `city:permitNumber:recordType`)
- `permitType`: `new_construction`, `alteration`, `demolition`, `electrical`, `plumbing`, `mechanical`, `roof`,
  `solar` or `other`, on the same scale for every city
- `permitTypeRaw`, `workClass`: the city's own coded type and class of work, where it publishes them (categories
  only, never free text)
- `status`: the city's current status for the permit
- `appliedDate`, `issuedDate`, `expiresDate`, `completedDate`: YYYY-MM-DD, empty where the city does not publish them
- `siteLocation`, `zip`, `latitude`, `longitude`: where the work is
- A San Francisco permit that covers several lots comes once, at the address the city flags as the primary address; the other parcels are listed in `additionalParcelIds`.
- `estimatedCost`: the estimated cost in USD as the city publishes it
- `housingUnitsAdded`: housing units the permit adds, where the city publishes an added count (Seattle) or proposed and existing counts (San Francisco); empty for Austin, Cambridge and Cincinnati.
- `contractorCompany`: taken only from a company or firm column, and only when the name carries a business marker such
  as LLC, Inc, Corp, Co, Ltd, LP or Construction; otherwise empty. Names that are only OWNER or Owner Builder are
  left empty. Where available. San Francisco contacts: only a firm whose role is contractor is used; a payor, expediter,
  architect, engineer or other role is never written into the contractor fields.
- `contractorTrade`: the contractor's trade or licence class as the city publishes it, only when `contractorCompany` is filled. Where available.
- `contractorBusinessAddress`: the firm's business address as the city publishes it, only when `contractorCompany` is filled. Where available.
- `contractorBusinessPhone`: the firm's business phone as the city publishes it, only when `contractorCompany` is filled. Where available. These numbers are not checked against Do-Not-Call lists; anyone who places calls must follow the TCPA and similar rules.
- `contractorLicenseNumbers`: licence numbers as the city publishes them, semicolon-separated if more than one, only when `contractorCompany` is filled. Where available.
- `parcelId`: the city's parcel id in its own format (San Francisco block and lot, Austin TCAD id, Cambridge map-block-lot, Cincinnati parcel number)
- `siteCity`, `siteState`: the city and state of the site address as the city publishes them (Seattle, Austin, Cincinnati)
- `jurisdiction` (Austin, Cincinnati), `councilDistrict` (San Francisco supervisor district, Austin council district), `neighborhood` (San Francisco, Cincinnati)
- `propertyClass`: residential or commercial (Seattle, Austin); `permitClass`: the city's own permit class (Austin, Cincinnati)
- `statusDate`: the date of the current status, YYYY-MM-DD (San Francisco, Austin)
- `existingUse`, `proposedUse`: the use of the property before and after the work, in the city's own labels (San Francisco and Cambridge; Cincinnati publishes the proposed use)
- `stories`: stories after the work (San Francisco, Austin, Cambridge); `constructionType`: the construction type code (San Francisco, Cambridge)
- `existingUnits`, `proposedUnits`: dwelling units on the property before and after the work (San Francisco, Cambridge)
- `housingUnitsRemoved`, `housingUnitsNet`: housing units removed and the net change in units (Seattle)
- `housingUnitsOnProperty`: housing units in the building or on the property, a count and not units added (Austin, Cincinnati)
- `newAddedSqft`: square feet added (Austin, Cambridge); `grossSqft`: gross or total square feet (Cambridge, Cincinnati)
- `buildingCost`, `electricalCost`, `plumbingCost`, `mechanicalCost`: the trade split of the job value in USD (Austin, Cambridge)
- `architectCompany`: Cambridge's architecture firm, filled only when the name carries a business marker such as LLC, Inc or Corp; otherwise empty
- `cityPermitUrl`: the link to the permit's page on the city's own permit system (Seattle, Austin; Cincinnati links to the county's permit page). The tool outputs the link, not the page, and those pages can show more than this tool outputs.
- `cityFields`: facts that one city alone publishes, under the city's own column name; empty values are left out. Text values are short codes or labels of at most 60 characters, checkboxes are true or false.
  - San Francisco: `permit_type`, `permit_creation_date`, `approved_date`, `number_of_existing_stories`, `plansets`, `existing_occupancy`, `proposed_occupancy`, `existing_construction_type` and its label, `proposed_construction_type` label, `last_permit_activity_date`, `application_submission_method`, `point_source`, `record_id`, `data_as_of`
  - Seattle: `permittypemapped`, plan-review days and dates (`totaldaysplanreview`, `daysinitialplanreview`, `daysplanreviewcity`, `daysoutcorrections`, `numberreviewcycles`, `initialreviewcompletedate`, `planreviewcompletedate`, `readytoissuedate`), `dependentbuilding`, `housingcategory`
  - Austin: `permittype`, `condominium` and `certificate_of_occupancy` (yes or no), `issue_method`, `total_existing_bldg_sqft`, `remodel_repair_sqft`, `total_valuation_remodel`, `project_id`, `masterpermitnum`, `total_lot_sq_ft`
  - Cambridge: the checkbox answers of the permit form (for example `floor_area_change`, `exterior_change`, `drains`, `storm_sewer`, `bza`, `planning_board`, `condo_association`), `gas_cost`, `fire_prevention`, `building_height_feet`, `conditioned_floor_area`, `viewpoint_id`, parking counts, commercial use classes and FEMA answers
  - Cincinnati: `statuscurrentmapped`, `permittype`, `workclass`, `fee`
- `sourceUrl`, `sourceDatasetId`, `sourceLicence`, `cityDataUpdatedAt`, `retrievedAt`: where the row came from; `sourceUrl` returns this row's own source record
- `changeType`: `snapshot` in a normal run; `new` or `changed` in only-new mode
- `type`: `permit`, or `notice` for a free row that says why a city delivered nothing (`noticeCode`, `message`)

Left out on purpose: owner, applicant, contractor-person, filing-representative and private-individual contact names,
phones and emails, and the free-text descriptions. A sole proprietor's name, phone or address that lacks a business
marker is treated as personal and left empty. Also left out: unit numbers, signatures, owner-occupied answers, free-text
form answers, columns the city leaves almost empty, and columns that repeat a fact already in the row. The tool asks each city portal only for the columns it maps. The one
exception is the work description, which is read in memory to recognise solar and roof work and is never saved.
San Francisco firm fields come from the city's separate Building Permits Contacts dataset (PDDL).

### How to use it (step by step)

1. Open the Input tab. The prefilled run reads two cities and returns 5 permits from each.
2. Pick your **Cities** and the issue dates (**Issued on or after**, **Issued on or before**). Empty dates mean the
   last 30 days.
3. Optional: pick **Permit types** and a **Minimum estimated cost (USD)**.
4. For a daily or weekly feed, turn on **Only new since last run** and add a schedule. The first run delivers the
   newest permits up to **Maximum permits per city**. Later runs deliver permits not delivered before, plus permits
   whose facts changed (for example a new status). When more permits match than the limit allows, the newest come
   first and the others come in later runs while they are still inside the date window.
5. Click **Start**. Results appear in the Output tab and can be exported as JSON, CSV or Excel.

### How much does it cost?

You pay per permit delivered (the price line shows "Permit"):

- Free plan: $1.50 per 1,000 permits ($0.0015 each)
- Starter plan: $1.00 per 1,000 permits
- Scale plan: $0.85 per 1,000 permits
- Business plan and higher: $0.70 per 1,000 permits

Apify also charges its small start fee of $0.00005 per run. Notice rows are free, and so are cities whose feed is
stale or cannot be read. A permit is charged only after it is saved to your dataset.

Examples:

- 1,000 permits cost $1.50 on the Free plan, $1.00 on Starter, $0.85 on Scale and $0.70 on Business, plus the start fee.
- A daily only-new run that finds 40 new permits costs about $0.06 on the Free plan.
- Apify's free plan includes $5 of monthly credit, enough for 3,333 permits in one run.

The tool stops cleanly at the maximum charge you set for the run and says so in the status message.

### Input example

```json
{
  "cities": ["seattle", "austin"],
  "issuedAfter": "2026-10-01",
  "issuedBefore": "2026-10-31",
  "permitTypes": ["solar"],
  "minEstimatedCost": 20000,
  "onlyNewSinceLastRun": false,
  "maxPermitsPerCity": 100
}
```

### Output example

```json
{
  "type": "permit",
  "id": "seattle:6990004-CN",
  "city": "Seattle",
  "state": "WA",
  "permitNumber": "6990004-CN",
  "permitType": "solar",
  "permitTypeRaw": "Addition/Alteration",
  "workClass": "Single Family/Duplex",
  "status": "Issued",
  "appliedDate": null,
  "issuedDate": "2026-10-22",
  "expiresDate": null,
  "completedDate": null,
  "siteLocation": "4000 EXAMPLE PL",
  "zip": "98115",
  "latitude": 47.68,
  "longitude": -122.3,
  "estimatedCost": 31000.0,
  "housingUnitsAdded": null,
  "contractorCompany": "DELTA SOLAR LLC",
  "contractorTrade": null,
  "contractorBusinessAddress": null,
  "contractorBusinessPhone": null,
  "contractorLicenseNumbers": null,
  "parcelId": null,
  "additionalParcelIds": null,
  "siteCity": "SEATTLE",
  "siteState": "WA",
  "jurisdiction": null,
  "councilDistrict": null,
  "neighborhood": null,
  "propertyClass": "Residential",
  "permitClass": null,
  "statusDate": null,
  "existingUse": null,
  "proposedUse": null,
  "stories": null,
  "constructionType": null,
  "existingUnits": null,
  "proposedUnits": null,
  "housingUnitsRemoved": null,
  "housingUnitsNet": 0,
  "housingUnitsOnProperty": null,
  "newAddedSqft": null,
  "grossSqft": null,
  "buildingCost": null,
  "electricalCost": null,
  "plumbingCost": null,
  "mechanicalCost": null,
  "architectCompany": null,
  "cityPermitUrl": "https://services.seattle.gov/portal/permit/6990004-CN",
  "cityFields": {
    "permittypemapped": "Building",
    "numberreviewcycles": 1,
    "readytoissuedate": "2026-10-20",
    "dependentbuilding": "N",
    "housingcategory": "Single Family"
  },
  "sourceUrl": "https://data.seattle.gov/resource/76t5-zqzr.json?permitnum=6990004-CN",
  "sourceDatasetId": "76t5-zqzr",
  "sourceLicence": "Public Domain",
  "cityDataUpdatedAt": "2026-11-15T00:00:00Z",
  "retrievedAt": "2026-11-16T15:00:00Z",
  "changeType": "snapshot"
}
```

### Integrations and API

Run it from the Apify API, the Apify CLI or the official clients for Python and JavaScript, on a schedule, or from
automation tools that connect to Apify (for example Make, n8n or Zapier). Webhooks can notify your system when a run
finishes. AI agents can call it through the Apify MCP server; the input and output schemas tell them what to send and
what comes back.

### FAQ

**Is it legal?** The tool reads only official city open-data datasets whose own metadata states a public-domain or
open licence (PDDL, Public Domain, Public Domain U.S. Government). The licence is written into `sourceLicence` on each
row and checked again on every run; a city whose licence changed is skipped with a free notice row. The tool uses no
account and no proxy, names itself honestly in its user agent, waits at least half a second between requests to the
same city portal (or the portal's robots.txt Crawl-delay if longer), and outputs no private-individual contact data.
Cincinnati is read only from the public-domain dataset on data.cincinnati-oh.gov, not from the municipal website.
East Baton Rouge Parish is not covered: the portal Terms of Service limit the site materials, including datasets, to
non-commercial personal use and bar resale, so it was removed in version 1.1. Business phones, where included, are not checked against Do-Not-Call lists; anyone who places calls must follow the TCPA and similar rules. This is not
legal advice.

**Why is a city missing from my results?** Open the Notices view or read the status message. A notice row names the
city and the reason: `STALE_FEED` (the city has not updated the dataset in 30 days), `CITY_UNAVAILABLE` (the city
portal did not answer, or kept answering HTTP 429), `LAYOUT_CHANGED` (the city changed its columns), `LICENCE_CHANGED`,
`NO_COST_COLUMN` (you set a minimum cost and the city publishes no cost) or `SCAN_LIMIT`. Notice rows are free. A city
can also simply have no permit that matches your dates and filters.

**How do I cap spend?** Set **Maximum permits per city**: you never pay for more permits than that per city. You can
also set a maximum charge for the run in the run options; the tool stops cleanly when it is reached.

**Is this affiliated with the cities?** No. This tool is not affiliated with or endorsed by any city or by the company
that hosts their open-data portals. It reads data the cities publish for public reuse.

**Something looks wrong.** Open an Issue on this page with the run ID. We reply within one business day and fix confirmed bugs in the next build.

### Limits

- Five cities in this version. Chicago, New York City and Los Angeles are not covered. East Baton Rouge Parish was removed in 1.1 because the portal Terms of Service do not allow commercial reuse.
- No permit descriptions and no person fields (see "What data do you get?").
- City portals answer without a key, but they can slow down requests that have none (HTTP 429). The tool waits and
  tries each request up to 5 times; a city that still refuses gets a free notice row and is charged nothing. Your
  own Socrata app token (optional input) makes this less likely.
- At most 5,000 permits per city per run, and at most 50,000 rows read per city per run.
- 512 MB is the lowest memory setting the tool allows, and it runs at that setting.
- Field coverage differs by city: a field the city does not publish is empty. Seattle, Cambridge and Cincinnati
  publish a contractor company name; Austin also publishes trade, business address and business phone; San Francisco
  also publishes firm address and licence numbers (from the contacts dataset). All of these are filled only when the
  company name passes the business-marker rule. Names that are only OWNER or Owner Builder are left empty. Parcel,
  use, size, unit, trade-cost and permit-page fields follow the same rule: each city fills the ones it publishes
  (see "What data do you get?").
- Solar and roof are recognised from the city's own type codes or from words in its work description, so a permit
  whose description does not mention the work is typed by its code only.

# Changelog

This Actor's version history is a separate document: https://apify.com/gapforge/building-permit-feed/changelog.md

# Actor input Schema

## `cities` (type: `array`):

The cities to read. Each one is an official city open-data feed whose own metadata states a public-domain or open licence.

## `issuedAfter` (type: `string`):

Earliest issue date (YYYY-MM-DD). Empty means 30 days before "Issued on or before".

## `issuedBefore` (type: `string`):

Latest issue date (YYYY-MM-DD), included. Empty means today (UTC).

## `permitTypes` (type: `array`):

Keep only these types. Empty keeps every type. Solar and roof also match when the city's own work description names solar panels or roofing (the description itself is not output).

## `minEstimatedCost` (type: `integer`):

Keep only permits whose city-published estimated cost is at least this amount. A permit without a cost is left out, and a city that publishes no cost column is skipped and named in the run status.

## `onlyNewSinceLastRun` (type: `boolean`):

Deliver (and charge for) only permits that earlier runs with the same state key have not delivered, plus permits whose facts changed. Made for scheduled runs.

## `maxPermitsPerCity` (type: `integer`):

Deliver at most this many permits from each city, newest issue date first. You pay per permit delivered, so this also caps the cost.

## `stateKey` (type: `string`):

Name of the memory used by "Only new since last run". Use a different key for each schedule. Letters, digits, dashes and underscores.

## `socrataAppToken` (type: `string`):

City portals may slow down requests without a token. You can create a free app token with the portal and paste it here; it is sent only to the city portals this tool reads and is never logged or stored in the output.

## Actor input object example

```json
{
  "cities": [
    "seattle",
    "san-francisco"
  ],
  "onlyNewSinceLastRun": false,
  "maxPermitsPerCity": 5,
  "stateKey": "default"
}
```

# Actor output Schema

## `overview` (type: `string`):

Permits with city, permit number, type, issue date, estimated cost and site.

## `source` (type: `string`):

Where each row came from: dataset id, licence and when the city last updated it.

## `allFields` (type: `string`):

Every field of every row in the dataset, as defined by the dataset schema.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "cities": [
        "seattle",
        "san-francisco"
    ],
    "maxPermitsPerCity": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("gapforge/building-permit-feed").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "cities": [
        "seattle",
        "san-francisco",
    ],
    "maxPermitsPerCity": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("gapforge/building-permit-feed").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "cities": [
    "seattle",
    "san-francisco"
  ],
  "maxPermitsPerCity": 5
}' |
apify call gapforge/building-permit-feed --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gapforge/building-permit-feed"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/taLXgPQnTgHL0twH5/builds/RRVZui3ZVky8Z28aM/openapi.json
