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

[{
  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',
  }
}]

[{

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:

[
{
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: ""
}
]

[

{

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:

[
{
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"
}
]

[

{

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.

[
{
superTypeId: "46",
superTypeName: "House",
subTypeId: "49",
subTypeName: "Terraced"
},
{
superTypeId: "47",
superTypeName: "Flat / Apartment",
subTypeId: "284",
subTypeName: "Penthouse Flat"
}
]

[

{

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:

[
{
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"
}
]

[

{

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, property detail requests, home report requests and for submitting new applicants to a mailing list.

The parameter ‘detailsRequested’ logs a detail request in BDP when this value is set to true.

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

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

{
	"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"
	}
}

{

"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

{
	"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
}

{

"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

{
	"propertyId":85682,
	"createdDate":"10 Sep 2017 12:39:24 +0100",
	"hrRequest":true,
	"message":"Home report please",
	"contactData":{
		"firstName":"Dave",
		"lastName":"Smith",
		"tel1":"0131 320 9777",
		"email":"test@bdphq.com"
	}
}

{

"propertyId":85682,

"createdDate":"10 Sep 2017 12:39:24 +0100",

"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.

{
	"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"
	}
}

{

"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 Stats

PUT /stats/

Sends a statistics report for a given property, this would be expected on a daily basis.

[{

"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"

}]

[{

"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"

}]

BDP API – Developer Documentation

BDP WebAPI Documentation1.0.4

BDP Rest API Basics

Authenticating a Request

Request Format

Base URLs

Request

Return

API Methods

Get Property

Get Props

Get Branches

Get Users

Get Property Types

Get SPC Districts

Webhook

Pulling Images from BDP

PUT Request (capturing leads)

PUT Stats

Related Articles

Complete property Placeholder list

Using the REST API to power your website