Comparables

Returns ranked sold comparables around a UK postcode, matched via PostGIS spatial search. Each comparable carries a similarity_score, a confidence_tier, a source_attribution, and flags that surface distressed or flip transactions, so you can build a defensible valuation rather than a flat list of nearby sales.

Attribution is per row, not per response. HM Land Registry Price Paid Data covers England and Wales only. Scottish comparables come from Registers of Scotland sold-price data supplied through our aggregation partners; Northern Irish comparables are estate agent asking prices, not completed sales, because Land & Property Services NI transaction data is not held. Read the source_attribution field on each comparable, or the response-level sources array, and cite that — never a single national registry.

Required scope: market-data:read · Cost: 1 request

GET /api/v1/comparables

Authenticate with a paid API key (Authorization: Bearer paid_your_key). The endpoint also accepts a logged-in Clerk session when called from the dashboard. Anonymous requests are rejected.

Query parameters

Param	Type	Default	Description
`postcode`	string	—	Required. Full postcode or outcode, e.g. `M1` or `M1 4WP`.
`bedrooms`	integer	—	Optional. Restrict to a bedroom count, `0`–`10`.
`type`	string	—	Optional. Property-type substring, e.g. `flat`, `terraced`, `detached`.
`radius_miles`	float	`0.5`	Optional. Search radius from the postcode centroid. Range `0.1`–`5.0`.
`limit`	integer	`20`	Optional. Maximum comparables to return. Range `1`–`50`.

Request

curl "https://api.propaideals.co.uk/api/v1/comparables?postcode=M1%204WP&bedrooms=2&type=flat&radius_miles=0.5&limit=20" \
  -H "Authorization: Bearer paid_your_key"

import requests

res = requests.get(
    "https://api.propaideals.co.uk/api/v1/comparables",
    params={
        "postcode": "M1 4WP",
        "bedrooms": 2,
        "type": "flat",
        "radius_miles": 0.5,
        "limit": 20,
    },
    headers={"Authorization": "Bearer paid_your_key"},
)
data = res.json()["data"]
for c in data["comparables"]:
    print(f"{c['address']}: £{c['price']:,} ({c['confidence_tier']})")

const params = new URLSearchParams({
  postcode: "M1 4WP",
  bedrooms: "2",
  type: "flat",
  radius_miles: "0.5",
  limit: "20",
});
const res = await fetch(
  `https://api.propaideals.co.uk/api/v1/comparables?${params}`,
  { headers: { Authorization: "Bearer paid_your_key" } }
);
const { data } = await res.json();
data.comparables.forEach((c) =>
  console.log(`${c.address}: £${c.price.toLocaleString()} (${c.confidence_tier})`)
);

Response

{
  "data": {
    "postcode": "M1 4WP",
    "count": 2,
    "sources": [
      "HM Land Registry Price Paid Data (England and Wales)"
    ],
    "comparables": [
      {
        "address": "14 Example Court, Manchester, M1 4WP",
        "price": 215000,
        "sale_date": "2025-11-22",
        "property_type": "flat",
        "property_type_source": "Purpose Built Flat",
        "bedrooms": 2,
        "distance_miles": 0.08,
        "similarity_score": 94,
        "confidence_tier": "gold",
        "transaction_category": "standard",
        "is_likely_flip": false,
        "floor_area_sqft": 712,
        "floor_area_source": "measured",
        "price_per_sqft": 301,
        "price_per_sqft_is_estimated": false,
        "price_per_sqft_note": null,
        "price_per_bedroom": 107500,
        "tenure": "Leasehold",
        "jurisdiction": "england_wales",
        "tenure_note": null,
        "source_attribution": "HM Land Registry Price Paid Data (England and Wales)",
        "energy_rating": "C",
        "latitude": 53.4751,
        "longitude": -2.2301
      },
      {
        "address": "9 Sample House, Manchester, M1 4WT",
        "price": 168000,
        "sale_date": "2025-07-03",
        "property_type": "flat",
        "property_type_source": "Flat/Maisonette",
        "bedrooms": 2,
        "distance_miles": 0.31,
        "similarity_score": 61,
        "confidence_tier": "bronze",
        "transaction_category": "non_standard",
        "is_likely_flip": true,
        "floor_area_sqft": 688,
        "floor_area_source": "building_estimate",
        "price_per_sqft": 244,
        "price_per_sqft_is_estimated": true,
        "price_per_sqft_note": "Imputed: the EPC certificate behind this size was attached by whole-address similarity, which every flat in one block passes. Treat the size, and any price per square foot derived from it, as an order of magnitude.",
        "price_per_bedroom": 84000,
        "tenure": "Leasehold",
        "jurisdiction": "england_wales",
        "tenure_note": null,
        "source_attribution": "HM Land Registry Price Paid Data (England and Wales)",
        "energy_rating": "D",
        "latitude": 53.4769,
        "longitude": -2.2358
      }
    ]
  },
  "meta": {
    "usage": {
      "request_cost": 1,
      "monthly_used": 1438,
      "monthly_limit": 20000
    }
  }
}

Response fields

Field	Type	Description
`postcode`	string	The postcode the search was run for.
`count`	integer	Number of comparables returned.
`sources`	array	The distinct `source_attribution` values present in `comparables`, sorted.
`comparables`	array	Ranked comparable sales (see per-item fields below).

Each item in comparables:

Field	Type	Description
`address`	string	Full address of the comparable.
`price`	number	Sold price in £.
`sale_date`	string	Transaction date (`YYYY-MM-DD`).
`property_type`	string \| null	One vocabulary across every source: `flat`, `terraced`, `semi-detached`, `detached`, `bungalow`, `house`, `studio`, `maisonette`, `land`, `commercial`, `parking`, `caravan`, `other`. Safe to send straight back as the `type` filter. `null` when the source recorded no type.
`property_type_source`	string \| null	The supplier’s own words, unedited — `"Mid Terrace House"`, `"Purpose Built Flat"`, `"Semi-Detached"`. Audit trail only; do not filter on it.
`bedrooms`	integer \| null	Bedroom count where known.
`distance_miles`	number	Distance from the search postcode.
`similarity_score`	integer	Composite similarity to the search criteria, `0`–`100`.
`confidence_tier`	string	`gold`, `silver`, `bronze`, `supporting`, or `excluded`.
`transaction_category`	string \| null	`standard` or `non_standard`. `null` outside England and Wales — the classification comes from the HM Land Registry PPD category, and Scotland and Northern Ireland keep their own registers, so the flag is unavailable rather than negative.
`transaction_category_note`	string \| null	Why `transaction_category` is `null`, when that absence has an explanation. `null` when the category is populated.
`is_likely_flip`	boolean	`true` when the same address re-sold within ~3 years for a large uplift.
`floor_area_sqft`	number \| null	Floor area in square feet where known.
`floor_area_source`	string	`measured`, `building_estimate`, `unverified` or `absent`. See Floor area and £/sqft below.
`price_per_sqft`	number \| null	`price / floor_area_sqft`, in £, truncated to whole pounds. `null` when no floor area is held.
`price_per_sqft_is_estimated`	boolean	`true` unless `floor_area_source` is `measured`.
`price_per_sqft_note`	string \| null	Why the figure is qualified, when it is.
`price_per_bedroom`	number \| null	`price / bedrooms`, in £.
`tenure`	string \| null	`Freehold` or `Leasehold` in England, Wales and Northern Ireland. `Ownership` or `null` in Scotland — see `tenure_note` and the note below.
`jurisdiction`	string \| null	`scotland`, `england_wales`, `northern_ireland`, or `unknown`.
`tenure_note`	string \| null	Why `tenure` reads the way it does when the jurisdiction changed it. Scottish rows only.
`source_attribution`	string \| null	Where this row came from.
`energy_rating`	string \| null	EPC band, A–G.
`latitude`	number	Latitude (WGS84).
`longitude`	number	Longitude (WGS84).

Property type

Comparables are drawn from three registers that each name the same dwelling differently. Zoopla says Semi-Detached House, Flat/Maisonette, Purpose Built Flat, Converted Flat, Mid Terrace House; HM Land Registry stores D/S/T/F, which the comparables query expands to Detached/Semi-Detached/Terraced/Flat; Rightmove uses semi_detached. One ranked list could therefore contain seven labels for four kinds of dwelling. property_type publishes one vocabulary for all of them: flat · terraced · semi-detached · detached · bungalow · house · studio · maisonette · land · commercial · parking · caravan · other house is a house whose subtype the source never stated (terraced vs semi-detached vs detached unknown). It is a real value, not a labelling error: some suppliers list only “house”, and subtype-specific filters (and the playbooks that gate on a specific house type) will not select those rows. The published value is always a value you can send straight back as type= and get that row again — the mapping is chosen so the label selects its own row. property_type_source carries the supplier’s original string so you can audit the mapping. Two consequences worth knowing:

Semi-Detached Bungalow publishes as semi-detached, not bungalow. The structure decides the bucket the filter uses; the bungalow detail stays in property_type_source.
/api/v1/market-data is deliberately not on this vocabulary. Its property_type is HM Land Registry’s own D/S/T/F code, which is also its filter value — translating it there would break the filter it echoes.

Floor area and £/sqft

A floor area is not always a measurement of the dwelling it is attached to. Most areas come from an EPC certificate, and a certificate routinely covers a whole block: 3,071,054 of the 26,755,813 Land Registry floor areas — 11.5%, measured 2026-08-13 — were attached by whole-address similarity, the rule that matches “Flat 3, 12 High Street” to “Flat 8, 12 High Street”. Dividing by such an area produces an exact-looking £/sqft whose precision is manufactured by the division. floor_area_source says which case you are in:

Value	Meaning
`measured`	The certificate was matched to this address (`uprn_match_method = 'epc_exact'`). Safe to treat `price_per_sqft` as this property’s own.
`building_estimate`	Attached at building level — a fuzzy whole-address match, or one certificate fanned across a block. Treat the size, and anything divided by it, as an order of magnitude.
`unverified`	A real area whose source records nothing about which address it was measured at. Every Zoopla row is in this state: `zoopla_properties` stores the certificate key but not how it was chosen. Not proven imputed — but not publishable as measured either.
`absent`	No floor area, so `price_per_sqft` is `null`.

price_per_sqft_is_estimated is true for everything except measured. It is deliberately asymmetric: absent evidence of a measurement is not evidence of one. The subject property’s own £/sqft, on the same footing, is returned by /api/v1/rental-estimate.

Confidence tiers

The confidence_tier ranks how directly comparable each sale is, combining similarity, distance, and recency:

Tier	Meaning
`gold`	Closest matches — same area, type, and size; safe to anchor on.
`silver`	Strong matches with minor differences.
`bronze`	Looser matches; useful context, weight with care.
`supporting`	Peripheral evidence only.
`excluded`	Filtered from the headline valuation (kept for transparency).

Tenure outside England and Wales

Freehold and Leasehold are estates in English land law. Neither exists in Scotland. Feudal tenure was abolished by the Abolition of Feudal Tenure etc. (Scotland) Act 2000, and residential long leases converted to outright ownership under the Long Leases (Scotland) Act 2012. A comparable with jurisdiction: "scotland" therefore returns:

Underlying value	`tenure`	Why
Freehold / Feudal	`Ownership`	Terminology correction — both describe the outright ownership the 2000 Act converted feudal estates into.
Leasehold	`null`	The true position is not recoverable from the data held, so nothing is asserted.
Occupancy labels (`owner-occupied`, `rented (private)`, …)	`null`	Never a tenure in any jurisdiction.

Northern Ireland is unaffected: freehold and leasehold both genuinely exist there. Where a postcode district straddles the border (TD12, TD15) and no stronger evidence is held, jurisdiction is unknown and the tenure is passed through untouched rather than rewritten on a guess.

Distressed and flip flags

Two flags help you discount sales that do not reflect open-market value:

transaction_category: "non_standard" marks sales recorded under HM Land Registry PPD category B — repossessions, right-to-buy, auction, and family transfers. These often sit below open-market value.
is_likely_flip: true marks an address that re-sold within roughly three years for a large uplift, which can inflate an apparent local price level.

For a robust valuation, lean on gold and silver comparables and exclude or down-weight rows flagged non_standard or is_likely_flip. Widen radius_miles only if the closer tiers return too few rows.

Get started

API reference

Granular endpoints

Resources

Comparables endpoint

Comparables

Query parameters

Request

Response

Response fields

Property type

Floor area and £/sqft

Confidence tiers

Tenure outside England and Wales

Distressed and flip flags

​Comparables

​Query parameters

​Request

​Response

​Response fields

​Property type

​Floor area and £/sqft

​Confidence tiers

​Tenure outside England and Wales

​Distressed and flip flags

Comparables

Query parameters

Request

Response

Response fields

Property type

Floor area and £/sqft

Confidence tiers

Tenure outside England and Wales

Distressed and flip flags