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. Each call to the API returns a maximum of 50 listings. If you need more listings, refer to the offset argument below.

Basic Use

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

[.format] can be .xml or .json depending on the format you want the API to output.

cURL

curl -X GET -d "api_key=xxxxxxxxxxx" http://api.placester.com/api/v2.1/listings

PHP

$url = 'http://api.placester.com/api/v2.1/listings?api_key=' . $my_api_key_here;

$curlcall = curl_init();
curl_setopt($curlcall, CURLOPT_URL, $url);
curl_setopt($curlcall, CURLOPT_RETURNTRANSFER, true);

$curlout = curl_exec($curlcall);

PHP – Filter listings

$url = 'https://api.placester.com/api/v2.1/listings/?api_key=' . $my_api_key_here;
$url .= "&metadata[beds]=4&metadata[baths]=2";

$curlcall = curl_init();
curl_setopt($curlcall, CURLOPT_URL, $url);
curl_setopt($curlcall, CURLOPT_RETURNTRANSFER, true);
$curlout = curl_exec($curlcall);

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
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=ObjectId 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
limit=Integer Limits how many listings are returned, value is capped at 50 limit=20
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
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. 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
offset=Integer How many listings to skip, used for pagination
property_types[]=Array Array of listing types to filter by. To learn how to specify arrays on the URL, see above this table.
purchase_types[]=Array Array of purchase types.To learn how to specify arrays on the URL, see above this table.
sort_by=String Field to sort by, can be any field returned from the API under cur_data, uncur_data, and location
sort_type=String Sort by asc or desc order
total_images=Integer Filter by total images
zoning_types[]=Array Array of zoning types to filter by.To learn how to specify arrays on the URL, see above this table.

 

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

 
For examples of these matchers in action, see this article.

Returns

Key Description
total How many listings match your criteria, cached for 1 hour
offset Offset that was passed with the request, or 0 if none was specified
limit The limit passed with the rquest, or 50 if none was specified
count How many listings are in the listings array returned
listings[] Array of all the listings found
listings[]id Listing ID
listings[]cur_data Curated data returned for the listing
listings[]uncur_data Uncurated data for the listing
listings[]location Where the listing is located
listings[]location[address] Address, eg “1234 Fake Street”
listings[]location[locality] Locality, eg “Boston”
listings[]location[region] State, eg “MA”
listings[]location[postal] Postal Code, eg “02145”
listings[]location[neighborhood] Neighborhood, eg “Parkwood Heights”
listings[]location[country] 2-digit country code, eg “US”
listings[]location[coords][latitude] Latitude location of the address
listings[]location[coords][longitude] Longitude location of the address
listings[]contact[] How potential leads can contact the agent
listings[]contact[email] Placester tracking email, will be forwarded to the agencies email address
listings[]contact[phone] The agencies phone number
listings[]tracker_url Tracking URL to reference the listing, must be used for Placester to provide traffic data on the listing
rets RETS information when available for the listing

 

Sample Output

  <result>
    <total>1</total>
    <offset>0</offset>
    <limit>50</limit>
    <count>1</count>
    <listings>
      <listing>
        <id>51a8f157960df91c06000001</id>
        <cur-data>
          <baths>1</baths>
          <beds>2</beds>
          <cble-rdy>true</cble-rdy>
          <desc>
            LIVES LARGER THAN LISTING READS. CHARMING & BEAUTIFULLY RENOVATED HOME. HIGH CEILINGS, SPACIOUS SUN-FILLED ROOMS & HARDWOOD FLOORS. BASEMENT PLAYROOM 16X12 (NOT INCLUDED IN SQUARE FOOTAGE). MATURE PLANTINGS & AN OPEN, MANICURED LAWN ROUND OUT THIS LOVELY DARIEN HOME! ONE MONTHS RENT & TWO MONTHS SECURITY DEPOSIT DUE AT SIGNING OF LEASE. TENANT RESPONSIBLE FOR CREDIT CHECK, UTILITIES & LAWN MAINTENANCE. AVAILABLE AUGUST 1, 2013.
          </desc>
          <half-baths>0</half-baths>
          <price>3500.0</price>
          <sqft>1345.0</sqft>
          <style>English Cottage</style>
          <year-blt>1929</year-blt>
          <url>
            http://pinkponyhats.us/?property=51a8f157960df91c06000001
          </url>
        </cur-data>
        <uncur-data>
          <additional-rooms>Playroom</additional-rooms>
          <appliances-included>
          Cook Top, Dishwasher, Disposal, Dryer, Refrigerator, Washer
          </appliances-included>
          <attic-description>Pulldown Stairs</attic-description>
          <elementary-school>Holmes</elementary-school>
          <exterior-features>Fence, Garden Area, Gas Grill, Outbuilding</exterior-features>
          <exterior-siding>Vinyl Siding</exterior-siding>
          <fireplaces>1</fireplaces>
          <flooring>Wood, Tile, Carpeted</flooring>
          <fuel-type>Natural Gas</fuel-type>
          <heat-type>Radiator, Baseboard</heat-type>
          <interior-features>Wainscoting,Whirlpool</interior-features>
          <middle-school>MIDDLESX</middle-school>
          <senior-high-school>Darien</senior-high-school>
          <sewage>Public Sewer Connected</sewage>
          <water-source>Public Water Connected</water-source>
          <year-renovated>1998</year-renovated>
        </uncur-data>
        <agency-id>505b64830941636a2d000020</agency-id>
        <provider-id>505b4453d23a543cd80002bc</provider-id>
        <import-id>505b647cd23a543d3500033f</import-id>
        <zoning-types>
          <zoning-type>residential</zoning-type>
        </zoning-types>
        <purchase-types>
          <purchase-type>rental</purchase-type>
        </purchase-types>
        <listing-types/>
        <compound-type>res_rental</compound-type>
        <building-id>51a8f159960df91c06000003</building-id>
        <rets>
          <aid>LAWTONC</aid>
          <oid>KLLY01</oid>
          <mls-id>18228</mls-id>
          <oname>Kelly Associates Real Estate</oname>
          <aname>Lawton Cathy</aname>
        </rets>
        <location>
          <neighborhood nil="true"/>
          <locality>Darien</locality>
          <region>CT</region>
          <postal>06820</postal>
          <unit nil="true"/>
          <country>US</country>
          <county>Fairfield</county>
          <address>68 Middlesex Road</address>
          <coords>
            <coord>41.077227</coord>
            <coord>-73.50827179999999</coord>
          </coords>
        </location>
        <contact>
          <email>
            inq-10oa5boya3tn1epvi001-105z0q06qp18raw29010@placester.net
          </email>
        </contact>
        <tracker-url>
          https://placester.com/listing/lead/505b64830941636a2d000020/51a8f157960df91c06000001
        </tracker-url>
        <images>
          <image>
            <id>51a8f1ec960df91c0600001b</id>
            <url>
            http://d126fxm3orgy3k.cloudfront.net/images/51a8f157960df91c06000001/51a8f1ec960df91c0600001b.jpeg?pid=505b64830941636a2d000020&kid=4f9eeff4d23a544121000257
            </url>
            <order>1</order>
          </image>
        </images>
      </listing>
    </listings>
  </result>