Market facts for an area
market_factsPrice, price per square metre and turnover for one area, asset class, bedroom band and period, from the market cube, with a grade on every number saying how much evidence sits behind it.
Same call over REST
Market facts/v1/market/factsNot connected yet? Connect your assistant. Sign in with your MarketCode account; no API key needed.
Reference
What market_facts answers
The market cube answers "what do two-bedroom flats in Lambeth sell for" without scanning sales at request time. Every cell is one geography, asset class, bedroom band and month, pre-computed from the sold-price record, and every cell carries a decision that says how much evidence it rests on. That decision is the reason to read this page before quoting a number.
Three metrics are populated today: sales_price, price_psm and turnover_rate. Three more exist in the schema and are empty (rental value, gross yield, days on market); the response names them under metrics_with_no_data so nobody ranks on a column of nulls.
The full description, as the assistant reads it
Metrics: sales_price, price_psm, turnover_rate are populated today. rental_value, gross_yield and days_on_market are NOT — the pipeline has never backfilled them, so they come back null and are named in the response's metrics_with_no_data. Do not compare or rank on them, and do not report a null from them as "no activity"; it means "not collected".
turnover_rate is sales as a share of the stock that could have sold. It is the liquidity measure — transaction COUNT is market size, not liquidity (W2 has the largest dwelling stock of any London district and near-bottom turnover).
Geography is postcode (resolved to its district — the cube has no sector or unit grain) or lad_code (a local-authority NAME, e.g. "Lambeth", not a GSS code). There are no LSOA or ward areas in the warehouse; those selectors return 422.
To compare AREAS against each other use market_ranking, not repeated calls here. For "how many sales" use market_volume_series — the tx_n here counts only UPRN-matched, non-anomalous sales and runs well short of the registry. The prices are sound; the count is a sample size.
READ tx_decision BEFORE QUOTING A PRICE. Every row carries one, and it says how much evidence is behind that number. Measured over the whole cube:
direct 2.7% 30+ sales in the cell. Quote it plainly.
modeled 15.4% 5-29 sales. Sound, lightly smoothed.
suppressed 44.0% 1-4 sales. Indicative — say the sample is thin.
imputed 17.3% ZERO sales. The price is the prior BORROWED from a
parent geography, not a measurement of this cohort.
missing 20.7% zero sales and no price at all (null).An imputed row looks exactly like a real one — a confident, specific figure — and it repeats: in one district, 25 cohorts all read the same 353,909, because they are all the same borrowed number. Reporting it as "2-bed detached in AL10 sell for £353,909" states a fact the data does not contain. Say the cohort has no recorded sales instead, or aggregate up to a grain that does. turnover_rate is 0 on every one of these rows, which is a second tell.
Where you want the AREA rather than a cohort, do not read a cohort row and call it the area: aggregate, or use market_ranking, which does it for you weighted by the sales behind each cohort. There is no rollup row in this cube — no bedroom_band="all" and no hmo_flag="all"; filtering on either matches nothing at all.
max_periods (default 3) bounds how many recent MONTHLY periods come back when period is not given. The grain is one row per (asset_subtype × bedroom_band × hmo_flag × period) — about 13 cohorts per period — so a wide window gets large fast. The response reports period_frequency, periods_returned and truncated so you can tell a short answer from a cut-off one.
UK only.
Reference
When to use it, and when not to
Use it for the price and liquidity of one cohort in one area: a district or a local authority, a property type, a bedroom band. Use market_ranking instead when the question compares areas; it aggregates the cube properly, weighted by the sales behind each cohort, and returns one row per area over one window, where a loop over market_facts returns rows from different periods. Use market_volume_series for "how many sales": the cube's tx_n is a UPRN-matched sample that runs well short of the registry, and is a sample size, not a count.
Inputs
Before you call it
Geography is a postcode (resolved to its district; the cube has no sector or unit grain) or a lad_code, which is a local authority name such as "Lambeth", not a GSS code. There are no LSOA or ward cells in the warehouse; those selectors return 422. max_periods (default 3) bounds how many recent months come back when period is not given; the grain is about thirteen cohorts per period, so a wide window gets large fast, and the response reports period_frequency, periods_returned and truncated so a short answer can be told from a cut-off one.
- postcode
- The postcode must be a full UK postcode ("SE22 8HN"), not a district. Where a tool works at district grain it truncates the postcode itself.
Example
An example call to market_facts
Use the MarketCode tool market_facts with {"lad_code":"Lewisham","max_periods":1} and show me the result.{
"country": "UK",
"query": {
"lad_code": "Lewisham"
},
"data": {
"area_id": "c0694b59-04d1-48ab-9a4c-c4f9d7b74f60",
"count": 3,
"metrics": [
"sales_price",
"price_psm",
"turnover_rate",
"… 2 more"
],
"period_frequency": "monthly",
"periods_returned": 3,
"max_periods": 3,
"truncated": false,
"data_through": "Dec 2026",
"facts": [
{
"area_id": "c0694b59-04d1-48ab-9a4c-c4f9d7b74f60",
"period_id": "fac8500b-8053-4a65-98d0-e46f3f57b5fe",
"period": "Dec 2026",
"period_start": "2026-12-01",
"period_frequency": "monthly",
"asset_class": "Residential",
"asset_subtype": "ALL",
"bedroom_band": "all",
"hmo_flag": "all",
"sales_price": null,
"price_psm": null,
"turnover_rate": null,
"rental_value": null,
"gross_yield": null,
"stock_count": null,
"tx_n": null,
"tx_decision": null,
"rental_listing_n": null,
"rental_listing_decision": null,
"gross_yield_decision": null
},
{
"area_id": "c0694b59-04d1-48ab-9a4c-c4f9d7b74f60",
"period_id": "3c1b4a4b-2f83-446c-ac98-3293a0e994f7",
"period": "Nov 2026",
"period_start": "2026-11-01",
"period_frequency": "monthly",
"asset_class": "Residential",
"asset_subtype": "ALL",
"bedroom_band": "all",
"hmo_flag": "all",
"sales_price": null,
"price_psm": null,
"turnover_rate": null,
"rental_value": null,
"gross_yield": null,
"stock_count": null,
"tx_n": null,
"tx_decision": null,
"rental_listing_n": null,
"rental_listing_decision": null,
"gross_yield_decision": null
},
{
"area_id": "c0694b59-04d1-48ab-9a4c-c4f9d7b74f60",
"period_id": "7ec536e8-86d8-4ec2-8833-d957c0244720",
"period": "Oct 2026",
"period_start": "2026-10-01",
"period_frequency": "monthly",
"asset_class": "Residential",
"asset_subtype": "ALL",
"bedroom_band": "all",
"hmo_flag": "all",
"sales_price": null,
"price_psm": null,
"turnover_rate": null,
"rental_value": null,
"gross_yield": null,
"stock_count": null,
"tx_n": null,
"tx_decision": null,
"rental_listing_n": null,
"rental_listing_decision": null,
"gross_yield_decision": null
}
],
"cached": true,
"time_ms": 0.5
},
"credits_charged": 0
}A real response, captured from production and trimmed: arrays to three items, long strings shortened, volatile keys dropped.
Inputs
Arguments market_facts takes
| Name | Type | Required | Description |
|---|---|---|---|
| postcode | string | No | |
| lsoa_code | string | No | |
| ward_code | string | No | |
| lad_code | string | No | |
| h3_cell | string | No | |
| asset_class | string | No | One of: Commercial, Mixed-Use, Other, Residential, Unclassified |
| asset_subtype | string | No | One of: Detached, Education, Flat, HMO, Healthcare, Hospitality, Hotel, Leisure, Office, Other, Retail, Semi-Detached, Terraced, Transport |
| bedroom_band | string | No | One of: 1bed, 2bed, 3bed, 4bed, 5plus, unknown |
| period | string | No | |
| max_periods | integer | No | |
| metrics | string[] | No |
Response
What comes back
| Field | Type | Example |
|---|---|---|
| country | string | UK |
| query | object | |
| query.lad_code | string | Lewisham |
| data | object | |
| data.area_id | string | c0694b59-04d1-48ab-9a4c-c4f9d7b74f60 |
| data.count | integer | 3 |
| data.metrics | array | |
| data.period_frequency | string | monthly |
| data.periods_returned | integer | 3 |
| data.max_periods | integer | 3 |
| data.truncated | boolean | false |
| data.data_through | string | Dec 2026 |
| data.facts | array | |
| data.facts[].area_id | string | c0694b59-04d1-48ab-9a4c-c4f9d7b74f60 |
| data.facts[].period_id | string | fac8500b-8053-4a65-98d0-e46f3f57b5fe |
| data.facts[].period | string | Dec 2026 |
| data.facts[].period_start | string | 2026-12-01 |
| data.facts[].period_frequency | string | monthly |
| data.facts[].asset_class | string | Residential |
| data.facts[].asset_subtype | string | ALL |
| data.facts[].bedroom_band | string | all |
| data.facts[].hmo_flag | string | all |
| data.facts[].sales_price | null | |
| data.facts[].price_psm | null | |
| data.facts[].turnover_rate | null | |
| data.facts[].rental_value | null | |
| data.facts[].gross_yield | null | |
| data.facts[].stock_count | null | |
| data.facts[].tx_n | null | |
| data.facts[].tx_decision | null | |
| data.facts[].rental_listing_n | null | |
| data.facts[].rental_listing_decision | null | |
| data.facts[].gross_yield_decision | null | |
| data.cached | boolean | true |
| data.time_ms | number | 0.5 |
| 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
- Read
tx_decisionbefore quoting a price. Over the whole cube: direct (30+ sales) 2.7%, modelled (5 to 29) 15.4%, suppressed (1 to 4) 44.0%, imputed (zero sales, price borrowed from the parent geography) 17.3%, missing 20.7%. An imputed row looks exactly like a real one and repeats: in one district twenty-five cohorts all read the same £353,909 because they are the same borrowed number.turnover_rateis 0 on every imputed row, which is the second tell. - There is no rollup row. No
bedroom_band="all"and nohmo_flag="all"; filtering on either matches nothing. For the area rather than a cohort, aggregate or usemarket_ranking. - Turnover is the liquidity measure. Sales as a share of the stock that could have sold. Transaction count is market size, not liquidity: W2 has the largest dwelling stock of any London district and near-bottom turnover.
Usage
How to run market_facts in your assistant
Ask your assistant in plain English, for example:
"Use the MarketCode tool market_facts for <address or area>.
Show the result and the credits charged."
The arguments the assistant will send, for the example on this page:
{"lad_code":"Lewisham","max_periods":1}The connect steps for Claude, ChatGPT, Codex, Cursor and Claude Code are on the MCP page.
Skills
Skills that use market_facts
- Property research: A sourced answer to any UK property question: the right tool for the job, the credit cost stated first, the wording rules that keep an estimate an estimate.
- Valuation report: An indicative valuation for one address: the range, the comparables and adjustments, the index position, the EPC, flood and planning context, and the reasoning, with every figure cited to the tool it came from.
- Area insights: A market brief for any UK area: the published indices, volumes, listing stock, agent activity and auction outcomes, compared and ranked against neighbours.
- Site and unit sourcing: A shortlist of land or units matching your criteria, scored, with the registered owner resolved for each and a recipient list ready for outreach.
- Deal analysis: A first-pass appraisal of a site or asset: plot utilisation, planning position, market evidence, value and a residual against the cost assumptions you supply.
Price and licence
What it costs, and where the data comes from
market_facts 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
How the model or index is built, and where it is weak, is on the methodology page.
Related
Tools used with market_facts
- Rank areas on a market metricFree
market_rankingRank areas against each other on a market metric — one row per area at the latest period. Defaults to turnover_rate, which is sales as a share of the stock that could have sold: the liquidity measure, as opposed to transaction count, which measures market size.Pairs with this - Monthly transaction volumeFree
market_volume_seriesMonthly transaction VOLUME for a postcode district, postcode area orPairs 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 - Resolve an area nameFree
area_resolveResolve an area name or code ("Hackney", "E5") to its area_id, centroidPairs with this - Asking-price index (portal listings)Free
asking_price_index_seriesHedonic ASKING-PRICE index for one postcode district, local authority or Great Britain, from portal listings (Rightmove ~95%), 2022M01 = 100, with 80% bands and posterior standard errors, smoothed toward the parent geography.Same product - Live listings stock, dailyFree
listing_stock_seriesLive listings on the market by day for one area, channel and bedroom band — the stock-on-market series, with the median age of the dated live stock, median asking price or rent, and the new-build count.Same product
Glossary
Terms used here
- Local authority district (LAD): The council area a property sits in: about 360 in Great Britain, the second geography MarketCode publishes indices and rankings for.
- Price per square metre (£/m²): Sale or asking price divided by internal floor area; the one number that makes properties of different sizes comparable, and what the valuation back-series is scaled by.
- Market cube: MarketCode's pre-computed table of price, price per square metre and turnover for every area, asset class, bedroom band and month, with a graded decision on how much evidence sits behind each cell.
- Turnover rate: Sales in a period as a share of the dwellings that could have sold; the liquidity measure, distinct from the raw count of sales, which measures market size.
- House in multiple occupation (HMO): A property let to three or more tenants from more than one household who share facilities; licensed by the council above five occupants and often restricted by Article 4.
FAQ
Questions about market_facts
How much does `market_facts` cost?
+
market_facts 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.
Which assistants can run `market_facts`?
+
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.
Does `market_facts` 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.
What does a price with tx_decision "imputed" mean?
+
That the cohort had no recorded sales in the period and the price shown is the prior borrowed from the parent geography. It is not a measurement of that cohort. Say the cohort has no recorded sales, or aggregate up to a grain that does.
Why does the sale count differ from HM Land Registry's?
+
Because the cube counts only UPRN-matched, non-anomalous sales, which run 17 to 66% short of the registry depending on the area. The prices are sound; the count is the sample behind them. For counts use market_volume_series, which reads Price Paid directly.
Can I get rents and yields from this?
+
Not yet. rental_value, gross_yield and days_on_market are in the schema and unpopulated. Rent levels and yields are in listing_market_series, from portal listings, by area and bedroom band.
Try market_facts in your assistant.
30-minute call. We'll connect your assistant live on a real address.