February 8th, 2010

What is an API?

By James Wilson, VP of Development

First… it is an acronym

API is an acronym which means Application Programming Interface.

What is it?

It is a contract that allows computers to talk to each other. Another name used widely is a protocol which is a set of rules that must be followed to exchange information. By “talk”, I mean the ability to ask a question and get a valuable answer back.

How does it work?

A really smart computer person (a developer) defines and builds a system that accepts questions (request for information). Next, that same developer writes instructions (the contract or protocol) that must be followed in order to properly accept questions so that the valuable answers can be computed and returned. Another developer, somewhere else in the world, reads the fascinating and tantalizing contract documentation. She then sets out to build a unit within her own system to ask questions at the proper time. Her system then uses the subsequent answers to deliver great value to that system’s end users.

What should be in an API’s contract?

1) Location, Name and Protocol

• Mechanism or protocols to be used to establish a connection. These are typically another lower level type of API or contract.
• The address or location of the system that can answer the questions.
• Name of the service.

Let’s give an example of a typical business to business (B2B) scenario. Just below is a URL or web address used to locate a service which finds nearby pizza delivery services.

http://www.pizza-store-locator.com/service/find-the-closest-pizza-delivery

The protocol used is established with the text: “HTTP”. HTTP is another acronym which stands for Hypertext Transfer Protocol. This is another contract which specifically defines how a web browser, like FireFox or IE, can communicate with a web server. Many higher level business services are built on top of this lower level API.

The location of this API is defined as “www.pizza-store-locator.com“. This type of string is typically called a domain in web parlance.  A domain is always associated with an IP address. This is a unique identifier and allows request to be reliably routed to the appropriate web server. An IP address is an acronym meaning “Internet Protocol” address. There is that word, “protocol”, again. The whole WWW, World Wide Web, is just a series of layered protocols that allow everyone to talk to everyone else.

The name of the  service is “service/find-the-closest-pizza-delivery”. This name is mapped to business logic, or a program, on the web server in this case that is responsible for formulating an answer. Just guessing, but this service probably helps find pizza delivery services. It is nice when the name of a service is self describing!! That is the sign of a good API.

2) Input Definition

• What questions can be asked?
  • Is there only one questions or different types of questions?
• What are all the pieces of information that must be included in the question so I can answer it?
  • In the example above, for the pizza delivery service, what information is required to find the closest pizza delivery shop? The contract could specify an address is required like 90 Broad Street, Suite 2002, New York, NY.  But it could also just be a latitude and longitude.
  • Lets keep going… how far away are you interested in searching? 5 Miles, 10 Miles or do you care? No, you don’t because it is not you that must do the driving to the pizza shop so… perhaps you only want a certain number of shop results back like 20 or 5? Perhaps you do need 20 but want to have at least 5 different pizza shop options returned so you can get a good selection.
  • All this stuff needs to be defined by the service creator based upon research by a product manager into how people actually think and what they want.
• How should all of those pieces of information be structured?
  • There are many ways to send information to the service.
    • We can send it as query string parameters.  For example..
      • http://www.pizza-store-locator.com/service/find-the-closest-pizza-delivery?LATITUDE=108&LONGITUDE=-47&number-of-different-types-of-shops=10.
    • We can send it as XML
      • <latitude>108</latitude><longitude>-47</longitude><number-of-different-types-of-shops>10</number-of-different-types-of-shops>

3) Outputs

• A description of the answers that can be returned
• Format of the answers
• Exceptions or errors that can be expected
  • A good API will defined all of the possible bad scenarios that can occur and how it will notify the calling program. This allows the calling program to respond gracefully.
  • Here are some examples to possible bad return results:
    • Not enough information was submitted, and here is specifically what was missing: the latitude.
    • The service is temporarily down.
    • The service is too busy, please try again later.
    • No results were found.
    • Results were found but not as many as you asked for because we only search within a maximum distance of 10 miles
    • This service has moved to a new address…
    • …and so on…
  • Typically each of the possible errant answer is give a unique identifier or code which allow computers to respond easily.

An “out of this world” example…

Do you remember “Close Encounters of a Third Kind” when the scientists first started communicating with the huge alien ship that came over the mountain? Sure you do… who can forget this brilliant movie that is now such a fundamental part of the fabric of our existence. Well… in this movie, the scientist use mathematics manifest through sound and lights to try to establish basic communication with the aliens. Once the alien understood, they repeated back the message to say to the scientists, quite loudly, “Yes, we heard you!” An interface was established, an agreement that if you flash your lights and send over sound waves, we will capture that information, process it, and send you back beeps and blips along with flashing light signals too (and the result of this will be that we land our ship and change the very nature of your lives!).

References

I have listed some common websites to give other definitions of an API; however, they commit some of the cardinal sins when defining a entity.

1.     Wikipedia

1. Sin! - They use the object in the definition itself.

2.     How Stuff Works

1. Sin! - They use the noun in the definition itself.
2. And worse still they limit the definition of API’s to web technologies.  It is important to understand that API’s are EVERYWHERE… for example… inside a computer, API’s are established to allow software to run  successfully on a computer’s hardware which has nothing to do with the web.

Tags: API, Application Programming Interface, James John Wilson, James Wilson PMP, Onboard Informatics, What is?.

May 4th, 2009

Did You Know?

By Colleen McKeating, Product Manager

Now that activity seems to be picking up in a number of markets, time is in short supply for agents. There is a need to supply clients, or potential clients, with as much information as possible without spending an inordinate amount of time trying to do so. The demographic, school, nearby establishments and home sales information is the exact type of information that home buyers are looking for.

Well, how about being able to place an API on your site where a visitor can enter their name, email address and zip code to receive all of this information? And how about being able to accomplish this in 3 easy steps? The above can easily be accomplished by utilizing the API from our CoPilot product.

A little background first for those of you who are not familiar with our CoPilot product. CoPilot provides customized reports for relocation purposes or for agents looking to provide home buyers with location specific information. Reports can easily be customized with the broker’s logos/headers. Agents can even choose what data sets that they want to include, whether that be community information, school reports, nearby establishments or recent home sales transactions. One of the best feature is the ability to collect client information and track whether they are opening the reports, and even how many times they have accessed the report.

The API functionality and instructions can be found at My Profile –> API. The three steps that would be required for this type of set-up include:

1. Create your default report template. Instructions are included for this in the Administrative system.
2. Add the lead form to your website. The lead form HTML is included so all you need to do is copy and paste.
3. Customize your landing page. The landing page HTML is included so all you need to do is copy and paste.

Upon entering their information into the Lead Form, a report is emailed to the user. An agent can then follow-up accordingly.

By posting this simple API to a website, all of the hard work is eliminated from having to create individual reports each time a client makes a request for more information. Reports can even be emailed detailing recent API activity – contacts created, reports created and reports read.

This is a great way to easily distribute all of our excellent data to your clients. If you are currently one of our clients on the CoPilot platform we strongly encourage you to take advantage of this very powerful feature. For those of you who do not utilize CoPilot at the moment we would love to talk to you about it.

If there are any additional questions please feel free to reach out to me at cmckeating@onboardinformatics.com or to our Product Support team at support@onboardinformatics.com.

Let us know any feedback you may have on the API functionality.

Tags: API, copilot, Products.

March 16th, 2009

Lifestyle Listings Engine…Another Step

By Scott Petronis, Senior Director of Product Management

In my last post I described the current capabilities in the Lifestyle Listing Engine Web Service and also mentioned some of the new things in the works. Well, we’ve been diligently at work and I’m happy to report we have some new stuff nearly ready for debut. In about a week we’ll have our next release ready for review. So I’m going to concentrate this post on what’s new and talk a bit more about what’s on the way.

A few cool new things we’re just completing put the “lifestyle” in lifestyle search. And believe me, this is just the start. To start we’ve focused on exposing some key new search criteria and also added a new content retrieval concept into the web service.

The concept is simple: there are criteria people will use to “drive” their search and then there’s additional content one wishes to see to help better educate herself/himself on the area surrounding the listing. So we’re exposing easily understood and highly relevant criteria in the search web service. Then we’re exposing more detailed content that may be pulled for presentation on the listing detail page.

School Performance
The first new search criteria is one of the most crucial for the largest demographic of homebuyers nationwide—families with school age children.  In fact, school performance can be THE driving force.  So we’ve focused our initial efforts on enabling searches based on school ratings from GreatSchools.   Now, within the Listings Web Service a desired GreatSchools rating (such as 8 or greater) can be identified and the search will return listings nearby those schools.  This way, a user can get an understanding of school performance up front rather than having to dig through a whole bunch of information after the search.  This may also be combined with other criteria so the user may search for listings within a specified distance of an address (i.e., their workplace), select a desired number of beds and baths, and input a price range.  The search will take into account all the criteria to execute the search.

The search can be initiated to just show counts of listings that meet the criteria.   Or it may pull back the listings themselves so they may be presented in tabular or map form.  Records returned may be pre-sorted based on any of the criteria submitted.  For example, you may choose to sort on the GreatSchools rating from greatest to least if that’s the criterion the user indicated is most crucial.

In addition to the search capability, a new call has been added to pull back the details of the school district.  This is especially useful when presenting the listing detail.  The way this works is that once a specific listing is pulled back, another request may be made (“GetContentSchoolDistrict”) for the detailed information on that specific school district.  This pulls back information such as number of students, student teacher ratios, enrollment by grade, expenditures, and more.  Once retrieved, this content might then be presented in another tab within the listing details page or however your design dictates.  So users don’t have to go searching for this information on their own, nor do you have to link off to another site to provide it.   It keeps the user engaged on your site and  provides the added benefit of improving SEO by adding locally relevant content into your pages.

Nearby Amenities
Another common way people search is by nearby amenities such as golf courses, parks or playgrounds, cafes and a wide variety of other “points of interest.”  We have loads of this data that we’re integrating into the search and have started with over a dozen key categories including: schools, parks and playgrounds, golf courses, grocery stores, cafes, public swimming pools, hospitals, airports, libraries, bookstores, veterinarians, pharmacies, health clubs, and universities.   Depending on the individual’s lifestyle and what stage of life they’re in, one or more of these may be crucial in their home search.

Using these criteria a search may be conducted to determine the listing located within a certain distance of a desired amenity.  Likewise, they may wish to ensure that they are NOT near one of these as well.  For example, someone may want to be near a golf course but NOT near a school.  Or they may wish to be near a school, park or playground and library, but further away from an airport.  There are numerous ways these criteria may be used to enhance the search experience and drive the relevance of the results.

Just like with the school district content, the details of each nearby amenity may also be retrieved for display.   So if there’s a golf course, nearby, the listing web service will return the name, address and other pertinent details.  The same holds true for any of the amenities.  This way, a list of nearby amenities may be displayed on the listing details page or in its own tab to help give a solid impression of the area and all it has to offer.

Other Search Criteria
We’re in the process of fleshing out a host of additional criteria for use in the search.  These decisions are being driven by ongoing research with both sides of the equation—home buyers and searchers as well as real estate brokers and agents.  We’re gaining great insight into how people search, what information they feel they need, where they tend to find this information today and what role the broker or agent plays in this laborious process.  As more of this information is collected, I’m looking forward to sharing the results to help drive more thoughtful design and better user experiences.

One criteria that’ made to the top of the list (I mentioned it in my last post) is the ability to search based on a desired “commute time or distance.”  This is well underway and we’re very close to getting out a first cut.  With this new capability, a user will be able to input their work location and either a desired commute time or a maximum commute distance.  The system will then calculate the potential areas and will retrieve the listings that are within those areas.  As we all know, there can be a significant difference between the straight line distances most searches use and the actual road distance.  Case in point, New Jersey is just across the Hudson River from New York and if you could kayak across, you’d be golden.  But for those of us not in the kayaking mood, we have to cross a pesky bridge.  So our commute time calculations will take this sort of situation into account.  Of course this will have maximum value when we can incorporate transit which we’re diligently working towards.

Other criteria on the docket right now are:

• Area demographics (i.e., average age, household income, family type, etc.)
• Cost of Living (i.e., total cost of living, cost of living per category, COL vs. the national average and vs. the general area, etc.)
• Safety (i.e., area crime, health, air quality, weather, natural disaster and other factors that impact safety and security) Note to self…see if Earth, Wind & Fire is available for launch party.
• Fun (i.e., bars, clubs, museums, arts and entertainment, and other places and events that give an area a “fun factor”)
• Employment Statistics (i.e., white collar vs. blue collar, does the area have more professionals or laborers, etc.)
• Educational Achievement (i.e., does the area have mostly college educated people or high school attainment?)

Again, depending on the lifestyle and stage of life the searcher is in, one or more of these items may be paramount.  As a young family just starting out, I may want to find places with other young families that tend to hold similar professions but also an area where the cost of living is reasonable compared to the national average.  An “empty nest” couple may also be looking for a lower cost of living but wish to be near others in a similar age group and might not care so much about the employment statistics.  So these different criteria may be used by different groups to identify the best fit for their needs.

Smoothing out the edges
As I mentioned in my last post, what we’re providing right now is purely an  that can be accessed via SOAP or using RESTful HTTP requests.  So one area we’re about to start diving into is the creation of some SDKs to “smooth out the edges.”  Many of the people I’ve talked to so far develop primarily in C#, are using .Net Framework 2.0 and primarily work in Microsoft VisualStudio .Net. So this is our likely starting point.  I’ve also spoken with quite a few PHP developers who work primarily on a LAMP (Linux, Apache, MySQL, PHP) technology stack.  So this appears to be the next logical environment.  But I’d like to hear more about what environments your working in, tools you use, and the extent to which you’d like to see UI widgets vs. pure .

I realize time is a precious commodity none of us have enough of, so I want to be sure we’re delivering enough to get you well on your way but not so much that we take away the very benefits of a flexible web service.  So what’s “enough” in your mind?

Please keep the comments coming and pipe in with your ideas as well as your critiques!

Feel free to reach out to me at spetronis@onboardinformatics.com until my next post.

Tags: API, geocode search, geocoding, Lifestyle, lifestyle search, listings, LLE, onboardinformatics, Products, property search.

February 20th, 2009

Lifestyle Listings Engine Web Service - New Property Search Version 0.8 Delivered

By Scott Petronis, Senior Director of Product Management

This week we launched the first version of our Lifestyle Listings Engine– version 0.8. The Listings Web Service has been in process for some time and has been in use by a number of early beta testers who have provided a lot of great feedback.  Over the coming weeks and months we’ll continue our work on improving what’s there, adding in additional search capabilities and filling in more details in terms of documentation, samples and so forth.  So there’s still a lot more to come.

What we have readily available through the web service are two primary search mechanisms—geographic and parametric. The web service is accessible using WSDL and conforms to SOAP 1.1 or 1.2.  You may also use REST over HTTP.   I’d like to provide a brief overview of the capabilities to give a sense of what’s possible. Then I’ll give a little insight into what’s next.

Geographic Search 

There are a number of geographic search capabilities built directly into the Listings Web Service so there’s no need to use another service unless you want to.   For example, you may geocode addresses directly through the web service without needing to make a separate call to Microsoft Virtual Earth or other service. For all search requests, there’s the option to bring back just the listings counts (e.g., 62 listings met the search criteria) or the listings themselves (listing summaries in XML). The specific geographic search capabilities in the web service include:

• GeoCode – Allows for address input and return either a <latitude> <longitude> (coordinate) pair or a string to be used in proximity searches.
• GeoCodeSearch – Allows for entry of a latitude/longitude pair and distance, and returns the records that meet the criteria. This can be used in concert with the GeoCode call or by passing lat/long values obtained from other services.
• GeoPointSearch – Allows for the entry of an already geocoded point and distance (radius) and returns the records that meet the criteria.
• AddressSearch – Allows for input of an Address and Search Distance and returns the records that meet the criteria.
• Poly and PolyPointSearch – Allows for entry of a set of geographic points (polygon) as either an array or from a file and returns the records that fall within the corresponding polygon (area). This is particularly useful when the UX includes a map interface where the user may select a custom, highly-refined geographic area to search within.
• CitySearch – Allows for the input of City/State and returns the records that meet the criteria.
• ZipSearch – Allows for entry of specific ZIP Code and returns the records that meet the criteria.
• HoodIdSearch – Allows for entry of an Onboard Neighborhood ID and returns the records that meet the criteria.

Geographic Lookup

In addition to geographic search functionality, we provide a robust and pre-defined geographic model upon which all other relationships are built. The web service exposes this in a way that lets you interact with various levels of geography for both searching and presentation to the user.  For example, you might want to present a series of selection lists, each of which is predicated on the one before it such as: select the state you which to search in, then select the county(ies), then select the neighborhood(s). The web service provides the following geographic “lookup” capabilities to enable this:

• LookupStates – Returns a list of all State covered based on the Account ID.
• LookupCountyByState – Allows for entry of a specific State and returns all Counties that fall within the specified State.
• LookupCityByState – Allows for entry of a specific State and returns all Cities/Places that fall within the specified State.
• LookupZipsByState – Allows for entry of a specific State and returns all ZIP Codes that fall within the specified State.
• LookupCityByCounty – Allows for entry of a specific State/County and returns all Cities/Places that fall within the specified County.
• LookupHoodMarket – Allows for entry of a specific Market and returns all Neighborhoods that fall within the specified Market.
• LookupHoodState – Allows for entry of a specific State and returns all Neighborhoods that fall within the specified State.
• LookupHoodAll – Enables retrieval of a list of all Neighborhoods that are available based on the Account ID.

Listings Lookup and Detail

The last area I’m going to cover is some of the capabilities specific to the feeds and the listings themselves. Again, some of these calls may be used on their own or in concert with the other calls depending on the UX you’re going for. Some of these calls are purely for “utility” purposes such as just understanding what content you have access to.  Most are pretty self-explanatory and very straight-forward.

• GetListingDetail – Allows for input of a specific Property ID in order to retrieve the detailed attributes of that specific listing. In the calls above, you’ve gotten back the listings that meet the search parameters. Now with this you pull back all the details on the individual listing.
• GetListingsFeedSearchByMlsIds – Allows for MLS ID input and returns the specific MLS property record.
  
• GetListingsFeedSearch – Allows for input of a Feed ID and returns all listings within that feed.
• LookupAgentsByFeed – Allows for entry of a specific Feed ID and returns all Agents associated to the specified Feed.
• LookupAllFeeds – Enables retrieval of a list of all Feeds that are available based on the Account ID submitted.
• LookupCurrentCitiesByFeed – Allows for entry of a specific Feed ID and returns all Cities covered by the specified Feed. This can be used, for example, to display a coverage list.
• LookupCurrentZipsByFeed – Allows for entry of a specific Feed ID and returns all ZIP Codes covered by the specified Feed.
• LookupPropertyTypes – Returns a list of all property types associated to the property (listings) records.
• LookupRecordRules – Returns a list of all display rules associated to the Account ID. Specific rules may apply based on licensing terms or other legal restrictions.
• LookupSearchableFeatures – Returns a list of all searchable features associated to the property (listings) records.
  

Of course, in addition to all the functionality described above, the standard parametric search capabilities you’d expect are also included.  These search parameters may be set to filter results in any of the other searches:

• PropertyType
• MinPrice
• MaxPrice
• MinSize
• MaxSize
• Bedrooms
• Bathrooms
• MinYearBuilt
• MaxYearBuilt
• SearchDistance
• FeatureProfile
• DOM (Days On Market)
• FeedID
• AgentID
• OfficeID
• AgentName
• OfficeName
• RecordLimit (Max number of records to return)
• Sort (specific value to sort by)

There’s one additional capability worth special note.   A “SpecialFormat” flag allows you to set a priority to be placed on Agent or Office criteria to move any listings for the specified agent or office to the top of the list. It requires that either an Agentname or Officename filter be submitted and then takes precedent over the Sort value and order. Any values in the Sort parameter would be acted on next.

What’s Next?

As I mentioned at the top, this is just the beginning. We’re diligently working on enhancements around the clock. Major items in the works include: search based on school performance (e.g., show me only listings with 4+ bedrooms, 2.5+ baths for between $300,000 and $350,000 in areas that have great schools); search based on commute time (show me only listings that are within a 30 minute drive to work); and, search based on distance to one or more amenities (I want to see places that are within 5 miles of a golf course).

Beyond this, I’m looking for feedback on:

• Web service usability – we have a fleshed out foundation here, but what would make it more useable to fit within your design patterns? I’d love to get some additional Beta testers.
• Development environments – what development environments are you working with? .Net, PHP, Java/JSP, Adobe ColdFusion, Adobe Flex?
• Helpers and samples – beyond the API, what would help to reduce your development time and speed deployment? Sample PHP code? JavaScript helpers? AJAX widgets?
• Output formats – beyond XML, what would make your life easier? JSON output?
• Search functionality – we have loads of additional lifestyle characteristics we can make available but the key is prioritizing the most important ones first. Your feedback is always welcome to help shape those priorities!

Until next time…

-sap

Tags: API, geocode search, geocoding, Lifestyle, lifestyle search, listings, LLE, onboardinformatics, Products, property search.

February 17th, 2009

Onboard Informatics Announces the Delivery of Lifestyle Listings Engine

By Megan Murphy, Marketing Manager

 Imagine if people could search for a home based on their lifestyle.

New York, NY. 2-17-2009 – Onboard Informatics, the premier data services company for top companies in real estate, technology and media, has announced the delivery of the Application Programming Interfaces (APIs) of Lifestyle Listings Engine: the first ever enterprise-class solution enabling property search based on consumer lifestyle choices. 

“With our expertise in data collection, standardization, and analysis, our clients were constantly asking us if we can help them with listings,” said Marc Siden, CEO of Onboard.  “But we wanted to offer something to the industry beyond just the best, cleanest, and most efficient listings.  So by combining our wealth of property data, community, schools, and amenities datasets,  with the best listings data in the industry, then layering on a search logic that takes human preferences into account, we are able to offer the first search engine that works the way the human mind does.”

The Lifestyle Listings Engine, introduced at the Inman News Real Estate Connect Event in New York, features a Human Centered Search (HCS) API enabling a multivariate, multi-weighted search experience.  Users are able to search based on schools system ratings, commute time, amenities, neighborhood info, and more at the same time.

“For years, Onboard has been providing data analytics to companies such as CNN/Money for feature stories on selecting best places to live, best places for retirement, and best places for families,” said Peter Goldey, Chief Information Officer of Onboard.  “We knew that our algorithms and our search logic were something that our clients in real estate could really benefit from, so we’ve created that toolset.”

The Lifestyle Listings Engine also features the most advanced handling of listings data, management of MLS relationships and IDX rules with its proprietary Compliancy Engine technology, and simplifies development by providing a single, consistent data feed from hundreds of disparate feeds.

According to Liam Dayan, Chief Technology Officer of Onboard, the HCS technology is made possible by the robust data handling technology behind the scenes: “What we’ve done is taken our expertise and systems for handling disparate data sources, aggregating them, cleaning them, and making the resulting data easy to use, and applied them to listings.  We then blend that cleaned dataset with the rest of our content, using our proprietary system.  That facility with data is the ‘secret sauce’ if you will that allows us to create applications like Human Centered Search.”

For more information regarding Onboard Informatics or Lifestyle Listings Engine, please either visit www.onboardinformatics.com or call 747.646.4273.

Tags: API, data, IDX, Liam Dayan, Lifestyle Listings Engine, lifestyle search, marc siden, MLS, Onboard Informatics, Peter Goldey, Real Estate.