Get Sales Comps
Find sale comparables (sales comps) for a property, ranked by
similarity score, flattened into ready-to-use sales-comp records.
Each comparable includes `distance` (miles from the subject property),
`score` (overall similarity, higher is more similar), `scoreDetail`
(per-factor breakdown showing each factor's score and the normalized
weight actually applied), and the sales-comp facts flattened onto the
record: name, address, city, state, zipCode, `status` ("LISTED" for
on-market comps, "SOLD" for off-market ones), listPrice and
listingDate, salePrice and saleDate, buyer, seller, the sale's
confidenceVerdict and confidenceReasons, transactionType,
pricePerSquareFoot and pricePerUnit (from the sale record when
available, otherwise derived from the status-correct price), plus
squareFootage, unitsQuantity, constructionYear, stories and
propertyStyle. Listing and sale facts are populated independently, so
a sold comp that was previously listed carries both.
Call this to find sale comps for a property — e.g. for valuation,
underwriting, or screening recent transactions — narrowing the pool
with any combination of the filters below. All filters except
`max_distance` are optional; omitted filters don't constrain results.
Some matches are removed from the response after ranking, mirroring
how Keyway curates sales comps: single-unit properties, off-market
comps with no sale record, and comps whose last sale is flagged
EXCLUDE. `total` counts matches before this curation, so a page may
contain fewer than `size` items; sending
confidence_verdicts=["VALID_HIGH", "VALID_WITH_NOTES", "REVIEW"] and
min_unit_quantity=2 pushes most of the curation into the search
itself.
Inputs
| Parameter | Required | Type | Details |
|---|---|---|---|
activity_date_from | No | anyOf | "YYYY-MM-DD"; only comparables with market activity (a listing or sale) on or after this date. E.g. send a date 18 months back to keep sales recent. Default: null |
activity_date_to | No | anyOf | "YYYY-MM-DD"; only comparables with market activity on or before this date. Default: null |
address | No | anyOf | Case-insensitive partial match on the property address. Default: null |
confidence_verdicts | No | anyOf | Filters by the confidence verdict of each comparable's last sale. Values: "VALID_HIGH" (high-confidence sale), "VALID_WITH_NOTES" (valid with caveats), "REVIEW" (needs review), "EXCLUDE" (flagged to exclude). Default: null |
has_affordable_units | No | anyOf | True to require affordable units, False to exclude properties that have them. Default: null |
housing_segments | No | anyOf | Only these housing segments. Values: "STUDENT", "SENIOR", "CORPORATE", "MILITARY", "CONVENTIONAL". Default: null |
max_construction_year | No | anyOf | Only comparables built in or before this year. Default: null |
max_distance | No | number | Search radius in miles around the subject property. Between 0 (exclusive) and 200; default 5. Default: 5 |
max_occupancy_percentage | No | anyOf | Maximum occupancy (0-100). Default: null |
max_score | No | anyOf | Only comparables with similarity score <= this value. Default: null |
max_square_footage | No | anyOf | Maximum total square footage. Default: null |
max_stories | No | anyOf | Maximum number of stories. Default: null |
max_unit_quantity | No | anyOf | Maximum number of units. Default: null |
min_construction_year | No | anyOf | Only comparables built in or after this year. Default: null |
min_distance | No | anyOf | Minimum distance in miles (0-200), e.g. to exclude the subject's immediate surroundings. Default: null |
min_occupancy_percentage | No | anyOf | Minimum occupancy (0-100). Default: null |
min_score | No | anyOf | Only comparables with similarity score >= this value. Default: null |
min_square_footage | No | anyOf | Minimum total square footage. Default: null |
min_stories | No | anyOf | Minimum number of stories. Default: null |
min_unit_quantity | No | anyOf | Minimum number of units. Default: null |
name | No | anyOf | Case-insensitive partial match on the property name. Default: null |
offset | No | anyOf | Pagination offset (default 0). Default: null |
order | No | anyOf | Sort direction, "ASC" or "DESC". Default: null |
order_by | No | anyOf | Sort field, "SCORE" (default) or "DISTANCE". Default: null |
property_id | Yes | string | Keyway property ID of the subject property. |
property_styles | No | anyOf | Only these building styles. Values: "LOW_RISE", "MID_RISE", "HIGH_RISE", "GARDEN", "TOWNHOME". Default: null |
size | No | integer | Page size, 1-50 (default 10). The response's `total` says how many comparables matched overall. Default: 10 |
source_types | No | anyOf | Only these market statuses. "ON_MARKET" keeps currently listed comps; "OFF_MARKET" and "PRE_MARKET" keep sold ones. Default: null |
total | No | anyOf | Echo back a previously returned `total` to let the service skip recounting when paginating through the same query. Default: null |
weight_activity_date | No | anyOf | Similarity-weight override, see below. Default: null |
weight_construction_year | No | anyOf | Similarity-weight override, see below. Default: null |
weight_distance | No | anyOf | Similarity-weight override, see below. Default: null |
weight_property_amenities | No | anyOf | Similarity-weight override, see below. Default: null |
weight_quality | No | anyOf | Similarity-weight override, see below. Default: null |
weight_square_footage_per_unit | No | anyOf | Similarity-weight override, see below. Default: null |
weight_stories | No | anyOf | Similarity-weight override, see below. Default: null |
weight_style | No | anyOf | Similarity-weight override, see below. Default: null |
weight_unit_amount | No | anyOf | Similarity-weight override, see below. Default: null |
weight_unit_mix | No | anyOf | Similarity-weight override, see below. Default: null |
weight_units_amenities | No | anyOf | Similarity-weight override, see below. Default: null |
Annotations
{
"title": "Get Sales Comps",
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false
}
Input schema
{
"type": "object",
"additionalProperties": false,
"properties": {
"property_id": {
"type": "string",
"description": "Keyway property ID of the subject property."
},
"max_distance": {
"default": 5,
"type": "number",
"description": "Search radius in miles around the subject property.\nBetween 0 (exclusive) and 200; default 5."
},
"min_distance": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum distance in miles (0-200), e.g. to exclude\nthe subject's immediate surroundings."
},
"min_construction_year": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Only comparables built in or after this year."
},
"max_construction_year": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Only comparables built in or before this year."
},
"min_occupancy_percentage": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum occupancy (0-100)."
},
"max_occupancy_percentage": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum occupancy (0-100)."
},
"min_unit_quantity": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum number of units."
},
"max_unit_quantity": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum number of units."
},
"min_square_footage": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum total square footage."
},
"max_square_footage": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum total square footage."
},
"min_stories": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum number of stories."
},
"max_stories": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum number of stories."
},
"min_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Only comparables with similarity score >= this value."
},
"max_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Only comparables with similarity score <= this value."
},
"offset": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination offset (default 0)."
},
"size": {
"default": 10,
"type": "integer",
"description": "Page size, 1-50 (default 10). The response's `total` says\nhow many comparables matched overall."
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Echo back a previously returned `total` to let the service\nskip recounting when paginating through the same query."
},
"order_by": {
"anyOf": [
{
"enum": [
"SCORE",
"DISTANCE"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort field, \"SCORE\" (default) or \"DISTANCE\"."
},
"order": {
"anyOf": [
{
"enum": [
"ASC",
"DESC"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort direction, \"ASC\" or \"DESC\"."
},
"activity_date_from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "\"YYYY-MM-DD\"; only comparables with market\nactivity (a listing or sale) on or after this date. E.g. send\na date 18 months back to keep sales recent."
},
"activity_date_to": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "\"YYYY-MM-DD\"; only comparables with market\nactivity on or before this date."
},
"property_styles": {
"anyOf": [
{
"items": {
"enum": [
"LOW_RISE",
"MID_RISE",
"HIGH_RISE",
"GARDEN",
"TOWNHOME"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Only these building styles. Values: \"LOW_RISE\",\n\"MID_RISE\", \"HIGH_RISE\", \"GARDEN\", \"TOWNHOME\"."
},
"housing_segments": {
"anyOf": [
{
"items": {
"enum": [
"STUDENT",
"SENIOR",
"CORPORATE",
"MILITARY",
"CONVENTIONAL"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Only these housing segments. Values: \"STUDENT\",\n\"SENIOR\", \"CORPORATE\", \"MILITARY\", \"CONVENTIONAL\"."
},
"has_affordable_units": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True to require affordable units, False to\nexclude properties that have them."
},
"source_types": {
"anyOf": [
{
"items": {
"enum": [
"ON_MARKET",
"OFF_MARKET",
"PRE_MARKET"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Only these market statuses. \"ON_MARKET\" keeps\ncurrently listed comps; \"OFF_MARKET\" and \"PRE_MARKET\" keep\nsold ones."
},
"confidence_verdicts": {
"anyOf": [
{
"items": {
"enum": [
"VALID_HIGH",
"VALID_WITH_NOTES",
"REVIEW",
"EXCLUDE"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Filters by the confidence verdict of each\ncomparable's last sale. Values: \"VALID_HIGH\" (high-confidence\nsale), \"VALID_WITH_NOTES\" (valid with caveats), \"REVIEW\"\n(needs review), \"EXCLUDE\" (flagged to exclude)."
},
"address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Case-insensitive partial match on the property address."
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Case-insensitive partial match on the property name."
},
"weight_distance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_construction_year": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_square_footage_per_unit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_unit_amount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_activity_date": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_unit_mix": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_property_amenities": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_units_amenities": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_quality": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_style": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
},
"weight_stories": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Similarity-weight override, see below."
}
},
"required": [
"property_id"
]
}