Site appraisal
GET /v1/site/appraisalEverything known about ONE site, assembled and judged — the site dossier.
Same call over MCP
Site appraisal dossiersite_appraisalAuthenticate with an API key from the API & MCP Hub. The same call is available as an MCP tool at the same price.
Reference
What GET /v1/site/appraisal returns
Give a uprn (from address_resolve or address_autocomplete) or a land_id (from sourcing_search). Returns in one call what would otherwise be six:
site— the land parcel: area, land use, built coverage, and the boundary as GeoJSON you can put straight on a mapvaluation— our AVM against the last recorded sale, with gain and years heldownership— the registered proprietor, type, company numberenergy— the latest EPCauction_history— every appearance, matched on address as well as UPRN, and whether it ever solddesignations— LIVE checks: conservation area, green belt, AONB, national park, flood risk, listed buildingssignals— the judgement
READ signals FIRST. It is why this exists rather than being six calls. Each entry names what fired it and carries its evidence: repeat auction failure with the guide-to-estimate ratio, long_held with the nominal gain, mees_unlettable with the EPC band (F and G cannot legally be let), under_built with the plot coverage, corporate_owner with the company number. A site with nothing to say returns signal: "none" explicitly.
ABSENCE IS A REAL ANSWER, NOT AN ERROR. No registered proprietor means the polygon-to-title backfill has not reached this parcel — it covers about 44% — not that the land is unregistered. No EPC, no auction history and no valuation are all normal, and each says so in its own block.
A designation check that FAILS is reported as UNKNOWN, never as absent. Do not tell a user a site is unconstrained on the strength of a failed check.
A SCHEME PRICES THE BUILD. Pass scheme_gia_m2 (and scheme_units for a cost per unit) and you get a scheme block: build cost from the published construction index times the regional factor, with on-costs. You must supply rate_gbp_m2 yourself — no £/m² benchmark is loaded, so without one the block reads not_available rather than inventing a rate. It is CONSTRUCTION COST ONLY: no land, finance, sales, S106 or CIL, so it is one side of a residual and never a residual. Say that when you report it.
precedents summarises what nearby applications were decided: an approval rate with its denominator, and a median decision time on the much smaller sample that carries both dates. Quote each with its own n, and never as a probability for this scheme.
plot_utilisation gives built coverage and unbuilt ground. Coverage is footprint over area — a ground-plane measure, NOT a density — and unbuilt ground is an upper bound before any constraint or access test, not a developable area.
include_designations=False skips the live lookups and answers from the warehouse alone, which is faster.
UK only.
Inputs
Before you call it
- uprn
- A UPRN is the Unique Property Reference Number every UK address carries. Narrow the address with address_autocomplete, which is free, then address_resolve returns the UPRN for 8 credits. property_summary and address_by_postcode return UPRNs too.
- land_id
- Parcel and land identifiers come from sourcing_search. Run the search first, then pass the identifiers of the parcels you want resolved or appraised.
- sector
- Sectors follow the VOA classification (OFFICE, RETAIL, INDUSTRIAL_WAREHOUSE, HOTEL and so on). Omit the argument for all sectors; the response names the sectors published for an area when the one you asked for is not.
Request
Calling GET /v1/site/appraisal
curl "https://api.marketcode.ai/v1/site/appraisal?uprn=200003443835" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"Send your API key as a Bearer token. Every response carries credits_charged and credits_remaining.
Inputs
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uprn | Query | integer | No | Property UPRN |
| land_id | Query | string | No | Parcel id from /sourcing/search |
| include_designations | Query | boolean | No | Run live planning constraint checks (adds ~1-3s).Default: true |
| scheme_gia_m2 | Query | number | No | Proposed gross internal area — prices the build side. |
| scheme_units | Query | integer | No | Proposed unit count. |
| sector | Query | string | No | Cost sector for the build estimateDefault: residential |
| region | Query | string | No | NATIONAL | LONDON | SOUTH_EASTDefault: NATIONAL |
| rate_gbp_m2 | Query | number | No | Your own £/m² rate — required for a priced build. |
| rate_period | Query | string | No | The period your rate is quoted at, e.g. 2024Q1 |
| include_precedents | Query | boolean | No | Summarise nearby planning decisions.Default: true |
| precedent_radius_m | Query | integer | No | Default: 800 |
Response
What GET /v1/site/appraisal returns for a real request
curl "https://api.marketcode.ai/v1/site/appraisal?uprn=200003443835" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"{
"country": "<string>",
"data": {
"site": {
"note": "<string>"
},
"address": {
"uprn": "<string>",
"address": "<string>",
"property_type": null,
"asset_subtype": null,
"num_beds": null,
"floor_area_m2": 0,
"epc_rating": null,
"tenure": null,
"year_built": null,
"last_sale_date": null,
"last_sale_price": null,
"lat": 0,
"lng": 0
},
"valuation": {
"estimated_value": 0,
"range_low": 0,
"range_high": 0,
"confidence": "<string>",
"estimated_at": "<string>",
"last_sale_price": null,
"last_sale_date": null,
"gain": null,
"gain_pct": null,
"years_held": null,
"basis": "<string>"
},
"ownership": {
"note": "<string>"
},
"energy": {
"note": "<string>"
},
"auction_history": {
"appearances": 0,
"lots": [],
"note": "<string>"
},
"signals": [
{
"signal": "<string>",
"severity": "<string>",
"detail": "<string>"
}
],
"designations": {
"conservation_area": {
"present": false,
"name": null,
"detail": "<string>",
"raw": {
"postcode": null,
"postcode_type": null,
"conservation_area": false,
"conservation_area_name": null,
"status": "<string>"
}
},
"green_belt": {
"present": false,
"name": null,
"detail": "<string>",
"raw": {
"postcode": null,
"postcode_type": null,
"green_belt": false,
"green_belt_name": null,
"status": "<string>"
}
},
"aonb": {
"present": false,
"name": null,
"detail": "<string>",
"raw": {
"postcode": null,
"postcode_type": null,
"aonb": false,
"aonb_name": null,
"status": "<string>"
}
},
"national_park": {
"present": false,
"name": null,
"detail": "<string>",
"raw": {
"postcode": null,
"postcode_type": null,
"national_park": false,
"national_park_name": null,
"status": "<string>"
}
},
"flood_risk": {
"present": false,
"level": "<string>",
"detail": "<string>",
"raw": {
"postcode": null,
"what3words": null,
"flood_risk": "<string>",
"status": "<string>"
}
},
"listed_buildings": {
"present": false,
"count": 0,
"entries": [],
"detail": "<string>",
"raw": {
"postcode": null,
"postcode_type": null,
"data": "<string>",
"status": "<string>"
}
}
}
},
"credits_charged": 0
}Shape only. This call returns licensed records, so the keys are real and every value is a placeholder of its type.
Response
Response fields
| Field | Type |
|---|---|
| country | string |
| data | object |
| data.site | object |
| data.site.note | string |
| data.address | object |
| data.address.uprn | string |
| data.address.address | string |
| data.address.property_type | null |
| data.address.asset_subtype | null |
| data.address.num_beds | null |
| data.address.floor_area_m2 | integer |
| data.address.epc_rating | null |
| data.address.tenure | null |
| data.address.year_built | null |
| data.address.last_sale_date | null |
| data.address.last_sale_price | null |
| data.address.lat | number |
| data.address.lng | number |
| data.valuation | object |
| data.valuation.estimated_value | integer |
| data.valuation.range_low | integer |
| data.valuation.range_high | integer |
| data.valuation.confidence | string |
| data.valuation.estimated_at | string |
| data.valuation.last_sale_price | null |
| data.valuation.last_sale_date | null |
| data.valuation.gain | null |
| data.valuation.gain_pct | null |
| data.valuation.years_held | null |
| data.valuation.basis | string |
| data.ownership | object |
| data.ownership.note | string |
| data.energy | object |
| data.energy.note | string |
| data.auction_history | object |
| data.auction_history.appearances | integer |
| data.auction_history.lots | array |
| data.auction_history.note | string |
| data.signals | array |
| data.signals[].signal | string |
| data.signals[].severity | string |
| data.signals[].detail | string |
| data.designations | object |
| data.designations.conservation_area | object |
| data.designations.conservation_area.present | boolean |
| data.designations.conservation_area.name | null |
| data.designations.conservation_area.detail | string |
| data.designations.conservation_area.raw | object |
| data.designations.conservation_area.raw.postcode | null |
| data.designations.conservation_area.raw.postcode_type | null |
| data.designations.conservation_area.raw.conservation_area | boolean |
| data.designations.conservation_area.raw.conservation_area_name | null |
| data.designations.conservation_area.raw.status | string |
| data.designations.green_belt | object |
| data.designations.green_belt.present | boolean |
| data.designations.green_belt.name | null |
| data.designations.green_belt.detail | string |
| data.designations.green_belt.raw | object |
| data.designations.green_belt.raw.postcode | null |
| data.designations.green_belt.raw.postcode_type | null |
| data.designations.green_belt.raw.green_belt | boolean |
| data.designations.green_belt.raw.green_belt_name | null |
| data.designations.green_belt.raw.status | string |
| data.designations.aonb | object |
| data.designations.national_park | object |
| data.designations.flood_risk | object |
| data.designations.listed_buildings | object |
| credits_charged | integer |
Fields observed in the example response above; a field the example did not exercise is not listed.
Price and licence
What it costs, and where the data comes from
Site appraisal costs 5 credits per successful call over MCP and over REST, and the two surfaces share one credit balance.
The price covers licensed records in the response, from HM Land Registry, Ordnance Survey, Ministry of Housing, Communities and Local Government, planning.data.gov.uk, Environment Agency, Historic England, Natural England and UK auction houses. A call that fails is not charged.
Credits are granted on sign-up and bought in packs; the pricing page lists every call.
Computed by MarketCode from
- HM Land Registry
Price Paid Data
Open Government Licence v3 · England and Wales
- HM Land Registry
Commercial and Corporate Ownership (CCOD) and Overseas Companies Ownership (OCOD)
HM Land Registry's dataset licence for CCOD and OCOD: free of charge, with conditions on onward use · England and Wales
- Ordnance Survey
National Geographic Database (buildings, land and sites)
Used under licence from Ordnance Survey · Great Britain
- Ministry of Housing, Communities and Local Government
Energy Performance Certificates (domestic and non-domestic)
MHCLG's EPC open data terms · England and Wales
- planning.data.gov.uk
National planning designations and the local planning authority register
Open Government Licence v3 · England
- Environment Agency
Risk of Flooding from Surface Water and Flood Zones
Open Government Licence v3 · England
- Historic England
National Heritage List for England
Open Government Licence v3 · England
- Natural England
National Landscapes, national parks and ancient woodland
Open Government Licence v3 · England
- UK auction houses
Auction catalogues and results (Allsop, Savills, Acuitus, Barnett Ross, Agents Property Auction)
Published catalogues and results, collected and matched by MarketCode · UK
How the model or index is built, and where it is weak, is on the methodology page.
Related
Endpoints used with Site appraisal
- Resolve an address to a UPRN8 credits
address_resolveResolve free-text address to canonical record (UPRN for UK).Named in the description - Autocomplete a UK addressFree
address_autocompleteFree address autocomplete. Returns ranked candidates for a partial addressNamed in the description - Search land or units by criteria8 credits
sourcing_searchFind land parcels or residential units matching investment criteria — the sourcing tool. Give a `location` (place or area name) or a `bbox`.Named in the description - Plot utilisation of land parcels6 credits
plot_utilisationLand parcels by size and how much of them is built on. Set `max_built_coverage` to 0.2 to find largely undeveloped plots.Named in the description - Owners of sourced parcels5 credits
sourcing_ownersResolve registered owners for parcels returned by `sourcing_search`.Same product - Titles held by a company3 credits
ownership_by_companyTitles held by a company, by Companies House number. Useful for mapping aSame product
Glossary
Terms used here
- Equity gain (nominal): The difference between a property's current estimated value and its last recorded sale price, in pounds and percent, before inflation and without any mortgage.
- CCOD and OCOD: HM Land Registry's two bulk datasets of titles owned by UK companies and public bodies (CCOD) and by overseas companies (OCOD), the source of MarketCode's ownership answers.
- Conservation area: An area a local planning authority has designated for its special architectural or historic character, where demolition and many external changes need consent.
- Listed building: A building on the National Heritage List for England, protected by grade (I, II* or II); any work affecting its character needs listed building consent.
- Article 4 direction: A direction by a local planning authority withdrawing specified permitted development rights in an area, so work that is normally automatic needs a planning application.
- Permitted development: Changes an owner may make without a planning application, granted nationally by the General Permitted Development Order, subject to limits and to local withdrawal by Article 4.
- Green belt: Land around cities designated to prevent urban sprawl, where new building is inappropriate except in defined circumstances; one of the designations MarketCode checks live.
- Brownfield land: Previously developed land; local authorities keep a register of brownfield sites suitable for housing, which MarketCode reads as a designation.
- Flood zone and surface water risk: The Environment Agency's two flood layers: fluvial and tidal flood zones (1 low, 2 medium, 3 high) and the Risk of Flooding from Surface Water, both returned per property.
- Plot utilisation (built coverage): The share of a land parcel covered by building footprint; a low figure on a large parcel is the signature of an under-built site.
- Minimum energy efficiency standard (MEES): The rule that privately rented property in England and Wales must reach at least EPC band E, so F and G stock cannot legally be let without a registered exemption.
- Distressed asset: A property that has gone to auction more than once and never sold; on the public record, a vendor who wants out and a market that has said no.
FAQ
Questions about Site appraisal
How much does `site_appraisal` cost?
+
Site appraisal costs 5 credits per successful call over MCP and over REST, and the two surfaces share one credit balance. The price covers licensed records in the response, from HM Land Registry, Ordnance Survey, Ministry of Housing, Communities and Local Government, planning.data.gov.uk, Environment Agency, Historic England, Natural England and UK auction houses. A call that fails is not charged.
Do I need to resolve the address first?
+
Yes. site_appraisal takes a UPRN, not an address. Start with address_autocomplete (free) to narrow the address, then address_resolve (8 credits) to get the UPRN. An assistant with the MarketCode skills installed does both steps on its own.
How do I authenticate?
+
Send your API key as a Bearer token in the Authorization header. Keys are created in the API & MCP Hub, shown once and revocable. Every response carries the credits charged and your remaining balance.
Is there an MCP version?
+
Yes. The site_appraisal tool on the MarketCode MCP server is the same call at the same price, signed in with OAuth rather than a key, so Claude, ChatGPT, Codex and Cursor can run it in a conversation.
Where does the data come from?
+
Computed by MarketCode from HM Land Registry price paid data, HM Land Registry ownership registers, Ordnance Survey NGD, Ministry of Housing, Communities and Local Government EPC register, planning.data.gov.uk, Environment Agency flood data, Historic England national heritage list for england, Natural England national landscapes, national parks and ancient woodland and UK auction houses catalogues and results. Coverage is the UK. The methodology page describes how the model or index is built.
Can I store or republish the results?
+
The response includes records we license from HM Land Registry, Ordnance Survey, Ministry of Housing, Communities and Local Government, planning.data.gov.uk, Environment Agency, Historic England, Natural England and UK auction houses. Use them in your own analysis, reports and products; bulk redistribution of the raw records or building a competing dataset from them is not covered. Ask us if you need a redistribution licence.
Does `site_appraisal` change anything?
+
No. The tool is annotated read-only on the server, so it never writes to your data or ours and an assistant can call it without a confirmation step.
Try Site appraisal on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.