Accessing Product Data via the API

For 3rd party developers, BrightDoor Central offers a robust set of API methods for accessing content of various types (contacts, products, etc). One of the most common integrations involves the retrieval of BrightDoor Central product information for use in web sites and apps.

Getting Started
Prior to embarqing on establishing your service to fetch product data, please ensure you have the following:

• A valid BrightDoor Central web service username and password (usually provided by your client or BrightDoor Account Manager)
• “Client” and “Center” ID values (usually both set to “1″ by default, but confirm with the designated BrightDoor Account Manager)
• A checklist of the product types, statuses, attributes and media types/sizes you’ll need. Our API methods require you submit specific product types, status and attribute ID values against the method to tune the requested dataset. Please review all requirements with your client and BrightDoor Account Manager to plan out the list of IDs you’ll need.
• A plan for scheduled data sync with BrightDoor Central. We do not allow live, real-time fetching from our API as (a) it will not meet your web site performance requirements and (b) introduces heavier loads on our servers. You will need to create a CRON or other scheduled job service to fetch a new local cache of BrightDoor Central product data on a 12 to 24 hour schedule.

Currently, we advise use of the GetAllProductDetails method for product data queries. This method can be found at (replace the “<clientname>” with the designated BrightDoor Central subdomain for your client):

https://<clientname>.brightdoor.com/bdc/wsbrightdoor.asmx?op=GetAllProductDetails

Preparing Your Query
As mentioned above, a key part of the process will be understanding the exact Product Types (homes, homesites, condos, etc), Statuses (available, under contract, sold) and Attributes (neighborhood, view, etc).

If you are provided Setup level access to BrightDoor Central, you can discover the ID values for each product type, status and attribute by:

• Types – Go to the Setup > Products > Types area, roll your mouse over (or click) the “Edit” button for desired types and note the ID value at the end of the URL string.
• Statuses – Go to the Setup > Products > Status area, roll your mouse over (or click) the “Edit” button for desired statuses and note the ID value at the end of the URL string.
• Attributes – Go to the Setup > Products > Attributes area, roll your mouse over (or click) the “Edit” button for desired attributes and note the ID value at the end of the URL string.

When scouting for the ID values, please make sure any page specific search filtering is removed and you are analyzing the entire list of available options.

Product XML Data

Some notes on items you’ll notice in the XML dataset returned by BrightDoor Central:

• Fixed Properties – there are a collection of fixed product properties that are in every BrightDoor Central instance. You will see these at the top of each product’s node beginning with the productid and ending with the centerid. Regardless of whether there is a value for the property, you will at least get the empty label.
• Custom Attributes – only those defined in the “productAttributeDefIDs” parameter are returned. These appear between the centerid and Playlist and include a label for your use.

Working with Media URLs
BrightDoor Central stores all uploaded product media on our dedicated servers and you have URL access to use these in your web sites and apps. There will be some work on your end, however, to ensure you are building the desired URL prefix based on the image size(s) needed. Also, its worth noting the concept of “playlist” types you’ll see in the XML return.

Product media URL references are stored in Playlist nodes based on the media category (photo, floorplans, survey, etc). As you see in this illustration, there is a playlist type along with media filenames stored as Items within that playlist. This allows you the option to discretely serve the content in your application based on these categories, or you can choose to consolidate them together. Your call. Of note, you will recognize that we are not providing full URL paths to media files. You will be required to append the desired URL prefix to the content based on your unique site requirements.

The following URL prefixes current apply to all BrightDoor Central instances. Note the image size you’ll get returned based on each.

It will be up to you to append the appropriate URL prefix to the filename to form a full URL to access the media. Please note in the thumbnail options, you will need to insert “_tmb” between the filename (eg. image1) and extension (eg. .JPG). So, a fully formed request for an image thumbnail will look something like:

http://clientname.brightdoor.com/bdc/media/presenter/image1_tmb.JPG

Here to assist

Hopefully these instructions will get you across the finish line in integrating BrightDoor Central product information and media with you web sites and apps. Please don’t hesitate to contact your client’s BrightDoor Account Manager if you have any questions.