# uk-planning-applications (`frequent_jumbo/my-actor`) Actor

Search & monitor planning applications from 400+ UK councils. Trade-lead tagging for builders, roofers, scaffolders, solar installers & landscapers, with 0–100 lead scoring, monitor mode with dedupe, and clean JSON for workflows and AI agents. No proxies, no logins.

- **URL**: https://apify.com/frequent\_jumbo/my-actor.md
- **Developed by:** [Philip Broadbent](https://apify.com/frequent_jumbo) (community)
- **Categories:** Lead generation, Real estate
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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

## UK Planning Applications — Search, Monitor & Trade Leads

Search and monitor **planning applications from 400+ UK councils** (England, Scotland, Wales & NI) in one place — with built-in **trade-lead classification** that turns raw applications into scored, actionable leads for builders, roofers, scaffolders, solar installers, landscapers and other trades.

Backed by a stable HTTP API aggregating official council planning portals — **no brittle browser scraping, no logins, no proxies**.

### What you get for each application

| Field | Example |
|---|---|
| `council`, `reference`, `address`, `postcode` | Manchester, 138756/FH/2026, 12 Acacia Ave, M20 4XX |
| `description` | "Erection of a single storey rear extension and loft conversion with dormer" |
| `state` / `applicationType` / `size` | Undecided / Full / Small |
| `startDate`, `decidedDate`, `consultationEndDate` | 2026-08-01 |
| `latitude` / `longitude` | 53.43 / -2.23 |
| `councilUrl` | Direct link to the application on the council portal |
| **`tradeTags`** | `extension-builder`, `loft-conversion`, `scaffolding:implied`, `roofing:implied` |
| **`leadScore`** (0–100) + `leadRationale` | 75 — "live application — early pipeline signal; matches trade keywords; medium-value project" |
| **`valueBand`**, **`projectCategory`** | medium / residential-improvement |

### Use cases

- **Tradespeople & contractors**: find homeowners about to start extensions, lofts, roofs, driveways — filter `minLeadScore: 60` and `appState: ["Permitted"]` for work that's approved and imminent.
- **Building-product & service suppliers**: scaffolding, skip hire, glazing, kitchens — use implied-trade tags to catch jobs that will need you even when the description doesn't say so.
- **Solar & renewables installers**: `searchText: "solar panel" or photovoltaic or "heat pump"`.
- **Property & land intelligence**: monitor competitor developers with `developer` searches; track approvals by area.
- **AI agents & workflows**: clean JSON, stable schema, monitor mode with dedupe — drop it into a scheduled workflow and pipe new leads to Slack/email/CRM via Apify integrations.

### Modes

- **Search** — one-off query: councils/areas + keywords + date ranges + postcode radius.
- **Monitor** — designed for **scheduled runs**: remembers every application it has returned and only outputs *new or changed* ones. Set it to run daily and you have a planning-alert engine.

### Example input

```json
{
    "areas": ["Manchester", "Trafford", "Stockport"],
    "mode": "monitor",
    "tradeTagging": true,
    "minLeadScore": 60,
    "appState": ["Undecided", "Permitted"]
}
```

### Pricing

Pay per result: a small fee per application found, plus a small fee per application classified with trade tags & lead score. No subscription. Turn `tradeTagging` off if you only want raw data.

### Reliability & fair use

Data comes from PlanIt (planit.org.uk), a long-running aggregator of official UK council planning portals, accessed with paced, rate-limit-respecting requests. Some councils' data can lag or go stale upstream; the `lastChanged` field tells you data freshness. Applicant personal names are **not** included in the data (data-protection safe) — applications are about properties and proposals.

### FAQ

**Which councils are covered?** 400+ UK planning authorities. Use any council name ("Leeds", "Hackney"), region ("London"), or nation ("Scotland").

**How fresh is the data?** Most active councils are checked daily upstream. Monitor mode + daily scheduled runs typically surfaces new applications within 24–48h of council publication.

**Is this legal?** Planning applications are public information published by councils for public consultation. This actor returns property/proposal data and omits personal applicant details.

# Actor input Schema

## `areas` (type: `array`):

One or more UK planning authority names, e.g. "Manchester", "Hackney", "Leeds", or a region like "London". Covers 400+ councils across England, Scotland, Wales and NI.

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

search = one-off query. monitor = remembers what it has seen and returns only NEW/changed applications on each run — ideal for scheduled runs feeding alerts.

## `searchText` (type: `string`):

Search in application descriptions. Supports phrases in quotes, 'or', and '-' to exclude. E.g.: "loft conversion" or extension

## `recentDays` (type: `integer`):

Only applications submitted within this many days (0 = today). Leave empty to use explicit dates below.

## `startDate` (type: `string`):

Only applications submitted on/after this date. Ignored if 'last N days' is set.

## `endDate` (type: `string`):

Only applications submitted on/before this date.

## `postcode` (type: `string`):

UK postcode for a circular search instead of / as well as council areas.

## `radiusKm` (type: `integer`):

Radius for postcode search. Default 5.

## `appState` (type: `array`):

Filter by status. 'Undecided' = live applications (early signal); 'Permitted'/'Conditions' = approved (work about to start).

## `appSize` (type: `array`):

Filter by development size. Large = major developments; Medium = multiple dwellings; Small = everything else (householder work).

## `appType` (type: `array`):

Filter by application type, e.g. Full (incl. householder), Trees, Advertising, Telecoms. Leave empty for all types.

## `tradeTagging` (type: `boolean`):

Tag each application with relevant trades (roofing, extension, solar, landscaping, scaffolding…), a project category, value band, and a 0-100 lead score with rationale.

## `minLeadScore` (type: `integer`):

Only output applications scoring at least this (0-100). Requires trade-lead classification. Try 60+ for hot leads.

## `maxResults` (type: `integer`):

Maximum number of applications to return across all areas (hard cap 5000 per source limits).

## Actor input object example

```json
{
  "areas": [
    "Manchester"
  ],
  "mode": "search",
  "radiusKm": 5,
  "tradeTagging": true,
  "minLeadScore": 0,
  "maxResults": 500
}
```

# 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 = {
    "areas": [
        "Manchester"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("frequent_jumbo/my-actor").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 = { "areas": ["Manchester"] }

# Run the Actor and wait for it to finish
run = client.actor("frequent_jumbo/my-actor").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 '{
  "areas": [
    "Manchester"
  ]
}' |
apify call frequent_jumbo/my-actor --silent --output-dataset

```

## MCP server setup

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

```

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/ybqU1GesMXgRUK3vt/builds/skpWfOabIh2hXsffR/openapi.json