> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.repliers.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Finding Comparables by Address - Implementation Guide

This guide demonstrates how to find comparable sold or leased properties for a specific address using the Repliers API. The process involves two main steps: first, searching for the subject property by address to obtain its attributes, then using those attributes to find comparable properties.

## Overview

The implementation consists of two API calls:

1. **Address Search**: Find the subject property and extract its key attributes
2. **Comparables Search**: Use the extracted attributes to find similar sold/leased properties

## Step 1: Address Search with Autocomplete

### User Interface Implementation

Start by implementing an autocomplete address input field that allows users to type and select from a dropdown of matching properties.

### API Request for Address Search

Use the search parameter combined with searchFields to find the subject property:

```
GET https://api.repliers.io/listings?search=101 Yonge St&searchFields=address.streetName,address.streetNumber
```

### Including All Listing Statuses

To ensure you capture the property regardless of its current status, include both active and unavailable listings:

```
GET https://api.repliers.io/listings?search=101 Yonge St&searchFields=address.streetName,address.streetNumber&status=["A","U"]
```

### Optimizing the Response with Fields Parameter

To improve performance and reduce payload size, use the `fields` parameter to only return the attributes you need for the comparables search:

```
GET https://api.repliers.io/listings?search=101 Yonge St&searchFields=address.streetName,address.streetNumber&status=["A","U"]&fields=details.numBedrooms,details.numBathrooms,map.lat,map.long,details.propertyType,details.sqft,address.city,address.streetName,address.streetNumber,type
```

### Example API Response

Here's what a typical response looks like with the optimized fields:

```json
{
  "listings": [
    {
      "details": {
        "numBedrooms": 3,
        "numBathrooms": 2,
        "propertyType": "Apartment",
        "sqft": 1200
      },
      "map": {
        "lat": 43.6532,
        "long": -79.3832
      },
      "address": {
        "city": "Toronto",
        "streetName": "Yonge St",
        "streetNumber": "101"
      },
      "type": "sale"
    }
  ]
}
```

### Extracting Key Attributes from Response

From the API response, extract these essential attributes for the comparables search:

* `details.numBedrooms` - Number of bedrooms
* `details.numBathrooms` - Number of bathrooms
* `map.lat` - Latitude coordinate
* `map.long` - Longitude coordinate
* `details.propertyType` - Property type (e.g., Apartment, House)
* `details.sqft` - Square footage
* `address.city` - City name
* `type` - Listing type (sale or lease)

## Step 2: Finding Comparables

### Building the Comparables Search Request

Using the attributes extracted from Step 1, construct a search for comparable properties that have been sold or leased.
**Example Request:**

```
GET https://api.repliers.io/listings?status=U&lastStatus=Sld&type=sale&minSqft=950&maxSqft=1050&city=New York&propertyType=Apartment&lat=40.0&long=-80&radius=2&minBeds=3&maxBeds=3
```

### Key Parameters for Comparables Search

**Status and Transaction Type:**

* `status=U` - Search for unavailable properties (sold/leased)
* `lastStatus=Sld` - Filter for sold properties (use `Lsd` for leased)
* `type=sale` - Properties that were for sale (use `lease` for rentals)

**Property Characteristics:**

* `propertyType` - Match the property type from Step 1
* `minBeds` & `maxBeds` - Set bedroom range (can use exact match)
* `minBaths` & `maxBaths` - Set bathroom range (optional)
* `minSqft` & `maxSqft` - Set square footage range (±50-100 sqft recommended)

**Location Parameters:**

* `city` - Limit search to same city
* `lat` & `long` - Center point for radius search
* `radius` - Search radius in kilometers (typically 1-3 km)

## Complete Implementation Example

### Step 1: Address Search

```javascript
// User types "123 Main Street, Toronto"
const addressQuery = "123 Main Street";
const fieldsParam = "details.numBedrooms,details.numBathrooms,map.lat,map.long,details.propertyType,details.sqft,address.city,address.streetName,address.streetNumber,type";
const searchUrl = `https://api.repliers.io/listings?search=${encodeURIComponent(addressQuery)}&searchFields=address.streetName,address.streetNumber&status=["A","U"]&fields=${fieldsParam}`;

const subjectProperty = await fetch(searchUrl);
const propertyData = await subjectProperty.json();

// Extract attributes from the first result
const property = propertyData.listings[0];
const attributes = {
  bedrooms: property.details.numBedrooms,
  bathrooms: property.details.numBathrooms,
  latitude: property.map.lat,
  longitude: property.map.long,
  propertyType: property.details.propertyType,
  sqft: property.details.sqft,
  city: property.address.city,
  listingType: property.type
};
```

### Step 2: Find Comparables

```javascript
// Build comparables search with ±50 sqft variance and 2km radius
const compsUrl = `https://api.repliers.io/listings?` +
  `status=U&` +
  `lastStatus=Sld&` +
  `type=${attributes.listingType}&` +
  `minSqft=${attributes.sqft - 200}&` +
  `maxSqft=${attributes.sqft + 200}&` +
  `city=${encodeURIComponent(attributes.city)}&` +
  `propertyType=${attributes.propertyType}&` +
  `lat=${attributes.latitude}&` +
  `long=${attributes.longitude}&` +
  `radius=2&` +
  `minBeds=${attributes.bedrooms}&` +
  `maxBeds=${attributes.bedrooms}`;

const comparables = await fetch(compsUrl);
const compsData = await comparables.json();
```

## Best Practices

### Search Range Adjustments

**Square Footage**: Use ±50-100 sqft range for apartments, ±200-300 sqft for houses
**Radius**: Start with 1-2 km in urban areas, 3-5 km in suburban areas
**Bedrooms**: Exact match is typically preferred, but ±1 bedroom can be acceptable

### Error Handling

* Handle cases where no subject property is found by address
* Implement fallback searches with broader criteria if no comparables are found
* Validate that essential attributes (lat, long, propertyType) are present

### User Experience

* Display the subject property details before showing comparables
* Allow users to adjust search criteria (radius, sqft range) if needed
* Sort results by relevance (distance, similarity, sale date)

## Troubleshooting

**No results for address search:**

* Try broader search terms (street name only)
* Check for typos in address
* Verify the property exists in the database

**No comparable properties found:**

* Increase the radius parameter
* Widen the sqft range
* Remove optional filters (bathrooms, exact bedroom match)
* Consider expanding to nearby cities

## Summary

By combining address search with comparables search, you can efficiently find relevant sold or leased properties for any given address. The key is extracting accurate property attributes from the initial address search and using appropriate range parameters to balance specificity with result quantity.

# What questions does this article answer?

* How do I build a workflow to find comparables starting from a typed address?  
* How do I use `search` + `searchFields` to first locate the subject property by address?  
* Which fields should I request to then build a comparables query (beds, baths, sqft, lat/long, propertyType, city, type)?  
* How do I construct the second API call using the subject property’s attributes to fetch sold/leased comparables?  
* How should I design an autocomplete UI that feeds into this comparables flow?