Comparable sold properties (comps) for a subject property

GET /api/properties/comps/

5 credits

What it returns

A ranked list of comparable sold properties within a search radius of the subject — each comp scored on similarity (size, beds/baths, year built, distance, condition delta) with the sale price and date. Powers AVM and ARV computations.

When to use it

• Build a comps table on a property report page.
• Validate AVM against the comparable set it's derived from.
• Power custom value models with raw comp inputs.

Performance

This is a slow endpoint — use a 60-second client timeout and cache responses.

Pricing

5 credits.

FAQ

How are comps ranked?

By a weighted similarity score that favors smaller size/feature deltas and shorter geographic distance. Sold date recency is a strong negative weight on older sales.

Does it adjust for condition?

Yes — if both the subject and comp have AI-condition scores, prices are adjusted up/down for the condition delta.

Fallback parameters

You can pass user-supplied values for the attributes the comp model uses, as fallbacks: Homesage.ai data is always used when available; your value is used only when our record is missing that field — so verified data is never overridden. Supported fallbacks: total_size, bedrooms, bathrooms, property_type. Only total_size can unblock an otherwise-empty result; the others just refine comp matching. year_built is intentionally not a factor in the comp/ARV model.

Every response includes a field_sources object telling you where each value came from: homesage (our data), user_provided (your fallback), or unavailable.

Parameters

• bathrooms (query) — Fallback bathroom count. Refines comp matching when Homesage.ai is missing it; used only as a fallback.
• bedrooms (query) — Fallback bedroom count. Refines comp matching when Homesage.ai is missing it; used only as a fallback.
• property_address (query, required)
• property_type (query) — Fallback property type, e.g. single_family. Refines comp matching when Homesage.ai is missing it; used only as a fallback.
• total_size (query) — Fallback square footage. Used only when Homesage.ai has no size on record — supplying it unblocks an otherwise-empty result. Verified Homesage.ai data is never overridden.

Responses

• 200
• 400 — Bad request — a required parameter is missing or failed validation. Costs 0 credits.
• 401 — Authentication failed — missing or invalid API key. Costs 0 credits.
• 402 — Payment required — no active subscription or insufficient credit balance. Costs 0 credits.
• 404 — Not found — the address could not be confidently matched to a single property. The body includes a did_you_mean array of suggested addresses (each with an mpr_id) to show the user and retry with; an empty array means no close match. Costs 0 credits.

More in AI-Powered Analysis

• Composite full property report — everything aggregated — GET /api/properties/full-report/
  The most comprehensive property analysis endpoint — aggregates 11 internal sources into a single response with 292 data fields.
• AI-derived property condition score from listing photos — GET /api/properties/property-condition/
  An AI condition assessment for a US residential property — overall condition category (Excellent/Good/Fair/Poor), confidence score, per-room breakdown when photos are available, and any flags (water damage, deferred maintenance signals).
• Property condition analysis with your own photos — POST /api/properties/property-condition-custom-photos/
  An overall property-condition rating and confidence score, combining a database lookup with AI vision analysis of property photos you supply.
• AI-powered square-footage breakdown by floor — GET /api/properties/sqft-per-floor/
  Per-floor square-footage distribution for a US residential property, derived from a multi-stage AI analysis (photo/room detection, architectural-style inference, and multi-method validation).
• LLM-powered room-by-room renovation cost breakdown — POST /api/properties/renovation-cost-breakdown/
  An itemized room-by-room renovation cost breakdown powered by a multimodal LLM analyzing the property's images plus its size/feature metadata.
• Local market outlook (buyer's/balanced/seller's) for a ZIP — GET /api/properties/market-outlook/
  A composite Market Outlook score (0-100) classifying a ZIP code as a buyer's market (<40), balanced (40-60), or seller's market (>60).
• Solar potential + AI roof condition for a property — GET /api/solar/analysis/
  Two coupled analyses in one call: