Windows  LIVE
Windows Live Expo Beta API
 

Author: John Pollard
Other contributors: Garry Wiseman, Kurt Weber, Samir Lakhani

Revised November 2006

This document supports a preliminary release of a software product that may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results from the use of this document remains with the user. Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Use of this SDK and the associated services are governed by the "Windows Live Expo API License Agreement" and the "Windows Live Terms of Use." For complete terms of use and licensing information, download the full SDK.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2006 Microsoft Corporation. All rights reserved.

Microsoft, Hotmail, MS-DOS, MSDN, MSN, Visual Studio, Win32, Windows, Windows Live, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

All other trademarks are property of their respective owners.

Contents

Introduction
Target Audience
Accessing Service
Listings Interfaces
Site Information

Introduction

The Expo API defines a set of Web services allowing customers to programmatically access the Expo classifieds listings database – a collection of location-tagged classifieds listings in categories like merchandise, real estate, autos, jobs and commercial services.

The Expo Web service is exposed to clients in two ways:

  • HTTP/GET request interface with XML response.
  • SOAP interface.

Target Audience

This API is intended for customers and partners who want to create applications that leverage the contents of the Expo classifieds listings database. Examples of applications that might be built on this API are:

  • A Web gadget displaying cars for sale in the user's city within 50 miles.
  • A Web site that allows users to overlay a map of houses available for sale in Seattle on a map.
  • A shopping Web site that allows users to comparison shop for used books and CDs.

If you have any feedback on using this SDK for writing your own code, please send us e-mail at >expoapi@microsoft.com.

Accessing Service

Every call to the API must send a unique application key that identifies the client caller. The application key is linked to the Expo account of the person who applies for the application key.

To apply for an application key:

  1. Go to http://expo.live.com/MyAPIKeys.aspx.
  2. Sign into the site with Passport.
  3. If you haven't already, create your Expo Profile.
  4. Accept the Terms and Conditions of the API Service.
  5. The application key will be displayed in the page.

To retrieve your application key at any time, simply return to http://expo.live.com/MyAPIKeys.aspx.

To generate a new application key, go to http://expo.live.com/MyAPIKeys.aspx and press the "Generate New Key" button. This will associate a new application key with your account (and obviously invalidate any previous keys you might have used).

Listings Interfaces

ListingsByCategoryKeywordLocation

This function returns Expo listings filtered by keyword, category and location.

Interface URLs

Type Base URL Function name
XML over HTTP http://expo.live.com/API/Classifieds_ListingsByCategoryKeywordLocation.ashx

 

 -
SOAP http://expo.live.com/API/Classifieds_Listings.asmx ListingsByCategoryKeywordLocation

Parameters

Parameter Type Default Restrictions Notes
appKey string N/A Mandatory Used to identify the user
page int 1 1 <= page Page number
pageSize int 10 1 <= pageSize <= 100 Results per page
orderBy string CreatedDate One of:

CreatedDate,

Price,

Distance,

EventStartDate

  
orderAscending bool true true/false Direction of ordering
keyword string ""   Keyword to search listings for
cat int N/A Mandatory Category ID - can be retrieved from GetCategories API call.
latitude double N/A Mandatory

-90.0 <= latitude <= +90.0

 Latitude
longitude double N/A Mandatory

-180.0 <= longitude <= +180.0

 Longitude
maxDist double 86,467   Distance from lat/long in meters

-1.0 means unrestricted

Default is equivalent to 50 miles
siteId int Current site   A value of zero means "use current site"

Notes

  • The total number of records that can be returned is 500.
  • A positive latitude means North, a negative latitude means South; a positive longitude means East, a negative longitude means West. For example, Seattle is 47° 27' N, 122° 18' W, which in our terms is:

    Latitude = 47 + 27/60 = 47.45

    Longitude = -(122 + 18/60) = -122.3

Return value

RSS 2.0 with extended properties.

Notes:

  • The category attributes in the return value are defined the GetCategories API call.
  • The node <classifieds:totalListings> is a count of the total number of listings that match the search query.

Example

Calling this method using the XML over HTTP/GET interface
http://expo.live.com/API/Classifieds_ListingsByCategoryKeywordLocation.ashx?appKey=-8446798441076350230&cat=66&keyword=Montlake&lat=47.686&long=-122.118&maxDist=40470
returns the following:

<rss version="2.0" xmlns:classifieds="http://expo.live.com/ns/2006/1.0">
  <channel>
  <title>Expo RSS Feed</title> 
  <link>http://expo.live.com /</link> 
  <description>Expo RSS feed</description> 
  <language>en-US</language> 
  <pubDate>Mon, 27 Mar 2006 15:12:43 GMT</pubDate>
  <classifieds:totalListings>217</classifieds:totalListings>  
  <item>
     <title>Montlake Area Home</title> 
     <link>http://expo.live.com/ViewListing.aspx?lid=3</link> 
     <description>Classic colonial on rarely available street across from the Montlake Community Center and its tennis</description> 
     <pubDate>Mon, 27 Mar 2006 08:11:00 GMT</pubDate> 
     <enclosure url="http://cache.windermere.com/pics4/ImageStore.dll?id=D954B8F207D3CAE0&w=100&h=70&bg=D1D5E1" type="image/jpeg" size="3000" /> 
     <classifieds:listingid>3</classifieds:listingid> 
     <classifieds:expirationDate>Mon, 03 Apr 2006 08:11:00 GMT</classifieds:expirationDate> 
     <classifieds:currency>$</classifieds:currency>  
     <classifieds:price>879500.00</classifieds:price> 
     <classifieds:category classifieds:id=”66” classifieds:name=”Merchandise” classifieds:transactionType=”For Rent”> 
     <classifieds:postedBy>JohnDoe</classifieds:postedBy> 
     <classifieds:location>
          <classifieds:address>1611 E calhoun</classifieds:address> 
          <classifieds:city>Seattle</classifieds:city> 
          <classifieds:state>WA</classifieds:state> 
          <classifieds:country>USA</classifieds:country>  
          <classifieds:postcode>98112</classifieds:postcode> 
          <classifieds:latitude>47.6410919703104</classifieds:latitude> 
          <classifieds:longitude>-122.310574373249</classifieds:longitude> 
     </classifieds:location>
     <geo:lat>47.6410919703104</geo:lat> 
     <geo:long>-122.310574373249</geo:long>
     <classifieds:details>
        <classifieds:YEAR_BUILT>1908</classifieds:YEAR_BUILT> 
        <classifieds:NUMBER_BEDROOMS>3</classifieds:NUMBER_BEDROOMS> 
        <classifieds:NUMBER_BATHROOMS>2.50</classifieds:NUMBER_BATHROOMS> 
        <classifieds:FLOOR_AREA /> 
        <classifieds:LOT_SIZE>5200.00</classifieds:LOT_SIZE> 
     </classifieds:details>
  </item>

ListingsByCategoryKeywordLocation_V2

This function returns Expo listings filtered by keyword, category and location and transaction type. This interface allows search by postal code, city and state rather than latitude and longitude.

Interface URLs

Type Base URL Function name
XML over HTTP http://expo.live.com/API/Classifieds_ListingsByCategoryKeywordLocation_V2.ashx

 

 -
SOAP http://expo.live.com/API/Classifieds_Listings.asmx ListingsByCategoryKeywordLocation_V2

Parameters

Parameter Type Default Restrictions Notes
appKey string N/A Mandatory Used to identify the user
page* int 1 1 <= page Page number
pageSize* int 10 1 <= pageSize <= 100 Results per page
orderBy string CreatedDate One of:

CreatedDate,

Price,

Distance,

EventStartDate

  
orderAscending bool true true/false Direction of ordering
keyword string ""   Keyword to search listings for
cat int N/A Mandatory Category ID - can be retrieved from GetCategories API call.
city string ""   City
state string ""   State
postalCode string ""   Postal/ZIP code
country string ""   Country
maxDist double 86,467   Distance from lat/long in meters

-1.0 means unrestricted

Default is equivalent to 50 miles
siteId int Current site   A value of zero means “use current site”
transactionType string ""   Transaction type - can be retrieved form GetCategories() - see below

Notes:

  • The total number of records that can be returned is 500
  • There must be enough information in the combination of city, state, postal code and country for the MapPoint service to be able to find the address — see http://msdn.microsoft.com/mappoint/ for specific details.

Return value

RSS 2.0 with extended properties.

Notes:

  • The category attributes in the return value are defined the GetCategories API call.
  • The node <classifieds:totalListings> is a count of the total number of listings that match the search query.

Example

Calling this method using the XML over HTTP/GET interface
http://expo.live.com/API/Classifieds_ListingsByCategoryKeywordLocation.ashx?appKey=-8446798441076350230&cat=66&keyword=Montlake&lat=47.686&long=-122.118&maxDist=40470 would return the following:

<rss version="2.0" xmlns:classifieds="http://expo.live.com/ns/2006/1.0">
  <channel>
  <title>Expo RSS Feed</title> 
  <link>http://expo.live.com /</link> 
  <description>Expo RSS feed</description> 
  <language>en-US</language> 
  <pubDate>Mon, 27 Mar 2006 15:12:43 GMT</pubDate>
  <classifieds:totalListings>217</classifieds:totalListings>  
  <item>
     <title>Montlake Area Home</title> 
     <link>http://expo.live.com/ViewListing.aspx?lid=3</link> 
     <description>Classic colonial on rarely available street across from the Montlake Community Center and its tennis</description> 
     <pubDate>Mon, 27 Mar 2006 08:11:00 GMT</pubDate> 
     <enclosure url="http://cache.windermere.com/pics4/ImageStore.dll?id=D954B8F207D3CAE0&w=100&h=70&bg=D1D5E1" type="image/jpeg" size="3000" /> 
     <classifieds:listingid>3</classifieds:listingid> 
     <classifieds:expirationDate>Mon, 03 Apr 2006 08:11:00 GMT</classifieds:expirationDate> 
     <classifieds:currency>$</classifieds:currency>  
     <classifieds:price>879500.00</classifieds:price> 
     <classifieds:category classifieds:id=”66” classifieds:name=”Merchandise” classifieds:transactionType=”For Rent”> 
     <classifieds:postedBy>JohnDoe</classifieds:postedBy> 
     <classifieds:location>
          <classifieds:address>1611 E calhoun</classifieds:address> 
          <classifieds:city>Seattle</classifieds:city> 
          <classifieds:state>WA</classifieds:state> 
          <classifieds:country>USA</classifieds:country>  
          <classifieds:postcode>98112</classifieds:postcode> 
          <classifieds:latitude>47.6410919703104</classifieds:latitude> 
          <classifieds:longitude>-122.310574373249</classifieds:longitude> 
     </classifieds:location>
     <geo:lat>47.6410919703104</geo:lat> 
     <geo:long>-122.310574373249</geo:long>
     <classifieds:details>
        <classifieds:YEAR_BUILT>1908</classifieds:YEAR_BUILT> 
        <classifieds:NUMBER_BEDROOMS>3</classifieds:NUMBER_BEDROOMS> 
        <classifieds:NUMBER_BATHROOMS>2.50</classifieds:NUMBER_BATHROOMS> 
        <classifieds:FLOOR_AREA /> 
        <classifieds:LOT_SIZE>5200.00</classifieds:LOT_SIZE> 
     </classifieds:details>
  </item>

ListingsByUser

This function returns listings posted by a particular user, identified by their nickname.

Interface URLs

Type Base URL Function name
XML over HTTP http://expo.live.com/API/Classifieds_ListingsByUser.ashx

 

 -
SOAP http://expo.live.com/API/Classifieds_Listings.asmx ListingsByUser

Parameters

Parameter Type Default Restrictions Notes
appKey string N/A Mandatory Used to identify the user
page int 1 1 <= page Page number
pageSize int 10 1 <= pageSize <= 100 Results per page
orderBy string Descending One of:

CreatedDate,

Price,

Distance,

EventStartDate

  
orderAscending bool true true/false Direction of ordering
nickname string "" If not empty, must match an existing Expo nickname If empty, we will return listings made by the owner of the application key
siteId int Current site   A value of zero means "use current site"

Note: The total number of records that can be returned is 500.

Return Value

RSS 2.0 with extended properties.

Calling this method using the XML over HTTP/GET interface
http://expo.live.com/API/Classifieds_ListingsByUser.ashx?appKey=3ql7F3haDCmCdh2szMIRN*MzM!RcC49f0*F*Vmms3gF5dkx6xFL4zJEsOUM6W7iIL6&nickname=JohnSmith
results in listings posted by the user whose registered nickname on Expo is "JohnSmith". Format of return value is identical to ListingsByCategoryKeywordLocation API call.

Site Information

These methods return information about the Expo site itself.

GetCategories

This function returns all of the available categories and attributes on the site. The caller could use the results of this query to dynamically pre-fill categories and attribute values to be returned from a listing search. The caller could also use this method to determine the schema of listing search results.

Interface URLs

Type Base URL Function name
XML over HTTP http://expo.live.com/API/Classifieds_GetCategories.ashx -
SOAP http://expo.live.com/API/Classifieds_Listings.asmx GetCategories

Parameters

Parameter Type Default Restrictions Notes
appKey string N/A Mandatory Used to identify the user
siteId int Current site   A value of zero means "use current site"

Return Value

RSS 2.0 with extended properties.

Example

Calling this method using the XML over HTTP/GET interface
http://expo.live.com/API/Classifieds_ListingsByCategoryKeywordLocation.ashx?appKey=-8446798441076350230&cat=66&keyword=Montlake&lat=47.686&long=-122.118&maxDist=40470
returns XML like the following:

<classifieds:categories xmlns:classifieds="http://expo.live.com/ns/2006/1.0">
<classifieds:category classifieds:id="2" classifieds:name="Autos">
<classifieds:categoryAttributes>
                    <classifieds:attribute classifieds:name="PRIMARYCITY" classifieds:displayName="City" classifieds:type="String" /> 
                     <classifieds:attribute classifieds:name="STATE" classifieds:displayName="State" classifieds:type="String" /> 
                     <classifieds:attribute classifieds:name="POSTALCODE" classifieds:displayName="Zip Code" classifieds:type="String" /> 
                     <classifieds:attribute classifieds:name="PRICE" classifieds:displayName="Price" classifieds:type="Number" />
 
    </classifieds:categoryAttributes>
 
<classifieds:category classifieds:id="4" classifieds:name="Boats">
<classifieds:categoryAttributes>
                     <classifieds:attribute classifieds:name="PRIMARYCITY" classifieds:displayName="City" classifieds:type="String" /> 
<classifieds:categoryAttributes>
              <classifieds:attribute classifieds:name="STATE" classifieds:displayName="State" classifieds:type="String" /> 
              <classifieds:attribute classifieds:name="POSTALCODE" classifieds:displayName="Zip Code" classifieds:type="String" /> 
              <classifieds:attribute classifieds:name="PRICE" classifieds:displayName="Price" classifieds:type="Number" /> 
              <classifieds:attribute classifieds:name="YEAR_BUILT" classifieds:displayName="Year built" classifieds:type="Number" /> 
              <classifieds:attribute classifieds:name="AUTOS_BOAT_SIZE" classifieds:displayName="Boat Size" classifieds:type="Number" /> 
<classifieds:attribute classifieds:name="COLOR" classifieds:displayName="Color" classifieds:type="PickList">
                     <classifieds:attributeOption /> 
                     <classifieds:attributeOption>Black</classifieds:attributeOption> 
                     <classifieds:attributeOption>Blue</classifieds:attributeOption> 
                     <classifieds:attributeOption>Brown</classifieds:attributeOption> 
                     <classifieds:attributeOption>Green</classifieds:attributeOption> 
                       <classifieds:attributeOption>Orange</classifieds:attributeOption> 
                     <classifieds:attributeOption>Purple</classifieds:attributeOption> 
                     <classifieds:attributeOption>Red</classifieds:attributeOption> 
                     <classifieds:attributeOption>Silver</classifieds:attributeOption> 
                       <classifieds:attributeOption>White</classifieds:attributeOption> 
                     <classifieds:attributeOption>Other</classifieds:attributeOption> 
           </classifieds:attribute>
    </classifieds:categoryAttributes>
  </classifieds:category>
...
   </classifieds:categories>
 

Notes

  • The root node is <classifieds:categories>, and the category nodes are <classifieds:category>.
  • The categories follow the hierarchy of categories on the Expo site.
  • A category can have a set of categoryAttributes, which denote the set of extended attributes specific to this category.
  • If an attribute has a type "PickList", then the list of allowable attributeOption values are given.

GetSites

The Windows Live Expo service will be available in a number of international markets. Every supported market is actually a different site, and all API calls require the site be specified as a parameter. This interface can be used to determine the complete list of supported sites and markets.

Interface URLs

Type Base URL Function name
XML over HTTP http://expo.live.com/API/Classifieds_GetSites.ashx -
SOAP http://expo.live.com/API/Classifieds_Listings.asmx GetSites

Parameters

Parameter Type Default Restrictions Notes
appKey string N/A Mandatory Used to identify the user

Return Value

RSS 2.0 with extended properties.

Example

Calling this method using the XML over HTTP/GET interface
http://expo.live.com/API/Classifieds_ListingsByCategoryKeywordLocation.ashx?appKey=-8446798441076350230&cat=66&keyword=Montlake&lat=47.686&long=-122.118&maxDist=40470
returns XML like the following:

<classifieds:sites xmlns:classifieds="http://expo.live.com/ns/2006/1.0">
<classifieds:site classifieds:id="1" classifieds:name="Windows Live Expo" classifieds:baseUrl="http://expo.live.com" /> 
<classifieds:site classifieds:id="2" classifieds:name="Windows Live Expo UK" classifieds:baseUrl="http://expo.live.co.uk" /> 
</classifieds:sites>
 

Notes

  • The root node is <classifieds:sites>, and the category nodes are <classifieds:site>.
  • The categories follow the hierarchy of categories on the Expo site.

Page view tracker