Version 1.0.4 – May 2017
BDP WebAPI Documentation1.0.4
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.
Return
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
[{ pId : 123456, orgId : 12345, externalId : 8047, address : { houseNo : 2, streetName : 'Some Street', addrL2 : 'some district', addrL3 : '', town : 'Edinburgh', postcode : 'EH1 1EE', lat : 123456232, lng : 421345161, dispAddress : '2 Some Street, Edinburgh', paperAddress : '2 Some Street' } propertyTypeId : 2, propertyTypeLabel : 'Detached Bungalow', transType : 'Resale', offerTypeId : 1, offerTypeLabel : 'Offers Over', sellingStatusId : '5', sellingStatusLabel : 'Under Offer', askingPrice : 430000, bedRooms : 4, receptionRooms : 3, bathRooms : 2, garage : true, garden : false, summary : 'Some short description of the property', fullDesc : 'Some long description of the property. <br> tags are accepted', brochureDesc : 'Some long description for the brochure', showroomDesc : 'Showroom Description', viewingDesc : 'Viewing description', rooms : [ { name : 'Dining Room', width : 4.34, length : 5.23, fullDesc : 'Some description of this room' }, { name : 'Living Room', width : 4.34, length : 5.23, fullDesc : 'Some description of this room' } ], epcRating : 'G', crad : { country : 'Scotland', region : 'Lothian', area : 'Edinburgh West', distroict : 'Barnton' } linkedMedia : { images : [ { name : 'Some image name', lowResUrl : 'http://somepath', highResUrl : 'http://somepath', gZipped : true }, { name : 'Some image name', lowResUrl : 'http://somepath', highResUrl : 'http://somepath', gZipped : true } ], brochure : 'http://some url', floorPlan : 'http://some url', movie : 'http://some url', } }] |
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.
Get Branches
GET /branches HTTP/1.1
Returns a json object for each branch. The follow example shows what details are included:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
[ { branch_id: "122", branchName: "Aberdeen ", houseNo: "12", streetName: "Main Street", town: "Aberdeen", addrL3: "", postcode: "AB10 2HR", tel1: "01224 553 000", contactEmail: "maildesk@firm.com", espcRef: "1000001", gspcRef: "", fspcRef: "", rMoveRef: "", atmRef: "", dpgRef: "", s1Ref: "", lWebRef: "", partnerEmail: "", branchWebsite: "", partnerName: "" }, { branch_id: "999", branchName: "Inverurie", houseNo: "6", streetName: "Long Place", town: "Inverurie", addrL3: "", postcode: "AB51 6TN", tel1: "01467 887 601", contactEmail: "maildesk@firm.com", espcRef: "1000001", gspcRef: "", fspcRef: "", rMoveRef: "", atmRef: "", dpgRef: "", s1Ref: "", lWebRef: "", partnerEmail: "", branchWebsite: "", partnerName: "" } ] |
Get Users
GET /users HTTP/1.1
Returns all users for a given firm. Included data for each user:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 |
[ { user_id: "101111", userNme: "test@bdphq.com", password: "password", firstName: "Joe", lastName: "Brown", userStatus_id: "2", workTel1: "", workMob1: "", workRole: "", accountAdmin: "1", branchId: "212", techAdmin: "0", propertyEdit: "0", valuer: "0", viewingAgent: "0", negotiator: "0", conveyancer: "0", feeEarner: "0", propertyAdvisor: "0", solicitor: "0", clientCare: "0", propertyAdmin: "0", inCal: "1", firmIpHold: "0", ipHold: "", calEmail: "", calColour: "", proPic: null, customInitials: "", assignedAccess: "0" }, { user_id: "11433", userNme: "user@bdphq.com", password: "password", firstName: "Dave", lastName: "Field", userStatus_id: "2", workTel1: "", workMob1: "", workRole: "", accountAdmin: "1", branchId: "212", techAdmin: "0", propertyEdit: "1", valuer: "0", viewingAgent: "0", negotiator: "1", conveyancer: "0", feeEarner: "0", propertyAdvisor: "0", solicitor: "0", clientCare: "0", propertyAdmin: "0", inCal: "1", firmIpHold: "0", ipHold: "", calEmail: "", calColour: "", proPic: null, customInitials: "", assignedAccess: "0" } ] |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
[ { superTypeId: "46", superTypeName: "House", subTypeId: "49", subTypeName: "Terraced" }, { superTypeId: "47", superTypeName: "Flat / Apartment", subTypeId: "284", subTypeName: "Penthouse Flat" } ] |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
[ { crad_id: "858", country: "Scotland", region: "Argyll & The Isles", area: "Argyll & The Isles", district: "Argyll & The Isles" }, { crad_id: "859", country: "Scotland", region: "Ayrshire", area: "Arran Bute & Cumbrae", district: "Arran Bute & Cumbrae" }, { crad_id: "860", country: "Scotland", region: "Ayrshire", area: "East Ayrshire", district: "East Ayrshire" }, { crad_id: "861", country: "Scotland", region: "Ayrshire", area: "North Ayrshire", district: "North Ayrshire" }, { crad_id: "862", country: "Scotland", region: "Ayrshire", area: "South Ayrshire", district: "South Ayrshire" }, { crad_id: "863", country: "Scotland", region: "Central Scotland", area: "Greater Falkirk", district: "Airth" } ] |
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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
{ "propertyId":0, "createdDate":"2017-09-13T09:55:38", "actionTime":"2017-09-13T09:55:38", "viewingRequested":"false", "hrRequest":false, "sendOtherData":"true", "message":"Mailing List request.", "contactData":{ "title":"Mr", "firstName":"James", "lastName":"Bond", "salutation":"Mr. Bond", "tel1":"0208 987 5522", "mobile":"07856 752232", "houseNo":"3", "streetName":"High Road", "addrL2":"Chelsea", "town":"London", "postcode":"SW10 0AJ", "email":"test@bdphq.com" }, "buyingData":{ "transType":"sale", "minPrice":0.0, "maxPrice":200000.0, "bedRoomsMin":1, "bedRoomsMax":2, "districts":[ "Edinburgh City Centre", "Edinburgh East", "Edinburgh North", "Edinburgh North West", "Edinburgh South", "Edinburgh South West", "Edinburgh West" ], "propertyTypes":[ "Flat" ], "keywords":"2nd floor" } } |
PUT /request/ – Viewing Request
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
{ "propertyId":89657, "createdDate":"2017-02-14T12:20:59", "viewingRequested":"true", "hrRequest":false, "sendOtherData":"true", "message":"Viewing Requested - Preferred time: Afternoon", "contactData":{ "title":"Ms", "firstName":"Sharon", "lastName":"Smith", "salutation":"", "tel1":"07428 665083", "mobile":"", "houseNo":"22", "streetName":"Cairns Place", "addrL2":"", "town":"Aberdeen", "postcode":"AB16 7AP", "email":"test@bdphq.com" }, "buyingData":null } |
PUT /request/ – Home Report Request
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "propertyId":85682, "createdDate":"2017-09-13T09:55:38", "hrRequest":true, "message":"Home report please", "contactData":{ "firstName":"Dave", "lastName":"Smith", "tel1":"0131 320 9777", "email":"test@bdphq.com" } } |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
{ "message": "I would like a valuation please", "createdDate": "2017-11-22T12:20:59", "actionTime": "2017-11-22T12:20:59", "valuationRequested": true, "propertyData":{ "houseNo":"79", "streetName":"Lothian Road", "town":"Edinburgh", "postcode":"EH39AW" }, "contactData": { "firstName": "John", "lastName": "Smith", "tel1": "0131 865 1111", "email": "jsmith@email.com" } } |
PUT /request – Enquiry Request
This will add an enquiry which will appear in the Enquiries (web) section.
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "propertyId": 121937, "createdDate": "2017-09-13T09:55:38", "enquiryRequest": true, "message": "I would like to request a viewing, please.", "contactData": { "firstName": "Mary", "lastName": "Poppins", "tel1": "0123456798", "email": "mary.poppins@example.com" } } |
PUT Stats
PUT /stats/
Sends a statistics report for a given property, this would be expected on a daily basis.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
[{ "propertyId" : "12347", "createdDate" : "26 Mar 2007 19:37:58 +0000", "statsDate" : "26 Mar 2007 00:00:00 +0000", "summaryViews" : "50", //views in the search results on 26 Mar 2007 "detailViews" : "15", //views of the property detail page on 26 Mar 2007 "brochureDownloads" : "5", "floorplanDownloads" : "3", "movieViews" : "6" }, { "propertyId" : "12345", "createdDate" : "26 Mar 2007 19:37:58 +0000", "statsDate" : "26 Mar 2007 00:00:00 +0000", "summaryViews" : "50", //views in the search results on 26 Mar 2007 "detailViews" : "15", //views of the property detail page on 26 Mar 2007 "brochureDownloads" : "5", "floorplanDownloads" : "3", "movieViews" : "6" }] |
Complete property Placeholder list