Constructing Property Queries

The Datafiniti API lets you build out a wide variety of search queries so you can get the exact data you want. Queries are specified by the q parameter in the /data/properties endpoint.

Querying a single field

The simplest query you can do is querying a single field. Here's an example:

q=city:Austin

This tells the API to search the property database for any property that has the value Austin in its city field.

You can do similar queries on any of the fields in the property schema. Here's an example that queries the propertyType field:

q=propertyType:Condo

Querying multiple fields

You can run more complicated queries by combining fields with various boolean operators (e.g., AND OR). For example:

q=propertyType:Condo AND city:Austin

This returns any properties that are condos and are in the city of Austin.

You can use the OR operator to run broader queries. For example:

q=propertyType:Condo OR propertyType:"Single Family Dwelling"

That's not all though. We can group fields and operators with parentheses to do some really fancy stuff:

q=(propertyType:Condo OR propertyType:"Single Family Dwelling") AND city:Austin

Querying multiple values

If you want to query multiple values within the same field, there is a simple way to do this. For example:

q=propertyType:(Condo OR "Single Family Dwelling" OR "Multi-Family Dwelling")

This returns any properties matching any of the above property types. This is much simpler than:

q=propertyType:Condo OR propertyType:"Single Family Dwelling" OR propertyType:"Multi-Family Dwelling"

Wildcards

You can use * to query a field for any value, like this:

q=prices:*

This will return any properties that have associated pricing. This is helpful if we want to make sure any properties we get back are guaranteed to have certain fields filed out.

Wildcards can do more though. You can also append * to the value we're searching on to broaden its potential matches. For example:

q=listingName:beaut*

This will return properties with any of the following in their listingName field: beauty, beautiful, beauties, and so on.

Querying sub-fields

Several fields in our schema have sub-fields. For example, reviews has sub-fields like date, rating, and others. Everything you can do to query fields, you can also do to query sub-fields. For example:

q=reviews.rating:3

will return all businesses that have a review with a 3-star rating.

It's important to note here that querying on sub-fields will not only return sub-objects that match your query. The entire field will be returned.

For instance, if a property look likes this:

{
  "listingName": "Cool place",
  "reviews:": [
    {
      "rating": 3
    },
    {
      "rating": 4
    }
  ]
}

then you'll see both rating values in your data, even if you do q=reviews.rating:3.

Range queries

Any fields that are dates, integers, or doubles will let you search them based on a range.

q=dateAdded:[2017-01-01 TO 2017-02-01]

will return all properties that have been added to the database between Jan 1, 2017 and Feb 2, 2017.

You can do unbounded range queries as well, like:

q=dateAdded:[2017-01-01 TO *]

This will return all properties have been added since Jan 1, 2017 until the current date.

You can also use comparison operators like >, >=, <=, and <. These are helpful when you want to search for products that are cheaper or more expensive than certain limits. E.g.:

q=reviews.rating:>3

returns all properties that have reviews greater than 3..