Weblisting - Show your Listings on your Website

Note: The following instructions explain how to display listings on a website. The integration requires development knowledge. The codes below are just examples and need to be adapted to your Website by a knowledgeable developer.

What is our Weblisting service?

Using our WebListings service you will be able grab any Listing object information found in Propertybase, such as Listing fields or media (e.g. images, documents, videos [if linked]) and display it on the Website.

Please find the technical documentation below for your Web Developer to use to sync your information to your Website. Your developer can add a search functionality, map search and this can all be designed styled as you like.

WebListings are a means of getting the live data to your Website using the Propertybase API. Where whenever you modify any data in Propertybase, the change is instant on the website. Meaning you don't have to track changes in two places.

Here is a summary of how WebListings work;

    1. You have a Website where you want to have your listings displayed to the public.
    2. You fill Propertybase with your Listings and necessary data.
    3. You activate Webservices in Propertybase and provide your Web Developer with our Technical Documentation.
    4. Your Web Developer can then grab the data from Propertybase and display it however you specify. It can have the look and feel of your website or any styling you wish.

Set up Notes

    • Getting Started - you first need to activate your Webservices for your Propertybase ORG.                                           
    • Sample Website
      Want to see how it can look? Visit our "BayAreaBrokers" demo site! You can check out your webservice configuration just by clicking "connect" and see your Propertybase listings!

 

Technical Documentation 
 
The weblisting webservice allows you to query Propertybase for the stored Listings to display that data on your webpage. Each query is a http request to a specific endpoint and returns an XML document as a result.
 
When you send a query to Propertybase, you can specify the following;
    • The Fields to retrieve in each returned item
    • How many items to retrieve (items per result page and number of page)
    • The order to retrieve the results
    • Whether you want to include links to images and other media files
    • And of course the filters that shall be applied to the data in Propertybase as simple http get or post parameters
 
NB: You can receive a maximum of 1000 inventories per search request. If more items are found, the result is truncated. This limit cannot be enhanced, even not if paging is used. If you want to retrieve larger sets of data, you can use the Salesforce Web Services API.
Parameters
The following parameters will be accepted by the WebListing service : debugmode iv>
Parameter  m* Value(s) Example(s) Default
(if not specified)
Annotations
token  * String token=24230928347owsadf   will be set by support on initial setup. If required you can change that by editing the Setting 'webserviceListingsQuery_token'
page   Integerpage number page=2 0 First page is 0
itemsperpage   Integeritems per result page itemsperpage=10 20 default value can be configured in Setting 'webserviceWeblisting_pageLimit'. 200 is maximum.
fields  * StringPropertybase API field names, semicolon separated fields=Id;Name;pba__ListingPrice_pb__c;pba__Bedrooms_pb__c; pba__Description_pb__c   list of all fields which should be included per item in the XML result (please use the API field name, not the field label)
orderby   StringPropertybase API field name + ASC or DESC, semicolon seperated sort=pba__ListingPrice_pb__c;ASC CreatedDate;DESC  
recordtypes   StringPropertybase Inventory Record Types, semicolon separated recordtypes=Sale;Rent   limits Record Types to be returned. Use the Developer name of the Record Type.
getimages   Boolean getimages=true true true: results contain links to images
getvideos   Boolean getvideos=true false true: results contain links to videos
getdocuments   Boolean getdocuments=true false true: results contain links to documents
debugmode   Boolean debugmode=true false if set to true, the result XML contains a debug section with some more debug information
Fieldname__c(any API fieldname)  * Stringeach field can be filtered according to the filter criteria specified in this value pba__ListingType_pb__c=Apartment
pba__ListingPrice_pb__c=[800000;1000000]
pba__Bedrooms_pb__c=[4;]
  at least one filter has to be specifiedsee table below
 format   Stringcan be "xml" or "json"  format=json  xml  if set to json, the system returns the results in JSON format instead of XMLthis parameter is available since Propertybase version 3.1.2.0
 language    String language=en
language=de
 default language of the API user  The language used to display picklist values that have associated translations in Propertybase. This value overrides the language of the API user. Possible values for this attribute include any language keys for languages supported by the Salesforce platform, for example, "en", "en-US" or "de".this parameter is available since Propertybase version 3.1.2.0
*: mandatory
 
 
 
 
 
 
 
Filters Syntax
Depending on the type of the field, you can specify different criteria to limit the results.
 
     Syntax  Example  Description
 All Types        
  Is Empty Fieldname__c=  pba__ListingPrice_pb__c= result contains only items, which do not have a price set
 String          
  Exact Match Fieldname__c=Value Name=abc selects only items with an exact name of "abc"
  Starts With Fieldname__c=Value% Name=abc% selects items with a name that starts with abc
  Contains Fieldname__c=%Value% Name=%abc% selects items with a name that contains abc
  In Fieldname__c=IN(Value1;Value2;Value3) Name=IN(abc;def;ghi) selects items with name exactly abc, def or ghi
 Boolean        
   Exact Match Fieldname__c=true|false
Fieldname__c=true
Fieldname__c=false
 
 Number, Date & DateTime        
  Exact Match Fieldname__c=Value pba__Bedrooms_pb__c=2  
  Range Fieldname__c=[LowerBorder;UpperBorder] pba__ListingPrice_pb__c=[500000;600000]
pba__Bedrooms_pb__c=[4;]
MonthlyRent__c=[;1500]
Any price between 500K & 600K
At least 4 bedrooms
Maximum rent of $1.500
Syntax for Date: 
 
YYYY-MM-DD
Example: 2009-08-08
 
Syntax for Datetime:

YYYY-MM-DD HH:mm:ss
Example: 2009-08-08 16:08:00
CreatedDate=[;2011-12-24 17:00:00]  (any item that was created before christmas eve )
In the quere it looks like this &LastModifiedDate=[;2011-12-24%2017:00:00]

Date and Datetime are always calculated in the local timezone of your weblisting user. (Setup> Build> Develop> Sites - click on the site label > Button "Public Access Settings"> Button "View Users" -> make sure this fits to the ORGs timezone (which can be found here: Setup> Administer> Company Profile> Company Information).
 
Note:Make sure to URL encode your values! e.g. if your value contains an ampersand (&), this would make your request invalid, if you don't encode the &.
Also make sure, that if you do a "starts with" or "contains" search, that your % is encoded as %25.Example: If you're searching for "name contains London", your search should contain the following filter &name=%25London%25All server script languages have built-in support for URL encoding. Check out this Wikipedia article if you are not sure how to encode your values: http://en.wikipedia.org/wiki/Percent-encoding

XML result

Error

<result>
        <page>0</page>
        <listingsPerPage>20</listingsPerPage>

        <numberOfListings>0</numberOfListings>

        <fatalError>true</fatalError>
        <errorMessages>
        <message>message text</message>
        ...
        </errorMessages>

        <!-- debug messages will only be included if debugmode is set to true-->
        <debugMessages>
        <message>message text</message>
        ...
        </debugMessages>
        </result>
    

 

Success

<result>
        <page>0</page>
        <listingsPerPage>20</listingsPerPage>
        <numberOfListings>6</numberOfListings>

        <!-- debug messages will only be included if debugmode is set to true-->
        <debugMessages>
        <message>message text</message>
        ...
        </debugMessages>
        <listings>
        <listing>
        <data>
        <id>a0900000762hj83</id>
        <name>Paradise in Poipu Kauai</name>
        <pba__ListingPrice_pb__c>1795000.0</pba__ListingPrice_pb__c>
        ...
        </data>
        <media>
        <images>
        <image>
        <title>Ocean View</title>
        <filename>Hawaii3.jpeg</filename>
        <tags>Exterior</tags>
        <mimetype>image/jpeg</mimetype>
        <url>https://s3.amazonaws.com/propertybase-clients/.../Hawaii3.jpeg</url>
        <baseurl>https://s3.amazonaws.com/propertybase-clients/...</baseurl>
        </image>
        <image>
        ...
        </image>

        ...

        </images>
        <videos>
        <video>
        <title>Flight over mansion</title>
        <tags></tags>
        <mimetype>video/mpeg</mimetype>
        <external>true</external>  <!-- true if video is stored somewhere on the net. false if video is on s3 like the images -->
        <url>http://youtube.com/...</url>
        </video>
        ...
        </videos>
        <documents>
        <!-- similar to videos -->
        </documents>
        </media>
        </listing>
        ...
        </listings>
        </result>
    

 

 

JSON result

 
 
{
        "page" : 0,
        "listingsPerPage" : 20,
        "numberOfListings" : 90,
        "fatalError" : false,
        "errorMessages" : [ ],
        "debugMessages" : [ "querying fields name,pba__Bedrooms_pb__c", "no filter on recordtypes", "order by: CreatedDate DESC", "getImages: true", "getVideos: false", "getDocuments: false", "using default for itemsPerPage: 20", "using default for page: 0" ],
        "listings" : [ {
        "data" : {
        "name" : "Paradise in Poipu Kauai",
        "pba__Bedrooms_pb__c" : 4.0
    },
      "images" : [ {
        "title" : null,
        "filename" : "original20.jpeg",
        "tags" : null,
        "mimetype" : "image/jpeg",
        "url" : "https://.../4f4b7c5a2df53/original20.jpeg",
        "baseurl" : "https://.../4f4b7c5a2df53"
    }, {
    "title" : null,
    "filename" : "original1.jpeg",
    "tags" : null,
    "mimetype" : "image/jpeg",
    "url" : "https://.../4f4b7c6d776cf/original1.jpeg",
    "baseurl" : "https://.../4f4b7c6d776cf"
      },
                ...],
      "videos" : [ ],
            "documents" : [ ]
        }
    },
In the examples below, just replace yourendpoint by the endpoint in your Org. Got to Setup > Develop > Sites > Webservices > Custom URLS. Use the URL and yourtoken by your weblisting token:
 
Example Requests

Before you start you need to find your endpoint and your token here - items  6 & 7

Sample Request #1  - Minimal request:

Fields: Name, Price
Filter: Any Price (0 - )
Debug:  enabled

Enter this query into your browser (values not url encoded):
https://yourendpoint/pba__WebserviceListingsQuery?token=yourtoken&fields=name;pba__ListingPrice_pb__c&pba__ListingPrice_pb__c=[0;]&debugmode=true

 

Your browser will encode any unusual characters and it will display as per the below:
https://yourendpoint/pba__WebserviceListingsQuery?token=yourtoken&fields=name;pba__ListingPrice_pb__c&pba__ListingPrice_pb__c=%5B0%3B%5D&debugmode=true
 
Sample Request #2 - Typical request:

Fields:  Name, Price, Description, Beds, Baths, Size
Filters: Price between 1,000,000 and 1,500,000
         Size greater than 2,500 sqft
Order:   lowest price first
Debug:   not enabled

Enter this query into your browser (values not url encoded):
https://yourendpoint/pba__WebserviceListingsQuery?token=yourtoken&fields=name;pba__ListingPrice_pb__c;pba__description_pb__c;pba__Bedrooms_pb__c;pba__FullBathrooms_pb__c;pba__totalarea_pb__c&pba__ListingPrice_pb__c=[1000000;1500000]&pba__totalarea_pb__c=[2500;]&orderby=pba__ListingPrice_pb__c;ASC&getdocuments=true&getvideos=true&itemsperpage=25&page=1

 

Your browser will encode any unusual characters and it will display as per the below:
https://yourendpoint/pba__WebserviceListingsQuery?token=yourtoken&fields=name;pba__ListingPrice_pb__c;pba__description_pb__c;pba__Bedrooms_pb__c;pba__FullBathrooms_pb__c;pba__totalarea_pb__c&pba__ListingPrice_pb__c=%5B1000000%3B1500000%5D&pba__totalarea_pb__c=%5B2500%3B%5D&orderby=pba__ListingPrice_pb__c;ASC&getdocuments=true&getvideos=true&itemsperpage=25&page=1
 
Other Optional Parameters that were included in this example:
 
&getdocuments=true    Returns documents (this is not default)
&getvideos=true   Returns videos (this is not default)
&itemsperpage=25   Returns 25 items per result page 
&page=1   will return result 26-50 (note &page=0 will return the first page)
 
FAQs
1) How do I Add New Fields to the returned listings

The parameter called Fields enables you to request any field from the listing record.

All you need to do is add the field API Name for the Fields you require in the Fields parameter in the query call.

To find out more about how to find the API Names for the required fields please review this help file. API Field Names Help File

2)I get error "field cannot be accessed: myfieldname__c"

The website user does not have permission to access the field . You will need to give permissions to access the field "myfieldname__c".

This will be the error message  if you have not given access.

<errorMessages>

        <message>field cannot be accessed: myfieldname__c</message> 

</errorMessages>

For more information please refer to our Help file on Webservices , specifically steps 4 and 5. 

3) Is there a way to exclude a property from the webservices output xml?

Indeed this is possible. You just need to add an field in Propertybase. e.g. Checkbox "List on Website". Then you adjust your web listing query, so that it only requests Listings that have a tick in the checkbox. 

4) My Price Filter ranges do not work properly

Please double-check if you have entered the filter correctly. You require both a filter from and a filter to,

e.g. to filter listing prices from $0 to $100,000 the filter should be as below

pba__listingprice_pb__c=[0;100000]

If you want to filter all lisitngs with a price greater than $100,000 the filter should be as below

pba__ListingPrice_pb__c=[100000;]

5) Its there possibly anyway to add commas to the money values in the xml output.

We return decimal numbers not formatted strings. -> So every client can adjust it it to his purpose and for instance country. 

Depending on your website technology you can format them as you need. e.G.: http://www.php.net/manual/en/function.number-format.php

6) I can not read the listings in my web server.

On cPanel the API doesn’t work unless allow_url_fopen is ON.

7) Do you have a demo website?

Click here to check it out!

8) Do you have code examples for my developer

We have a full working example website repository and every developer should be able to introduce it into your website! You can check out your webservice configuration just by clicking "connect" and see your Propertybase listings!

 

Powered by Zendesk