# Seattle WA Building Permits - New Permit Feed (`themartygriffin/seattle-building-permits-feed`) Actor

New City of Seattle building permits since your last run: residential and non-residential new builds, additions, alterations, tenant improvements and demolitions, filtered by type, ZIP, work type, cost or keyword. Each permit has the city's estimated project cost, address and coordinates.

- **URL**: https://apify.com/themartygriffin/seattle-building-permits-feed.md
- **Developed by:** [Marty Griffin](https://apify.com/themartygriffin) (community)
- **Categories:** Real estate, Business
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$5.00 / 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.

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

## Seattle Building Permits — New Permit Feed

New City of Seattle construction permits since your last run: one clean record per permit, with the
address, the city's estimated project cost, coordinates, housing units and full status.

Built for contractor lead lists, supplier prospecting, real-estate research and market monitoring —
run it on a schedule and each run returns only what is new since the last one.

### Quick start

Click **Start** and leave the form alone: the default `backfill` mode with `lookback_days: 30`
returns the last month of permits and saves your position. Schedule it with mode `new` to get only
permits issued since the previous run.

| Mode | What it does | Charged |
|---|---|---|
| `backfill` | Returns permits issued in the last `lookback_days` (1–365) days and saves the watermark. Start here. | Yes, one event per permit you have never been charged for |
| `new` | Returns permits not reported to you by an earlier run. Needs saved state: a first run with no `backfill` behind it returns an empty dataset and charges nothing. | Yes, for permits new to you |

Both modes are safe to repeat. A permit you have already been charged for is never charged again —
not under another `state_key`, not with `include_already_reported` on, and not after a crashed run.

### What you get

One dataset record per permit:

| Field | Meaning |
|---|---|
| `permit_number` | Seattle's permit number, e.g. `7130375-CN`. Unique across the dataset, and the identity used for billing. |
| `issue_date`, `applied_date`, `expires_on` | Dates the permit was issued, applied for and expires (`YYYY-MM-DD`). |
| `permit_type` | `Building`, `Demolition`, `Roof` or `Grading`. |
| `permit_type_detail` | The work type: `New`, `Addition/Alteration`, `Demolition`, `Tenant Improvment`, `Temporary`, `Change of Use Only - No Construction`. |
| `permit_class` | `Residential` or `Non-Residential`, as the city maps it. |
| `permit_class_detail` | The city's own class string, e.g. `Single Family/Duplex`, `Commercial`. |
| `construction_class` | Normalised work class: `new_construction`, `addition`, `alteration`, `tenant_improvement`, `demolition`, `other`. |
| `is_new_construction` | `true` for brand-new construction permits. |
| `work_description` | The scope of work, as filed. |
| `address`, `city`, `state`, `zip` | The filed address (Seattle, WA and its ZIP). |
| `latitude`, `longitude` | Coordinates, on 99.6% of permits. |
| `valuation` | The city's **estimated project cost** in USD. Published on 100% of permits. |
| `housing_units`, `housing_units_added`, `housing_units_removed` | Net housing units on the permit, when it changes them. |
| `housing_category` | The city's housing category, e.g. `Single-Family Add/Alt`, `Commercial Add/Alt`. |
| `status`, `completed_on` | Current status (`Issued`, `Completed`, `Withdrawn`, …) and completion date where the city has one. |
| `contractor_company` | The contractor **when the city publishes one** — see the fill rates below. |
| `related_mup` | Related master use permit number, where the city links one. |
| `permit_url` | Link to the permit's public page on the Seattle Services Portal. |
| `first_seen_at` | When this Actor first returned the permit to you. |

### Input

| Field | Notes |
|---|---|
| `mode` | `backfill` (default) or `new`. |
| `lookback_days` | Backfill window, 1–365. Default 30. |
| `include_already_reported` | Backfill only. Re-emits permits you already have, free. Default off. |
| `permit_types` | `Building`, `Demolition`, `Roof`, `Grading`. Empty = all. |
| `permit_classes` | `Residential`, `Non-Residential`. Empty = both. |
| `work_types` | `New`, `Addition/Alteration`, `Demolition`, `Tenant Improvment`, `Temporary`, `Change of Use Only - No Construction`. Empty = all. |
| `min_valuation`, `max_valuation` | Keep permits whose estimated project cost is in range. Seattle publishes a cost on virtually every permit, so this filter rarely drops rows. |
| `zip_codes` | 5-digit ZIPs. Empty = all. |
| `keywords` | Substring match (case-insensitive) on the work description: `solar`, `ADU`, `restaurant`, `tenant improvement`. |
| `max_results` | Cap on permits **charged** in one run (default 1000). Free re-reports do not count. |
| `state_key` | Name of the saved watermark. Use one per scheduled filter set. |

### Billing

Pay per event: **$5.00 per 1,000 permits returned**, billed once per permit the first time it is
written to your dataset. 1,000 permits cost **$5.00**; a permit you have already been billed for is
free forever, including when it is returned again. A run that finds nothing new costs nothing, and
the filter, lookback and mode inputs are free.

### Data source

City of Seattle Open Data Portal, dataset `76t5-zqzr` — *Building Permits*
(`https://data.seattle.gov/resource/76t5-zqzr.json`). Public record, published by the City of Seattle.
The Actor reads only the columns it returns, pages 1,000 rows at a time in issue-date order using
keyset pagination on `(issueddate, permitnum)`, and never edits the source.

### Freshness and volume — measured, not claimed

All figures measured on **2026-11-16** from a Linux host against the live Socrata endpoint:

- **486 permits** were issued in the 30 days from 2026-10-17 (dataset range 2026-10-18 →
  2026-11-13). That is about **16 permits per weekday** — a small, high-value feed, not a firehose.
- A full 30-day scan is **one request and 1.0 s**. A full **365-day backfill is 6,411 permits, 7
  pages, 27.3 s**, and the paged scan returned exactly `count(*)` = `count(distinct permitnum)`, so
  no duplicates and no gaps.
- The newest issue date in the dataset was **2026-11-13**, i.e. the feed ran one to three days behind
  the calendar on a Monday. Seattle issues permits on weekdays only.
- The dataset holds **194,311 permits** in total; the earliest `issueddate` is a placeholder
  `1900-01-01` row, so treat the first few records of any very long backfill as suspect.
- Split of the 30-day window: **360 residential / 126 non-residential**; by work type
  **Addition/Alteration 308, New 101, Demolition 24, Tenant Improvment 18, Temporary 9,
  Change of Use 2**, and 24 with no work type published.

### Column fill rates — what is actually there

Measured on the 486 permits issued from 2026-10-17 to 2026-11-13:

| Column | Filled | Share |
|---|---|---|
| `estprojectcost` → `valuation` | 486 / 486 | **100%** |
| `description`, `statuscurrent`, `permitclass(es)`, `expiresdate`, `originaladdress1`, `housingcategory`, `link` | 486 / 486 | **100%** |
| `latitude` / `longitude` | 484 / 486 | **99.6%** |
| `applieddate` | 469 / 486 | **96.5%** |
| `permittypedesc` | 462 / 486 | **95.1%** |
| `originalzip` | 449 / 486 | **92.4%** |
| `housingunitsadded` / `housingunitsremoved` | 316 / 486 | **65.0%** |
| `housingunits` (non-zero) | 108 / 486 | **22.2%** |
| `contractorcompanyname` | 21 / 486 | **4.3%** |
| `completeddate` | 9 / 486 | **1.9%** |
| `relatedmup` | 3 / 486 | **0.6%** |
| `zoning`, `dwellingunittype` | 0 / 486 | **0%** |

**The contractor is not part of this listing's promise.** Over the last 365 days the city published a
contractor company on 530 of 6,411 permits (**8.3%**), and on under 5% of current permits. The field
is returned when it exists, and is `null` otherwise — do not buy this Actor for contractor names.
`zoning` and `dwellingunittype` exist in the dataset but are empty on every current row, so they are
not returned at all.

### Caveats worth knowing before you buy

- **Valuation is the city's estimated project cost, not a verified contract price.** It is present on
  essentially every permit, including 4 permits in the last 30 days that state `0`.
- **Contractor coverage is sparse** (~4% of current permits, 8.3% over the last year). See above.
- **`permitnum` is the identity.** Seattle reuses a number for a permit's revisions rather than
  issuing a new permit number, so one number is one record and one charge.
- **Addresses are the city's filed address**, not a normalised postal address; a few permits have no
  city/state filled even though the address and ZIP are present.
- **The city's spelling is preserved**: `Tenant Improvment` is how Seattle publishes it, and the
  `work_types` filter expects that spelling.
- The data covers permits inside Seattle city limits. King County and neighbouring cities publish
  their own datasets and are not included.

# Actor input Schema

## `mode` (type: `string`):

'backfill' returns permits issued in the last N days and saves the state; it is the default, so a first run returns real results. 'new' returns only permits not reported by an earlier run and needs saved state - it exits with an empty dataset if you have never run 'backfill'.

## `lookback_days` (type: `integer`):

Backfill only. Return permits issued in the last this many days (1 to 365, the same span the Actor remembers reported permits for). Seattle issues permits on weekdays only, so the newest 1-3 days can be missing on a Monday.

## `include_already_reported` (type: `boolean`):

Backfill only. Controls whether permits an earlier run already reported appear in the dataset again. Off (the default): they are left out. On: they are returned again. It never changes what you are charged: a permit is billed once, the first time it is reported, and re-reported permits are free. Permits are remembered for 365 days of issue dates, which covers the longest lookback.

## `permit_types` (type: `array`):

Exact dataset values: 'Building', 'Demolition', 'Roof', 'Grading'. Empty = all.

## `permit_classes` (type: `array`):

Exact dataset values: 'Residential' or 'Non-Residential'. Empty = both.

## `work_types` (type: `array`):

Exact dataset values: 'New', 'Addition/Alteration', 'Demolition', 'Tenant Improvment' (the city's spelling), 'Temporary', 'Change of Use Only - No Construction'. Empty = all.

## `min_valuation` (type: `integer`):

Skip permits whose estimated project cost is below this. Seattle publishes a cost on every permit, so this filter rarely drops rows.

## `max_valuation` (type: `integer`):

Skip permits whose estimated project cost is above this.

## `zip_codes` (type: `array`):

5-digit ZIP codes, e.g. 98118. Empty = all.

## `keywords` (type: `array`):

Return a permit if its work description contains ANY of these text fragments (case-insensitive), e.g. solar, ADU, restaurant, tenant improvement. This is a substring match, so 'ADU' also matches longer words that contain it.

## `max_results` (type: `integer`):

Safety cap on charged permits (never reported before) per run. Permits returned again for free do not count. Default 1000. Oldest first. The rest are picked up on the next 'new' run.

## `state_key` (type: `string`):

Name of the saved watermark. Use a different name for each filter set you schedule, because 'already reported' is tracked per name, not per filter set.

## Actor input object example

```json
{
  "mode": "backfill",
  "lookback_days": 30,
  "include_already_reported": true,
  "max_results": 1000,
  "state_key": "default"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "mode": "backfill",
    "lookback_days": 30,
    "include_already_reported": true,
    "max_results": 1000,
    "state_key": "default"
};

// Run the Actor and wait for it to finish
const run = await client.actor("themartygriffin/seattle-building-permits-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 = {
    "mode": "backfill",
    "lookback_days": 30,
    "include_already_reported": True,
    "max_results": 1000,
    "state_key": "default",
}

# Run the Actor and wait for it to finish
run = client.actor("themartygriffin/seattle-building-permits-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 '{
  "mode": "backfill",
  "lookback_days": 30,
  "include_already_reported": true,
  "max_results": 1000,
  "state_key": "default"
}' |
apify call themartygriffin/seattle-building-permits-feed --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,themartygriffin/seattle-building-permits-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/4y8A5xf8v1XW9CiS6/builds/pxlLmKol0TEgUp6Uh/openapi.json
