# US Building Permits Scraper | Construction & Real Estate Leads (`ahmed_jasarevic/us-scraper`) Actor

Find fresh US construction leads from public building permits. Scrape any Socrata city portal and extract permit details, project value, contractor, owner, address, coordinates and work description. Filter by date, trade, keywords and project value.

- **URL**: https://apify.com/ahmed\_jasarevic/us-scraper.md
- **Developed by:** [Ahmed Jasarevic](https://apify.com/ahmed_jasarevic) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## US Building Permits Scraper (Socrata/SODA API)

Scrapes building and construction permits from any US city's open data portal powered by Socrata (SODA API). Extracts permit details, contractor leads, owner information, and property coordinates for roofing/solar/HVAC contractors, building material suppliers, real estate investors, and construction market analysts.

### Why use this Actor?

- **Lead generation**: Every issued permit signals a construction job about to start — a buyer for materials, equipment, subcontracting, or financing.
- **Multi-city coverage**: Works with any Socrata open-data portal (NYC, LA, Chicago, Austin, SF, and hundreds more).
- **Public data**: No login, no API key required for modest use. Statutorily public municipal records.
- **Structured output**: Clean, deduplicated rows with permit number, type, status, dates, address, work description, valuation, contractor/owner details, coordinates, and parcel ID.
- **Flexible filtering**: Search by keyword (solar, roofing, HVAC), date range, custom SoQL where clauses, and column selection.

### How to use

1. **Set input parameters** in the Input tab or via JSON:
   - `domain`: City open-data host (e.g., `data.cityofnewyork.us`)
   - `datasetId`: 4x4 dataset identifier (e.g., `rbx6-tga4` for NYC DOB NOW)
   - Optional: `searchQuery`, `dateField`, `dateFrom`, `dateTo`, `whereClause`, `select`, `limit`, `offset`
2. **Run the Actor**. It will fetch records from the Socrata API, map columns to standard fields, and push results to a dataset.
3. **Export results** in JSON, CSV, Excel, or via API.

### Example input

```json
{
    "domain": "data.cityofnewyork.us",
    "datasetId": "rbx6-tga4",
    "searchQuery": "solar",
    "dateField": "issued_date",
    "dateFrom": "2024-01-01",
    "dateTo": "2024-01-31",
    "limit": 100
}
```

### Output fields

| Field | Description |
|-------|-------------|
| `permit_number` | Unique permit identifier |
| `permit_type` | Type of work (e.g., Solar, General Construction) |
| `status` | Permit status (e.g., Signed-off, Issued) |
| `issue_date` | Date permit was issued |
| `address` | Property address (composite if needed) |
| `work_description` | Description of work to be performed |
| `valuation` | Estimated job cost |
| `contractor_name` | Contractor or applicant business name |
| `contractor_license` | Contractor license number |
| `owner_name` | Property owner name |
| `latitude` | Property latitude |
| `longitude` | Property longitude |
| `city` | City or borough |
| `parcel_id` | Parcel identifier (BBL, lot, etc.) |
| `raw` | Original record from the source dataset |

### Pricing

This Actor uses Apify's compute units. Free-tier users are limited to 10 items per run; paying users have no limit.

### Technical details

- **Strategy**: Cheerio-based HTML scraping of the dataset page for metadata, plus the public CSV export endpoint (`/api/views/{id}/rows.csv`) for data — this bypasses the rate-limited SODA JSON API that direct API calls hit.
- **Column mapping**: Automatically detects and maps dataset columns to standard fields using pattern matching.
- **Proxy**: Configurable Apify proxy support via CheerioCrawler for high-volume runs.
- **Retries/sessions**: Built-in retry and session management from Crawlee protects against intermittent blocks.

### Supported cities

Any US city portal powered by Socrata. Pre-configured examples:

- New York City (`data.cityofnewyork.us`)
- Los Angeles (`data.lacity.org`)
- Chicago (`data.cityofchicago.org`)
- San Francisco (`data.sfgov.org`)
- Austin (`data.austintexas.gov`)
- Seattle (`data.seattle.gov`)
- And many more...

### FAQ

**Q: Do I need an API key?**\
A: No, Socrata datasets are publicly accessible. However, for high-volume usage, consider registering for an app token to avoid rate limits.

**Q: How do I find the dataset ID?**\
A: Open the dataset page on the city's portal, click "Export" → "SODA API", and copy the 4x4 identifier.

**Q: Can I filter by permit type or status?**\
A: Yes, use the `whereClause` parameter with SoQL syntax (e.g., `work_type='Solar'`).

**Q: What if the dataset columns differ?**\
A: The Actor uses intelligent column mapping. It will try to match common column names; you can also specify exact columns via the `select` parameter.

### Support

For issues or feature requests, please open an issue on the Apify platform.

### Disclaimer

This Actor accesses publicly available government data. Users are responsible for complying with the terms of service of the target data portals and applicable laws.

### SEO Keywords

building permits scraper, construction permits data, socrata soda api, us building permit data, contractor leads, construction lead generation, roofing contractor leads, solar contractor leads, hvac contractor leads, city open data permits, building permits dataset, construction market data, permit data api, us construction leads, multi city permit data, building permit monitoring, real estate construction data, socrata data scraper, permit leads pipeline, building material supplier leads

### Related Actors

Verified related actors on Apify that pair well with this one. All links point to real, publicly available actors.

- [Apify Web Scraper](https://apify.com/apify/web-scraper)
- [Google Search Scraper](https://apify.com/apify/google-search-scraper)
- [Google Maps Places](https://apify.com/compass/crawler-google-places)

# Actor input Schema

## `domain` (type: `string`):

City open-data host, e.g. data.cityofnewyork.us, data.sfgov.org, data.cityofchicago.org.

## `datasetId` (type: `string`):

Socrata dataset identifier, the 4x4 code from the dataset URL (e.g. ipu4-2q9a for NYC DOB Permit Issuance).

## `searchQuery` (type: `string`):

Full-text search across all text columns, e.g. solar, roofing, HVAC, demolition.

## `dateField` (type: `string`):

Column to filter by date, e.g. issued\_date, issuance\_date.

## `dateFrom` (type: `string`):

Keep permits with Date column on or after this date. Format YYYY-MM-DD.

## `dateTo` (type: `string`):

Keep permits with Date column on or before this date. Format YYYY-MM-DD.

## `whereClause` (type: `string`):

Optional raw SoQL filter, e.g. borough='MANHATTAN' or estimated\_job\_costs > 50000.

## `select` (type: `string`):

Comma-separated list of columns to keep. Leave empty to keep all.

## `limit` (type: `integer`):

Maximum number of records to fetch.

## `offset` (type: `integer`):

Number of records to skip.

## `proxyConfiguration` (type: `object`):

Proxy settings for anti-bot protection.

## Actor input object example

```json
{
  "domain": "data.cityofnewyork.us",
  "datasetId": "rbx6-tga4",
  "limit": 1000,
  "offset": 0,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# 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 = {
    "domain": "data.cityofnewyork.us",
    "datasetId": "rbx6-tga4"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ahmed_jasarevic/us-scraper").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 = {
    "domain": "data.cityofnewyork.us",
    "datasetId": "rbx6-tga4",
}

# Run the Actor and wait for it to finish
run = client.actor("ahmed_jasarevic/us-scraper").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 '{
  "domain": "data.cityofnewyork.us",
  "datasetId": "rbx6-tga4"
}' |
apify call ahmed_jasarevic/us-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ahmed_jasarevic/us-scraper"
        }
    }
}

```

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/gX3oObswLprzhmLjA/builds/0hSyI7wqgen8N5XJS/openapi.json