This reference documents version 2.1 of the Placester RESTful API.

The code in this document requires an API key which you can obtain from the Placester plugin.

Aggregate will provide a list of unique items of the type specified in the keys[] array. You use all the same filters used in Listings but rather than outputting the entire listing data, aggregate will only list out the unique values for that particular key.

For instance, if you have a filter for all 2 bedroom listings, then choose neighborhoods for your aggregate keys, you will get a list of neighborhoods with 2 bedroom listings.

Basic Use

  http://api.placester.com/api/v2.1/listings/aggregate[.format]?api_key=xxxxxxxxxxxxxxxxxxxxxxxxxxkeys[]=AggregateKey
  

.format can be .xml or .json or blank depending on the format you want the API to output. No format will result in json. At least one aggregate key must be specified.

Arguments

Arguments are specified on the URL usually after the API key and are separated by an &. You can use the following patterns for different types of arguments:

FormatURL Argument
String, Integer, or Floatkey=StringValue
Arraykey[]=StringValue1&key[]=StringValue2&key[]=StringValue3…
Hashmetadata[key]=2&metadata[key]=4

 

ArgumentDescriptionExample
keys[]=Array (Required)Array of keys to aggregate off of. See the above table to understand arrays in the URL
address_mode=StringForces returned location rather than relying on agency setting. Options are exact or polygon.
agency_only=BooleanWhether to filter and only include only the listings relevant to the agency id on the API key
box[key]=HashValueLongitude and latitude filters. Possible keys include min_latitude, min_longitude, max_latitude, and max_longitude. To learn how to specify hashes on the URL, see above this table.
building_id=StringEach listing includes a Building ID making it possible to find all apartments in a single apartment building. This argument allows you to filter by building_id building_id=2432424234345345
include_disabled=BooleanWhether to include disabled listings in the results
listing_ids[]=ArrayArray of listing ids. To learn how to specify arrays on the URL, see above this table.listing_ids[]=634748456753457& listing_ids[]=234535464576476
listing_types[]=StringArray of listing types to filter by
location[key]=HashValueLocation filters. Possible keys include postal, region, locality. To learn how to specify hashes, see above this table.location[postal]=06820
metadata[key]=HashValueSearch for specific curated data, such as number of beds, baths, etc. See the output sample below for possible keys. Replace any dashes (-) with underscores (_). Also refer to the matchers table to see how to use min and max values. Add multiple metadata values to specify more complex searches.To learn how to specify hashes, see above this table.metadata[beds]=2& metadata[baths]=1
non_import=BooleanOnly include listings that weren’t imported
property_type[]=ArrayListing type to filter by
purchase_types[]=ArrayArray of purchase types to filter by
total_images=IntegerFilter by total images
zoning_types=StringArray of zoning types to filter by

 

Matchers

The matchers below are ways of further refining how you want a field searched, allowing for more complex queries. The * can be replaced with the field, such as property_type_match or postal_match.

For Integers and Floats, you can either call the field name to do an exact match, or you can use the below to search lesser than or equal, greater than or equal, or range, such as min_beds=3.

MatcherDescription
*_match=String (Default eq)Match strings by: exact match (eq), partial match (like), or anything except the given value (ne)
*_match=String (Default in)Match arrays by: include the value (nin), include all the values (all), or include at least one (in)
*_match=String (Default eq)Match dates by: greater than (gt), greater than or equal (gte), less than (lt), less than or equal to (lte), or equals to (eq)
min_*=NumberMinimum value to match
max_*=NumberMaximum value to match

 

Possible Aggregate Keys

This is a list of the keys you can use to aggregate the data. You can specify more than one key. Refer to the table above for more info on how to specify arrays on the URL.

KeyCorresponding Value in Listings Output
cur_data.keyMost curated data keys can be used. For instance, cur_data.style, or cur_data.year_blt. Url cannot be used as a key.
uncur_data.keyMost uncurated data keys can be used. For instance uncur_data.appliances_included
agency_idagency_id
provider_idprovider_id
import_idimport_id
zoning_typeszoning_types
compound_typecompound_type
building_idbuilding_id
provider_idprovider_id
location.keyMost location data keys can be used. For instance, location.postal or location.address. coords cannot be used.

Sample Output

    <aggregated>
      <location.postal>
        <location.postal>06820</location.postal>
        <location.postal>06853</location.postal>
        <location.postal>06854</location.postal>
        <location.postal>06840</location.postal>
        <location.postal>06851</location.postal>
        <location.postal>06850</location.postal>
        <location.postal>06907</location.postal>
        <location.postal>06902</location.postal>
        <location.postal>06824</location.postal>
        <location.postal>06855</location.postal>
        <location.postal>06903</location.postal>
        <location.postal>06880</location.postal>
        <location.postal>60840</location.postal>
        <location.postal>06896</location.postal>
      </location.postal>
    </aggregated>