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:

Format URL Argument
String, Integer, or Float key=StringValue
Array key[]=StringValue1&key[]=StringValue2&key[]=StringValue3…
Hash metadata[key]=2&metadata[key]=4

 

Argument Description Example
keys[]=Array (Required) Array of keys to aggregate off of. See the above table to understand arrays in the URL
address_mode=String Forces returned location rather than relying on agency setting. Options are exact or polygon.
agency_only=Boolean Whether to filter and only include only the listings relevant to the agency id on the API key
box[key]=HashValue Longitude 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=String Each 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=Boolean Whether to include disabled listings in the results
listing_ids[]=Array Array of listing ids. To learn how to specify arrays on the URL, see above this table. listing_ids[]=634748456753457& listing_ids[]=234535464576476
listing_types[]=String Array of listing types to filter by
location[key]=HashValue Location filters. Possible keys include postal, region, locality. To learn how to specify hashes, see above this table. location[postal]=06820
metadata[key]=HashValue Search 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=Boolean Only include listings that weren’t imported
property_type[]=Array Listing type to filter by
purchase_types[]=Array Array of purchase types to filter by
total_images=Integer Filter by total images
zoning_types=String Array 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.

Matcher Description
*_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_*=Number Minimum value to match
max_*=Number Maximum 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.

Key Corresponding Value in Listings Output
cur_data.key Most 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.key Most uncurated data keys can be used. For instance uncur_data.appliances_included
agency_id agency_id
provider_id provider_id
import_id import_id
zoning_types zoning_types
compound_type compound_type
building_id building_id
provider_id provider_id
location.key Most 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>