Last Updated: Sept 2021

BDP WebAPI Documentation

BDP Rest API Basics

The BDP Media restful API allows authenticated users to receive orders for new media and load media remotely.

BDP restful APIs follow restful principles.

Authenticating a Request

BDP APIs use a simplified version of the Amazon S3 method for authentication. Authentication is provided by placing an ‘Authorization’ header in the request containing an API key and signature generated from a shared secret.

Authorization = “BDWS” + ” ” + BDWSAccessKeyId + “:” + Signature;

Signature = Base64( HMAC-SHA1( YourSecretAccessKeyID, UTF-8-Encoding-Of( StringToSign ) ) );

StringToSign = HTTP-Verb + “\n” +

Content-MD5 + “\n” +

Content-Type + “\n” +

Date + “\n”

;

Full details of this authentication technique can be found at:

 

http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html

Request Format

Base URLs

Live environment:   https://api.bdphq.com/restapi/

UAT environment:   https://uat.bdphq.com/restapi/

Training environment:   https://training.bdphq.com/restapi/

Request

====================================================================

GET /property/id HTTP/1.1

Host: bdphq.com

accId : 123456

Date: Mon, 26 Mar 2007 19:37:58 +0000

Authorization: ESPCWS AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg=

In the above example, all available property data would be returned for property with a given id for account id. 123456.

WARNING: Depending on the firm the result might have more or less data.

Return

 

API Methods

Get Property

GET /property/id   HTTP/1.1

Returns the full set of json for a property with a given id.

Get Props

GET /props   HTTP/1.1

Additional parameters can be included to control search results. These can be found at: http://i.bdphq.com/controlling-output-using-the-url/

Returns json results for properties. Each property result is a shortened ‘summary’ json object. Full property details including all images must be pulled individually using GET /property/id.

Return

 

Get Branches

GET /branches   HTTP/1.1

Returns a json object for each branch. The follow example shows what details are included:

Get Users

GET /users   HTTP/1.1

Returns all users for a given firm. Included data for each user:

Get Property Types

GET /propertytypes   HTTP/1.1

Returns all property types. We recommend using only the superTypeId (i.e. House, Flat, etc.) to limit the amount of search options e.g. when populating a drop-down.

Get SPC Districts

GET /spcdistricts   HTTP/1.1

Returns all SPC districts. Fields include CRAD id, country, region, area and district. Snippet of returned JSON data:

 

Webhook

The suggested method for populating a website with content from BDP is to pull the data on page load, rather than store it locally. If storing data locally, it is recommended that a full GET of property data is pulled at least once a day to avoid data inconsistencies if webhook calls are missed.

A Webhook Url can be stored in the configuration section of BDP. When a new order is initiated from BDP, a simple get request is made to the Webhook Url containing an id parameter. A typical rest client would listen for a notification, when received, it will access the API and request data for the given id.

A typical Webhook Notification: http://yourdomain.com/notification.php?id=123456

This can be used to prompt a get request for updated data on a given property.

Pulling Images from BDP

The URL for each image in BDP appears in the API at full size. Images can be resized by adding
the following parameters to the query string of the image:

  •  W – setting the width (height scales automatically unless set)
  •  H – setting the height (width scales automatically unless set)
  •  MXD – setting a maximum dimension, an example might be setting an image inside a box
  •  Nogzip – stops the image from being sent gzipped – we recommend using gzipping to streamline delivery as much as possible.

PUT Request (capturing leads)

PUT /request/

This method is used for creating viewing requests, enquiries, home report requests and for submitting new applicants to a mailing list.

The parameter ‘actionTime’ sets the time for an appointment – used in the case of a viewing or valuation request.

The parameter ‘viewingRequested’ initiates a viewing in BDP when this value is set to true.

The parameter ‘hrRequest’ initiates a home report request in BDP when this value is set to true.

The parameter ‘sendOtherData’ ensures that the applicant is subscribed to the mailing list in BDP and can receive matching emails.

The parameter ‘enquiryRequest’ initiates a standard enquiry when set to true. This can then be manually converted into a viewing via the UI.

 

PUT /request/ – Example of a Property Mailing List Sign-Up request

PUT /request/ – Viewing Request

PUT /request/ – Home Report Request

PUT /request – Valuation Request

This will add the property to BDP with a blank status and create an unconfirmed calendar appointment at the time of creation.

PUT /request – Enquiry Request

This will add an enquiry which will appear in the Enquiries (web) section.