Property comps
GET /v1/property/{uprn}/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 MCP
Comparable propertiesproperty_compsAuthenticate 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/property/{uprn}/comps returns
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.
Request
Calling GET /v1/property/{uprn}/comps
curl "https://api.marketcode.ai/v1/property/200003443835/comps" \
-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 | Path | string | Yes | |
| max_backfills | Query | integer | No | Default: 12 |
Response
What GET /v1/property/{uprn}/comps returns for a real request
curl "https://api.marketcode.ai/v1/property/200003443835/comps" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"{
"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.
Response
Response fields
| 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.
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
Endpoints 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.
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 property_comps 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. 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 on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.