Rank areas on a market metric
market_rankingRead-onlyIdempotent
Rank areas AGAINST EACH OTHER on a market metric — one row per area,
AGGREGATED over a trailing window of whole months.
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. Free.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hmo | No | ||
| sort | No | ||
| limit | No | ||
| order | No | ||
| metrics | No | ||
| area_type | No | ||
| min_stock | No | ||
| area_codes | No | ||
| lag_months | No | ||
| asset_class | No | ||
| bedroom_band | No | ||
| window_months | No | ||
| parent_area_code | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||