Valuation estimate
POST /v1/valuation/estimateThe point value and its range for any property with a floor area on record, free; the lighter half of the valuation pair.
Same call over MCP
Automated valuation estimatevaluation_estimateAuthenticate with an API key from the API & MCP Hub. The same call is available as an MCP tool at the same price.
Reference
What POST /v1/valuation/estimate returns
The quick number. Give a UPRN and get the model's estimate of what the property would sell for today and the range around it. It is the same model as valuation_full, without the back-series, the rental estimate and the trust score, so it is the one to call when a value is one input among many: sizing a portfolio, ranking a shortlist, checking a guide price.
It is free, and it returns 404 rather than a guess when the property has no floor area on record, because the model needs the area before it will produce a number.
Reference
When to use it, and when not to
Use it in loops and lists: every property in a sourcing shortlist, every lot in an auction catalogue, every UPRN in a book. Use valuation_full where the number will be relied on or challenged and you need the trust score and the comparables' context to defend it. equity_estimate combines this value with the last recorded sale to give the nominal gain and years held.
Inputs
Before you call it
A UPRN with a floor area on record. Resolve the address with address_autocomplete and address_resolve first. Coverage of floor area is the main lever on coverage of value: certificates arrive when a property is sold or let, and measured building geometry fills many of the rest.
- 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 POST /v1/valuation/estimate
curl -X POST "https://api.marketcode.ai/v1/valuation/estimate" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"uprn":"200003443835"}'Send your API key as a Bearer token. Every response carries credits_charged and credits_remaining.
Inputs
Parameters
This endpoint takes no path or query parameters.
Request body
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uprn | Body | integer | Yes | Property UPRN |
Response
What POST /v1/valuation/estimate returns for a real request
curl -X POST "https://api.marketcode.ai/v1/valuation/estimate" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"uprn":"200003443835"}'{
"uprn": "200003443835",
"country": "UK",
"data": {
"data": {
"uprn": 200003443835,
"estimated_value": 440830,
"value_range_min": 227909,
"value_range_max": 668415,
"confidence_score": 0.5002,
"last_transaction_price": null,
"last_transaction_date": null,
"valuation_available": true,
"unavailable_reason": null,
"source": "robosapien",
"credits_used": 0,
"execution_time_ms": 34.218549728393555
}
},
"credits_charged": 0
}A real response, captured from production and trimmed: arrays to three items, long strings shortened, volatile keys dropped.
Response
Response fields
| Field | Type | Example |
|---|---|---|
| uprn | string | 200003443835 |
| country | string | UK |
| data | object | |
| data.data | object | |
| data.data.uprn | integer | 200003443835 |
| data.data.estimated_value | integer | 440830 |
| data.data.value_range_min | integer | 227909 |
| data.data.value_range_max | integer | 668415 |
| data.data.confidence_score | number | 0.5002 |
| data.data.last_transaction_price | null | |
| data.data.last_transaction_date | null | |
| data.data.valuation_available | boolean | true |
| data.data.unavailable_reason | null | |
| data.data.source | string | robosapien |
| data.data.credits_used | integer | 0 |
| data.data.execution_time_ms | number | 34.218549728393555 |
| credits_charged | integer | 0 |
Fields observed in the example response above; a field the example did not exercise is not listed.
Reference
Things that catch people out
- An estimate, not a valuation. It has not seen the property. Condition, lease length, a loft conversion never certified: none of these are in the number. Use it to screen and to size.
- 404 is an answer. No floor area means no valuation; the tool does not invent one. A rural site with designations, a newly built flat with no certificate yet, a long-held house never sold or let: all can be missing.
- The range is the model's uncertainty for that property. Narrow where the block has many recent sales and a certificate, wide where the last comparable sold years ago. A headline that quotes the point without the range quotes more precision than exists.
Price and licence
What it costs, and where the data comes from
Valuation estimate is free over MCP and over REST, and the two surfaces share one credit balance. Free calls need a signed-in account or an API key and appear in your usage, but they never touch your balance.
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
- Ministry of Housing, Communities and Local Government
Energy Performance Certificates (domestic and non-domestic)
MHCLG's EPC open data terms · England and Wales
How the model or index is built, and where it is weak, is on the methodology page.
Related
Endpoints used with Valuation estimate
- Full valuation with back-seriesFree
valuation_fullFull valuation block for a property: the value and its range, a monthlyPairs with this - Comparable properties6 credits
property_compsComparable properties in the same building or block, with missingPairs with this - Equity gain estimateFree
equity_estimateCurrent estimated value against the last recorded sale: gain in pounds and percent, and how long it has been held.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 - Comparables with their time adjustments2 credits
comps_adjustmentsThe evidence behind a valuation, itemised: same-building comparable sales for the property, each with its registered price and date, the time adjustment by the district index to today, any relisting penalty (pass `relisted_uprns` for comps known to have been relisted and withdrawn — each takes a deterministic -10%), and the IQR fence that decided which comps count. Use it to show WHY a value is what it is; `valuation_full` gives the value itself. `lookback_months` 12–120. UK only.Same category - The property's own sale, carried to todayFree
subject_transaction_anchorThe property's own last registered sale carried to today by the district index: the price paid, the date, the index factor applied and the anchored value. Where a property has sold, this is the strongest single piece of evidence a valuation has. Returns an empty anchor when no registered sale is linked to the UPRN. UK only.Same category
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.
- Valuation range: The interval around a valuation estimate that expresses the model's own uncertainty for that property; it widens where evidence is thin.
- Credit (MarketCode): The unit MarketCode meters calls in: most tools are free, licensed and model-run tools cost a fixed number per successful call, and one balance covers MCP, REST and the products.
FAQ
Questions about Valuation estimate
How much does `valuation_estimate` cost?
+
Valuation estimate is free over MCP and over REST, and the two surfaces share one credit balance. Free calls need a signed-in account or an API key and appear in your usage, but they never touch your balance.
Do I need to resolve the address first?
+
Yes. valuation_estimate 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 valuation_estimate 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 and Ministry of Housing, Communities and Local Government EPC register. Coverage is England and Wales. The methodology page describes how the model or index is built.
Does `valuation_estimate` 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 is this different from the full valuation?
+
Same model, same estimate and range. valuation_full adds a monthly back-series carried by the local index, a rental estimate where the district supports one, and a trust score grading the evidence. It is materially more work; this is the light call.
Why 404 and not a lower-confidence number?
+
Because a value without a floor area would be a guess from location alone, and it would look exactly like a real one. Returning nothing is the honest answer; the property record and the energy tools say why the area is missing.
Can I value a whole street?
+
Yes, one UPRN at a time. address_by_postcode (10 credits) lists every address at a postcode with its UPRN; this call is free for each. A skill or a script loops them.
Try Valuation estimate on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.