Market ranking
POST /v1/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.
Same call over MCP
Rank areas on a market metricmarket_rankingAuthenticate 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/market/ranking returns
This is the comparison tool. market_facts answers for one geography; calling it in a loop to build a league table is slower, costs more and gives you rows from different periods. Use this for "which districts in Greater Manchester turn over fastest", "rank these twelve postcodes by price per sqm", "cheapest LADs in the North West by price_psm".
ALWAYS report the window block from the response alongside the ranking. It names the months aggregated, and it matters: a 12-month turnover and a 3-month one differ by roughly 4x. lag_months (default 3) deliberately drops the most recent months because HM Land Registry registers sales long after completion — the newest month looks near-dead and would rank registration lag rather than liquidity.
turnover_rate is exact — it is sales over stock, recomputed at this grain. Price, rent and yield are weighted means of the underlying medians, so describe them as indicative, not as medians.
min_stock (default 50) skips areas with too few dwellings for a rate to mean anything: one sale in a 2-dwelling district is a turnover of 0.5, which otherwise tops the table. Where a returned area still has a small stock_count, say so rather than presenting its rate as comparable.
Scope it EITHER by parent_area_code (every child of that area, e.g. every district in a county) OR by an explicit area_codes allowlist. area_type is the grain: "Postcode District" (default) or an administrative type such as "Local Authority District".
sort defaults to turnover_rate, the liquidity measure — sales as a share of the stock that could have sold. Do NOT sort on gross_yield or days_on_market: they are 0% populated, so every row ties as NULL and the "ranking" is arbitrary order. Populated metrics are sales_price, price_psm and turnover_rate. Whatever you sort on is always returned, and anything empty is named in metrics_with_no_data.
Distinct from market_volume_ranking, which ranks on raw transaction COUNT — that is market size, not liquidity.
UK only.
Request
Calling POST /v1/market/ranking
curl -X POST "https://api.marketcode.ai/v1/market/ranking" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"area_codes":["SE22","SE15","SE4","SE13"],"limit":4}'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 |
|---|---|---|---|---|
| area_type | Body | string | No | Grain to rank at: 'Postcode District' (default) or an administrative type such as 'Local Authority District'. There are no LSOA, ward, postcode-sector or postcode-unit areas.Default: Postcode District |
| parent_area_code | Body | string | No | Restrict to children of this area_code. |
| area_codes | Body | string[] | No | Explicit allowlist of area_codes to compare. |
| asset_class | Body | string | No | Default: residential |
| bedroom_band | Body | string | No | Default: all |
| hmo | Body | boolean | No | |
| metrics | Body | string[] | No | Metrics to return. Omit for the default set. Populated today: sales_price, price_psm, turnover_rate. rental_value and gross_yield are awaiting backfill and come back listed in `metrics_with_no_data`. |
| sort | Body | string | No | Metric to rank by. Defaults to turnover_rate — the only liquidity metric that is fully populated. Do NOT rank on gross_yield or days_on_market yet: they are 0% populated, so every row sorts as NULL and the ranking is arbitrary.Default: turnover_rate |
| order | Body | string | No | asc | descDefault: desc |
| limit | Body | integer | No | Default: 50 |
| window_months | Body | integer | No | Trailing whole months to aggregate over. 12 gives the conventional annual turnover rate.Default: 12 |
| lag_months | Body | integer | No | Months dropped from the end of the data before the window starts, for HM Land Registry registration lag. 0 includes the provisional months and understates turnover.Default: 3 |
| min_stock | Body | integer | No | Skip areas with fewer dwellings than this. A rate over a tiny denominator sorts straight to the top. 0 disables.Default: 50 |
Response
What POST /v1/market/ranking returns for a real request
curl -X POST "https://api.marketcode.ai/v1/market/ranking" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"area_codes":["SE22","SE15","SE4","SE13"],"limit":4}'{
"country": "UK",
"query": {
"area_type": "Postcode District",
"area_codes": [
"SE22",
"SE15",
"SE4",
"… 1 more"
],
"asset_class": "residential",
"bedroom_band": "all",
"sort": "turnover_rate",
"order": "desc",
"limit": 4,
"window_months": 12,
"lag_months": 3,
"min_stock": 50
},
"data": {
"area_type": "Postcode District",
"count": 0,
"sort": "turnover_rate",
"metrics": [
"sales_price",
"price_psm",
"turnover_rate",
"… 2 more"
],
"metrics_with_no_data": [],
"window": {
"period_from": "Oct 2025",
"period_to": "Sep 2026",
"months": 12,
"lag_months": 3,
"note": "Aggregated over whole months. turnover_rate is exact (sum of sales / mean stock); price, rent and yield are weighted means of the underlying medians, so they a…"
},
"min_stock": 50,
"areas": [],
"cached": true,
"time_ms": 0.3
},
"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 |
|---|---|---|
| country | string | UK |
| query | object | |
| query.area_type | string | Postcode District |
| query.area_codes | array | |
| query.asset_class | string | residential |
| query.bedroom_band | string | all |
| query.sort | string | turnover_rate |
| query.order | string | desc |
| query.limit | integer | 4 |
| query.window_months | integer | 12 |
| query.lag_months | integer | 3 |
| query.min_stock | integer | 50 |
| data | object | |
| data.area_type | string | Postcode District |
| data.count | integer | 0 |
| data.sort | string | turnover_rate |
| data.metrics | array | |
| data.metrics_with_no_data | array | |
| data.window | object | |
| data.window.period_from | string | Oct 2025 |
| data.window.period_to | string | Sep 2026 |
| data.window.months | integer | 12 |
| data.window.lag_months | integer | 3 |
| data.window.note | string | Aggregated over whole months. turnover_rate is e |
| data.min_stock | integer | 50 |
| data.areas | array | |
| data.cached | boolean | true |
| data.time_ms | number | 0.3 |
| credits_charged | integer | 0 |
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
Market ranking 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
- Office for National Statistics
Price Index of Private Rents and geography lookups
Open Government Licence v3 · UK
How the model or index is built, and where it is weak, is on the methodology page.
Related
Endpoints used with Market ranking
- Market facts for an areaFree
market_factsPrice, rent, yield and days-on-market by geography × asset class ×Named in the description - Rank districts by volume or priceFree
market_volume_rankingRank postcode districts by transaction volume or median price over aNamed in the description - Resolve an area nameFree
area_resolveResolve an area name or code ("Hackney", "E5") to its area_id, centroidSame product - 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.Same product - 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 - Monthly transaction volumeFree
market_volume_seriesMonthly transaction VOLUME for a postcode district, postcode area orSame product
Glossary
Terms used here
- Postcode district, area and sector: The parts of a UK postcode: the area ("SW"), the district ("SW11") and the sector ("SW11 1"); most MarketCode area statistics are published at district grain.
- Registration lag: The weeks to months between a sale completing and HM Land Registry registering it, which makes the most recent months of any sold-price series incomplete.
- 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.
FAQ
Questions about Market ranking
How much does `market_ranking` cost?
+
Market ranking 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.
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 market_ranking 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 Office for National Statistics price index of private rents and geography lookups. Coverage is the UK. The methodology page describes how the model or index is built.
Does `market_ranking` 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 Market ranking on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.