io.github.paulieb89/property-shared

Official13 tools

by paulieb89 · Python

UK Property Data

UK property data — Land Registry comps, EPC, Rightmove, rental yields, stamp duty, Companies House

UK property data including Land Registry, EPC, Rightmove, and stamp duty information.

Topics

ai-skillsclaudeepcland-registrymcpmcp-serverpropertyrightmoveuk

Captured live from the server via tools/list.

property_comps

Comparable sales from Land Registry Price Paid Data. Defaults return the standard residential set: - property_type=None means residential (F+D+S+T). Pass "F"/"D"/"S"/"T"/"O" for a single type, or "ALL" to disable type filtering (firehose). - transaction_category defaults to "A" (standard sales). Pass None to include category-B (bulk transfers, non-standard conveyances). - filter_outliers=False by default; set True for IQR-trimmed stats AND transaction list (1.5*IQR rule, needs >=4 prices). limit caps returned transactions (max 200). enrich_epc attaches EPC floor area and price-per-sqft to each transaction — slower but richer.

Parameters (9)

postcodestringrequired
monthsinteger
property_typeany
transaction_categoryany
filter_outliersboolean
search_levelstring
addressany
limitinteger
enrich_epcboolean

property_yield

Gross rental yield for a UK postcode. Combines Land Registry sale comps (median sale price) with Rightmove rental listings (median monthly rent) to produce a gross yield percentage.

Parameters (5)

postcodestringrequired
UK postcode (e.g. "NG1 2NS").
monthsinteger
PPD sale lookback period (default 24).
search_levelstring
PPD search granularity — "postcode", "sector" (default), or "district".
property_typeany
Filter sales by type. None (default) = residential set (F+D+S+T). Pass "F"/"D"/"S"/"T"/"O" for one type, "ALL" for firehose.
auto_escalateboolean
Widen the PPD search area on thin markets — postcode→ sector→district. Default True. Set False for strict-locality only.

rental_analysis

Rental market analysis and achievable rent estimate. auto_escalate widens the search area when fewer than 5 listings are found (thin market). Response includes thin_market, escalated_from, escalated_to fields when escalation occurs.

Parameters (4)

postcodestringrequired
radiusnumber
purchase_priceany
auto_escalateboolean

property_epc

Energy Performance Certificate data for a UK property or postcode area. With address: returns the matched EPC certificate for that specific property. Without address: returns an aggregated summary of every certificate at the postcode — count, rating distribution, property-type breakdown, floor-area range — plus a hint to call again with an address for single-property detail. Returns None if no certificates exist for the postcode at all.

Parameters (2)

postcodestringrequired
addressany

property_epc_search

Browse all EPC certificates at a postcode — use when you have no house number. Returns a slim list of every certificate at the postcode. Each entry contains: address, rating, score, floor_area (sqm), property_type, floor_level, habitable_rooms, inspection_date, lmk_key. Workflow for Rightmove listings where the house number is not shown: 1. Call rightmove_listing to obtain floor_area_sqm, property_type, and any floor-level signals in the description (e.g. "top floor", "ground floor"). 2. Call property_epc_search(postcode) to retrieve the full cert list. 3. You MUST cross-reference each cert's floor_area against the listing's floor_area_sqm (accept within ±5 sqm) AND property_type must match. Also use floor_level and habitable_rooms where available. 4. If a single cert matches, call epc_certificate(lmk_key) for the full detail. 5. If multiple certs match equally, present all candidates — do not guess. If floor_area is unavailable on the listing, filter by property_type only and return all candidates. Returns None if no certificates exist for the postcode.

Parameters (1)

postcodestringrequired

epc_certificate

Fetch a single EPC certificate by its lmk_key (certificate hash). Use after property_epc_search has identified the correct cert — this is faster than property_epc(postcode, address) as it makes a direct lookup with no fuzzy matching or postcode re-fetch. lmk_key is returned in every property_epc_search result. Returns the full EPC certificate or None if not found.

Parameters (1)

lmk_keystringrequired

stamp_duty

UK Stamp Duty Land Tax (SDLT) calculation with full breakdown.

Parameters (4)

priceintegerrequired
additional_propertyboolean
first_time_buyerboolean
non_residentboolean

rightmove_search

Fetch Rightmove listings for a postcode. listing_type: "sale" or "rent". sort_by: "newest", "most_reduced", "price_asc", "price_desc". keywords filters by description text (e.g. "church conversion", "barn", "factory"). Images are excluded from results.

Parameters (9)

postcodestringrequired
listing_typestring
radiusnumber
property_typeany
min_bedroomsany
max_priceany
sort_byany
keywordsany
max_pagesinteger

rightmove_listing

Full detail for a single Rightmove listing (URL or numeric ID). include_images fetches and embeds photos and floorplans as MCP image content. max_images caps the number of property photos (default 3); floorplans always included.

Parameters (3)

property_url_or_idstringrequired
include_imagesboolean
max_imagesinteger

property_blocks

Property block analysis — identify buildings with multiple flat sales (block-buy opportunities).

Parameters (3)

postcodestringrequired
search_levelstring
monthsinteger

company_search

Search Companies House for a company by name.

Parameters (1)

namestringrequired

planning_search

Find the council planning portal URL for a postcode.

Parameters (1)

postcodestringrequired

ppd_transactions

Raw Land Registry Price Paid transactions for a postcode.

Parameters (3)

postcodestringrequired
limitinteger
property_typeany

README.md5 KBView on GitHub

Property Shared

UK property data in one package. Pulls Land Registry sales, EPC certificates, Rightmove listings, rental yields, stamp duty calculations, planning portal links, and Companies House records.

Use it as a Python library, CLI, HTTP API, or MCP server.

What You Get

Data Source	What It Returns
Land Registry PPD	Sold prices, dates, property types, area comps with median/percentiles
EPC Register	Energy ratings, floor area, construction age, heating costs
Rightmove	Current listings (sale + rent), prices, agents, listing details
Yield Analysis	Gross yield from PPD sales + Rightmove rentals combined
Stamp Duty	SDLT calculation with April 2025 bands, BTL surcharge, FTB relief
Block Analyzer	Groups flat sales by building to spot investor exits
Planning	Local council planning portal lookup (99 verified councils, stdio only)
Companies House	Company search and lookup by name or number

Skills & Plugins

Property and Legal packs coming soon. Please get in contact if you have working experiance or expert knowledge in UK property investing, UK Estate Agents, Property and Conveyencing and would like to help shape this. paul@bouch.dev

Use as MCP Server

No install required — paste the URL into your MCP client config and go.

Claude Code, Cursor, any MCP client:

json

{
  "mcpServers": {
    "property-shared": {
      "type": "http",
      "url": "https://property-shared.fly.dev/mcp"
    }
  }
}

Install

bash

pip install property-shared

# or with uv
uv add property-shared

Extras: [cli] for CLI, [api] for HTTP server, [dev] for tests.

bash

pip install property-shared[cli]
# or
uv add property-shared --extra cli

Use as a Python Library

python

from property_core import PPDService, calculate_yield, calculate_stamp_duty

# Get comparable sales for a postcode
comps = PPDService().comps("SW1A 1AA", months=24, property_type="F")
print(f"Median flat price: {comps.median:,}")

# Calculate rental yield
import asyncio
result = asyncio.run(calculate_yield("NG1 1AA", property_type="F"))
print(f"Gross yield: {result.gross_yield_pct}%")

# Stamp duty
sdlt = calculate_stamp_duty(250000, additional_property=True)
print(f"SDLT: {sdlt.total_sdlt:,.0f} ({sdlt.effective_rate}%)")

All models are available at top level:

python

from property_core import (
    PPDTransaction, PPDCompsResponse, EPCData,
    RightmoveListing, RightmoveListingDetail,
    PropertyReport, YieldAnalysis, RentalAnalysis,
    BlockAnalysisResponse, CompanyRecord, StampDutyResult,
)

Interpretation helpers (core returns numbers, you decide how to label them):

python

from property_core import classify_yield, classify_data_quality, generate_insights

Use as CLI

bash

pip install property-shared[cli]  # or: uv add property-shared --extra cli

# Comparable sales
property-cli ppd comps "SW1A 1AA" --months 24 --property-type F

# Rental yield
property-cli analysis yield "NG1 1AA" --property-type F

# Stamp duty
property-cli calc stamp-duty 300000

# Rightmove search (with sort)
property-cli rightmove search-url "NG1 1AA" --sort-by most_reduced

# Full property report
property-cli report generate "10 Downing Street, SW1A 2AA" --property-type F

Add --api-url http://localhost:8000 to any command to route through the HTTP API instead of calling core directly.

Use as HTTP API

bash

pip install property-shared[api]  # or: uv add property-shared --extra api
property-api  # starts on port 8000

Interactive docs at http://localhost:8000/docs.

Key endpoints:

GET /v1/ppd/comps?postcode=SW1A+1AA&property_type=F&enrich_epc=true
GET /v1/analysis/yield?postcode=NG1+1AA&property_type=F
GET /v1/analysis/rental?postcode=NG1+1AA&purchase_price=200000
GET /v1/rightmove/search-url?postcode=NG1+1AA&sort_by=newest
GET /v1/calculators/stamp-duty?price=300000&additional_property=true
POST /v1/property/report with { "address": "10 Downing Street, SW1A 2AA" }

Full endpoint list in USER_GUIDE.md.

Environment Variables

Copy .env.example to .env. Key variables:

Variable	Required For	Description
`EPC_API_EMAIL`	EPC lookups	Free key from EPC Register
`EPC_API_KEY`	EPC lookups	Paired with email above
`COMPANIES_HOUSE_API_KEY`	Company search	Free key from Companies House
`RIGHTMOVE_DELAY_SECONDS`	No (default 0.6s)	Rate limit delay for Rightmove scraping
`OPENAI_API_KEY`	Planning scraper	Vision-guided planning portal scraper

Land Registry PPD and Rightmove work without credentials.

Development

bash

# Install with dev extras
uv sync --extra dev

# Run API with reload
uv run uvicorn app.main:app --reload

# Run tests (mocked, no network)
uv run --extra dev pytest -v

# Run live integration tests (real network calls)
RUN_LIVE_TESTS=1 uv run --extra dev pytest -v

Deployed at https://property-shared.fly.dev with API docs at /docs and MCP endpoint at /mcp.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "property-shared": {
      "command": "uvx",
      "args": [
        "property-shared"
      ]
    }
  }
}