Identify Comparables

Given a subject property, you can query this endpoint to find comparable properties. We developed a proprietary similarity score to rank candidate properties based on their similarity to the subject property. This API endpoint is useful for real estate professionals looking to find comparable properties for valuation, analysis, or market research purposes.

The score is based on the following features:

• Distance: The distance between the subject property and the comparable property.
• Market Characteristics: Similarity in demographics, transportation facilities, and other market characteristics.
• Number of Units: The number of units in the building.
• Year Built: The year the building was built. When not available online, we use Computer Vision models to detect the year built from the pictures.
• Number of Stories: The number of stories in the building. When not availability online, we use Computer Vision models to detect the number of stories from the pictures.
• Quality: The quality of the buildings, estimated from the pictures and the description.
• Building Amenities: The amenities available in the building. We use Natural Language Processing to extract this information from the text present on property’s websites.
• Unit Amenities: The amenities available in the unit. We use Natural Language Processing to extract this information from the text present on property’s websites.
• Unit Mix: The mix of units in the building. We compare unit types pair-wise to calculate the similarity score.

Get Comparable Properties

$
curl --location 'https://api.hellodata.ai/property/comparables' \
>
--header 'x-api-key: token' \
>
--header 'Content-Type: application/json' \
>
--data '{
>
  "subject": {
>
    <PropertyDetails>
>
  }
>
}'

This will return a list of properties that are similar to the subject property. The list is sorted by similarity score in descending order.

Each property simplified payload gives you high-level information, such that you can decide which properties to explore further:

1
{
2
    "comparables": [
3
        {
4
            "id": "15599d82-be17-5b45-8003-0738de431104",
5
            "lat": 41.88761,
6
            "lon": -87.63816,
7
            "year_built": 2015,
8
            "number_units": 529,
9
            "similarity_score": {
10
                "distance_meters": 573.3983428508922,
11
                "distance_miles": 0.35629409748772306,
12
                "distance": 0.6493687463773125,
13
                "number_units": 0.9894393078525705,
14
                "vintage": 1,
15
                "number_stories": 0.8753162865669926,
16
                "quality": 0.9399914771951164,
17
                "building_amenities": 0.7386363636363635,
18
                "unit_amenities": 0.26785714285714285,
19
                "unit_mix": {
20
                    "0": 0.758883952386279,
21
                    "1": 0.641025641025641,
22
                },
23
                "overall": 0.6525070566031329
24
            },
25
            "street_address": "343 West Wolf Point Plaza",
26
            "street_address_alias": [
27
                "343 West Wolf Point Plaza"
28
            ],
29
            "city": "Chicago",
30
            "state": "IL",
31
            "zip_code": "60654",
32
            "building_name": "Wolf Point West",
33
            "building_name_alias": [
34
                "Wolf Point West",
35
                "343 West Wolf Point Plaza"
36
            ]
37
        }
38
    ]
39
}

Add constraints to the comparables

You might have specific requirements for the properties you are looking for. You can add constraints to the request to filter the results:

• Set distance limits (maxDistance)
• Filter by units (minNumberUnits, maxNumberUnits)
• Filter by year built (minYearBuilt, maxYearBuilt)
• Filter by number of stories (minNumberStories, maxNumberStories)

$
curl --location 'https://api.hellodata.ai/property/comparables?max_distance=0.5&min_number_units=300&max_number_units=600&min_year_built=2010&max_year_built=2020&min_number_stories=10&max_number_stories=50' \
>
--header 'x-api-key: token' \
>
--header 'Content-Type: application/json' \
>
$
--data '{
>
  "subject": {
>
    <PropertyDetails>
>
  }
>
}'

Exclude and Include specific properties

• If you have already seen some properties and want to exclude them from the results, you can add their id to the excluded_ids array in the request. They will not appear in the results.
• You may also tell the API that you want some specific properties to be selected. In that case, you can add their id to the selected_ids array in the request. The API will return these properties first, and then if topN is high enough, it will also add best next comparables to the response.

$
curl --location 'https://api.hellodata.ai/property/comparables' \
>
--header 'x-api-key: token' \
>
--header 'Content-Type: application/json' \
>
--data '{
>
  "subject": {
>
    <PropertyDetails>
>
  },
>
  "excluded_ids": ["15599d82-be17-5b45-8003-0738de431104"],
>
  "selected_ids": ["2b3b1b3b-1b3b-1b3b-1b3b-1b3b1b3b1b3b"]
>
}'

Get the top N properties

You can also specify the number of properties you want to get in the response by setting the topN parameter in the request. You can request up to 50 comps most similar properties at once.

If you need more, you can make multiple requests with topN=50 and excluded_ids set to the id of the properties you have already seen. We encourage you to query once with 50 properties and filter results in your application for speed and performance reasons.

Speed and performance

This endpoint aggregates a lot of data to provide you with the most relevant properties. Some requests might take longer than others, depending on the number of properties in the area and the complexity of the properties. Feel free to make multiple requests in parallel, but be aware that you might hit the rate limit, or slow down the response time if you make too many requests in a short period.

Full Documentation

Find more details about the API response in our API Reference.