Comparable properties
property_compsComparable properties in the same building or block, with missing attributes backfilled from sibling records so the set is usable rather than sparse.
Same call over REST
Property comps/v1/property/{uprn}/compsNot connected yet? Connect your assistant. Sign in with your MarketCode account; no API key needed.
Reference
What property_comps answers
Valuers value by comparison, and the best comparable is the flat next door. This call returns the comparable properties in the same building or block as the subject, with their sales, and backfills the attributes a single record lacks (a floor area, a bedroom count, a type) from sibling records in the same building, so a comparable set is something you can actually use rather than a list with holes in it. max_backfills bounds how far that goes.
It costs 6 credits because the response carries licensed records (AddressBase addresses and Ordnance Survey building data).
Reference
When to use it, and when not to
Use it to defend or challenge a value: the estimate from valuation_full says what the model thinks; this says what the neighbours made and when. Carry each comparable to today with market_index_series before comparing. For lots that sold at auction, measured against the valuation of the same property, use auction_comps; auction is a different market and the two are not interchangeable.
Inputs
Before you call it
A UPRN for the subject. address_autocomplete (free) then address_resolve (8 credits). The subject's own sales are in transactions_by_uprn; the comparables here are the other units.
- 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.
Example
An example call to property_comps
Use the MarketCode tool property_comps with {"uprn":"200003443835"} and show me the result.{
"uprn": "<string>",
"country": "<string>",
"data": {
"data": {
"subject": {
"uprn": 0,
"parent_uprn": 0,
"address": "<string>",
"postcode": "<string>",
"classification_code": "<string>"
},
"parent_uprn": 0,
"comps": [],
"backfills_attempted": 0,
"backfills_succeeded": 0
}
},
"credits_charged": 0
}Shape only. This call returns licensed records, so the keys are real and every value is a placeholder of its type.
Inputs
Arguments property_comps takes
| Name | Type | Required | Description |
|---|---|---|---|
| uprn | string | Yes | |
| max_backfills | integer | No | Default: 12 |
Response
What comes back
| Field | Type |
|---|---|
| uprn | string |
| country | string |
| data | object |
| data.data | object |
| data.data.subject | object |
| data.data.subject.uprn | integer |
| data.data.subject.parent_uprn | integer |
| data.data.subject.address | string |
| data.data.subject.postcode | string |
| data.data.subject.classification_code | string |
| data.data.parent_uprn | integer |
| data.data.comps | array |
| data.data.backfills_attempted | integer |
| data.data.backfills_succeeded | integer |
| credits_charged | integer |
Fields observed in the example response above; a field the example did not exercise is not listed.
Reference
Things that catch people out
- Same building first, then the street. A terraced house's comparables are the terrace; a flat's are the block. A detached house in a village may have few, and the response says so rather than reaching further and calling it comparable.
- Backfilled means inferred from siblings. A floor area filled from the flat below is marked as such. Read the provenance where a comparable's attribute matters.
- Dates matter. A comparable from 2017 is evidence about 2017. Adjust with the index and quote the date.
- Category B sales are not market prices. Transfers under a power of sale and right-to-buy sales are in the registry; they are not comparables for an open-market value.
Usage
How to run property_comps in your assistant
Ask your assistant in plain English, for example:
"Use the MarketCode tool property_comps for <address or area>.
Show the result and the credits charged."
The arguments the assistant will send, for the example on this page:
{"uprn":"200003443835"}The connect steps for Claude, ChatGPT, Codex, Cursor and Claude Code are on the MCP page.
Price and licence
What it costs, and where the data comes from
property_comps costs 6 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. 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
How the model or index is built, and where it is weak, is on the methodology page.
Related
Tools used with property_comps
- Full valuation with back-seriesFree
valuation_fullFull valuation block for a property: the value and its range, a monthlyPairs with this - Registered sales for a propertyFree
transactions_by_uprnAll HMLR Price Paid records joined to this UPRN, newest first.Pairs with this - House price index seriesFree
market_index_seriesThe published house-price INDEX for one postcode district or local authority: the level per month (base period = 100), the forecast tail flagged, and provenance saying how the index was built.Pairs with this - Auction comparablesFree
auction_compsAuction comparables on ACHIEVED prices, each against our valuation.Pairs with this - Resolve an address to a UPRN8 credits
address_resolveResolve free-text address to canonical record (UPRN for UK).Same product - Property summary4 credits
property_summaryOne-call summary of a property: what it is, what building it belongs to,Same product
Glossary
Terms used here
- Automated valuation model (AVM): A statistical model that estimates a property's current value from comparable evidence without an inspection; MarketCode's is trained on registered sales joined to floor area and building form.
- Comparable (comp): A recent sale or listing of a similar property nearby, used to support or challenge a valuation; MarketCode draws them from the same building and street first.
FAQ
Questions about property_comps
How much does `property_comps` cost?
+
property_comps costs 6 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. A call that fails is not charged.
Do I need to resolve the address first?
+
Yes. property_comps 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.
Which assistants can run `property_comps`?
+
Any MCP client: Claude (claude.ai, Claude Desktop, Claude Code), ChatGPT in developer mode, Codex and Cursor, each documented on the MCP page. You sign in with your MarketCode account over OAuth; there is no key to paste, and the connection is read-only.
Where does the data come from?
+
Computed by MarketCode from HM Land Registry price paid data. Coverage is England and Wales. 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. 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 `property_comps` 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.
How many comparables come back?
+
As many as the building or block holds with a sale, subject to the backfill limit. A large block returns many; a small house few. The count is itself information about how well evidenced the subject is.
Why is a comparable's floor area marked as backfilled?
+
Because the comparable has no certificate of its own and its area was filled from a sibling in the same building with the same footprint. It is usually close; the marking lets you weight it.
Does this include listings?
+
No. Comparables here are registered sales. Asking prices for the area are in listing_market_series; a single property's listing history, including reductions, is in listing_history.
Try property_comps in your assistant.
30-minute call. We'll connect your assistant live on a real address.