UK Planning Leads Finder

Find potential contractor jobs in recent UK planning applications without reading every municipal record by hand.

Choose a trade and planning authorities. The Actor builds the source query from a curated service catalog, collects public applications, combines literal BM25 matching with a packaged local MiniLM model, and checks that each result contains direct evidence of a selected service.

No external AI key is required. The ranking model runs inside the Actor.

Supported contractor packs

The catalog contains 18 trade packs and 63 selectable services:

• roofing; HVAC and ventilation; signage and shopfronts; windows, doors, and glazing
• tree surgery; solar PV and battery storage; EV charging
• extensions and general building; demolition; fencing and gates
• landscaping and groundworks; drainage; facades, cladding, and rendering
• heritage restoration; telecommunications; external lighting and security
• highways, parking, and access; industrial and agricultural buildings

Commercial roofing also has specialized rules for common false matches such as roof-mounted plant, solar panels, rooflights, loft conversions, and minor residential roof references. The other packs use a shared recall-first service-evidence qualifier and expose weaker stages as risks instead of silently hiding possible work.

Quick start

Select one trade pack and one or more planning authorities:

{
  "authorities": ["Leeds"],
  "tradePack": "hvac_ventilation",
  "serviceIds": ["commercial_extraction", "heat_pumps"],
  "recentDays": 30,
  "maxCandidates": 30,
  "maxResults": 10,
  "onlyNew": false,
  "includeRejected": false,
  "scoring": {
    "mode": "catalog_hybrid",
    "minimumScore": 45,
    "transformerBatchSize": 32
  }
}

Leave serviceIds empty to search all standard services in the selected trade. minimumScore: 45 is the recall-first default. To audit borderline and rejected records, set includeRejected to true; to inspect every ranked candidate, temporarily use minimumScore: 0.

How it works

1. Expands the selected services into planning-language source phrases.
2. Collects recent records from public UK planning data through PlanIt.
3. Normalizes fields and groups related application records into projects.
4. Applies exact filters for stage, application type, size, required phrases, and excluded phrases.
5. Ranks candidates with BM25 and several service-specific MiniLM comparisons.
6. Applies an absolute fit check based on explicit service evidence, proposed-work wording, and application stage.
7. Writes accepted leads to the Dataset and run diagnostics to RUN_SUMMARY.

The source phrases provide recall, BM25 rewards literal matches, MiniLM improves ordering by meaning, and the final guardrail prevents a first-place result from receiving a high fitScore merely because it was best in a small run.

Example result

{
  "authority": "Leeds",
  "description": "...installation of side-mounted extraction and ventilation flue...",
  "fit": true,
  "fitScore": 83,
  "workIntent": "commercial_extraction",
  "combinedRank": 1,
  "bm25Rank": 1,
  "semanticRank": 2,
  "matchedServices": ["Commercial extraction"],
  "intentEvidence": ["extraction", "ventilation flue"],
  "risks": [],
  "sourceUrl": "https://publicaccess.example/..."
}

Important fields:

• fitScore - absolute evidence-based qualification score; not a probability of winning work
• combinedRank - position from BM25 and semantic reciprocal-rank fusion within this run
• workIntent, matchedServices, and intentEvidence - the service and literal evidence found
• whyMatch, risks, and unknowns - explanations for review or downstream automation
• sourceUrl - link to the authority record where available
• isNew and firstSeenAt - monitoring state for repeated runs

Exact keyword controls

Use filters.requiredTerms when a word or phrase must literally occur in the description. Set requiredTermMode to any or all, and use filters.excludedTerms for deterministic exclusions. These filters run before semantic ranking.

For example, a solar installer can select the Solar pack and still require warehouse if its workflow must only receive warehouse projects.

Monitoring new opportunities

After an initial calibration run, set onlyNew to true. The Actor remembers previously returned projects for the same search configuration in an Apify Key-Value Store, making scheduled Tasks suitable for feeds, webhooks, Make, Zapier, or CRM workflows.

Validation and limitations

• The catalog was checked against 1,154 saved real PlanIt applications from Leeds and Manchester. Literal examples were observed for 54 of 63 services, and all 17 packs with candidates placed a plausible direct job first in the latest full local spot-check.
• This is development evidence, not a nationwide accuracy guarantee. Industrial/agricultural buildings and eight other individual services need broader multi-authority validation.
• A planning application is an early project signal, not a tender, contract award, confirmed budget, or request for quotation.
• Conditions, amendments, retrospective records, and retained work can still be useful signals, but the Actor lowers their fit score and explains the risk.
• Coverage, field quality, and freshness vary by planning authority.
• The Actor currently reads application metadata and descriptions; it does not download or interpret attached drawings or PDFs.

Keep early runs bounded with maxCandidates, review the explanations, and create a scheduled Task only after the selected trade and authority produce useful results.