This reference documents version 2 of the Placester RESTful API. “People” does not exist in the v2.1 section.

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

Basic Use


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

cURL

curl -X GET -d "api_key=xxxxxxxx" http://api.placester.com/api/v2/people

PHP

$url = 'https://api.placester.com/api/v2/people';
$url .= '?api_key=' . $my_api_key_here;
$url .= '&metadata[name]=matt'; //filtered down by people named matt

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

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

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
relation=Integer Filters by relation. Possible relations are 0, 1, or 2 which mean Custom, Client, or Lead respectively
cust_relation=String Filters by relation text
metadata[key]=HashValue Key/value to search on for metadata
limit=Integer Limits how many listings are returned, value is capped at 50 limit=20
offset=Integer How many listings to skip, used for pagination
sort_by=String Field to sort by, can be any field returned from the API, for uncurated fields use _uncur_data. <key>_ for curated use _cur_data.<key>_
sort_type=String Sort by asc or desc order

 

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

 

Returns

Key Description
total How many people 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 request, or 50 if none was specified
count How many people are in the listings array returned
people[] Array of all the people found
people[]id Person ID
people[]cur_data Curated data returned for the person
people[]cur_data[]name Person’s name
people[]cur_data[]email Person’s email
people[]uncur_data Uncurated data for the listing
people[]relation Relationship of the person. 0 for custom, 1 for client, 2 for lead.

 

Sample Output

{
"total": 8,
"offset": 0,
"limit": 50,
"count": 8,
"people": [
{
"id": "51e5a2e41cdabc7a7d000010",
"cur_data": {
"name": "Matthew Williams",
"email": "placesteruser@domain.com"
},
"uncur_data": {},
"relation": 2,
"updated_at": "2013-07-25 20:03:54 UTC"
},
{
"id": "520bc2dd7293b45bfb000002",
"cur_data": {
"name": "asdad",
"email": "placesteruser@domain.com"
},
"uncur_data": {},
"relation": 2,
"updated_at": "2013-08-14 17:48:13 UTC"
},
{
"id": "520bc3697293b45cd5000018",
"cur_data": {
"name": "Matt",
"email": "placesteruser@domain.com"
},
"uncur_data": {},
"relation": 2,
"updated_at": "2013-08-14 17:50:33 UTC"
},
{
"id": "526057fc7293b47cff000003",
"cur_data": {
"name": "matt",
"email": "placesteruser@domain.com"
},
"uncur_data": {},
"relation": 2,
"updated_at": "2013-10-17 21:34:52 UTC"
},
{
"id": "526058031cdabc122c000006",
"cur_data": {
"name": "matt",
"email": "placesteruser@domain.com"
},
"uncur_data": {},
"relation": 2,
"updated_at": "2013-10-17 21:34:59 UTC"
},
{
"id": "52605ac31cdabc1fd2000001",
"cur_data": {
"name": "matt",
"email": "placesteruser@domain.com"
},
"uncur_data": {},
"relation": 2,
"updated_at": "2013-10-17 21:46:43 UTC"
},
{
"id": "52605b026b03652403000001",
"cur_data": {
"name": "matt",
"email": "placesteruser@domain.com"
},
"uncur_data": {},
"relation": 2,
"updated_at": "2013-10-17 21:47:46 UTC"
},
{
"id": "52605b301cdabc1cca000005",
"cur_data": {
"name": "matt",
"email": "placesteruser@domain.com"
},
"uncur_data": {},
"relation": 2,
"updated_at": "2013-10-17 21:48:32 UTC"
}
]
}