Hotel Deals API

1. Overview
2. Request Parameters
3. Example Requests
4. Response XML
5. Example Request/Response Pair

1. Overview

The Hotel Deals API delivers data describing hotel "Deals" discovered on Hotwire.com in the past 24 hours.   A "deal" is a Hotwire search result whose value is attractive relative to other results.  The concept of value includes not only absolute price, but also star rating and the relative popularity of the location and of the travel dates.

As on Hotwire.com,  the API does not divulge the identify of specfic hotels.  Hotwire customers learn the identify of the hotel they book after their purchase is complete.  In exchange for their flexibility, they can save quite a bit of money.     If you're new to Hotwire.com, an introduction may be found here:  http://www.hotwire.com/newtohotwire/index.jsp. 

The API allows the developer to search for deals using a variety of parameters, including:

• location
• price
• hotel star rating
• travel dates
• travel length of stay
• restrict to weekend stay
• time since deal was discovered

Within the constraints specified by the parameters in a Hotel Deals API call, developers can also specify whether they'd like to retrieve deals with the best absolute price, the best value, or the closest proximity to the location they've specified.

The data returned by the Hotel Deals API includes the Hotwire.com city, neighorhood, and star rating for the deal, as well as a Hotwire.com nightly rate, and the date and time at which the deal was found on Hotwire.com.    Because travel inventory changes frequently,  price and availability may change between the time a deal is discovered on Hotwire.com and the time it is retrieved via the Hotel Deals API. 

The Hotel Deals API base URL is:

http://api.hotwire.com/v1/deal/hotel

Formats supported:  xml, json, jsonp, rss, atom

2. Request Parameters:

The Hotel Deals API takes the following request parameters, in addition to the common parameters described in URL Conventions:

&dest=&distance= specifies a geographical anchor point for the hotel deal search.   results will include neighborhoods whose centers are within a specified distance range from this point.

• You may specify a lat,lon pair.
• You may specify a string that we can geocode into a lat,lon pair.   You can try addresses, city names, and points of interest.  
• Be aware that the API will proceed with a "best match" for ambiguous destinations, so developers should attempt to resolve ambiguous inputs before calling the API.
• Examples:
  • &dest=Seattle
  • &dest=Seattle|Miami|Houston
  • &dest=Portland,OR
  • &dest==37.792,-122.397
  • &dest=Alcatraz&distance=*~20       #within 20 miles of Alcatraz
  • &dest=Chicago&distance=50~150  #>50 and <150 miles outside of Chicago in any direction 
• Default value for distance is 15 miles.
• If no destination is specified, the search may return the top hotel deal results worldwide, as ordered by the specified or default sort order

&startdate=&enddate=&duration= specifies date and stay-length ranges to limit the checkin and checkout dates returned by the hotel deal search

• Note: at present, hotel deals data is limited to checkins within the next 30 days.
• Examples:
  • &startdate=07/04/2009&enddate=07/11/2009  #specific checkin and checkout dates
  • &startdate=07/04/2009  # specific checkin date, any checkout date
  • &startdate=07/04/2009&duration=4~6 # specific checkin date, length of stay between 4 and 6 nights
  • &startdate=07/05/2009|07/12/2009&duration=2  # checkin date is either 7/5 or 7/12 for a 2 night stay
  • &startdate=07/05/2009~07/12/2009&duration=3~4 # checkin any time between 7/5 and 7/12 for a 3 or 4 night stay
  • &duration=5~*   # any checkin/checkout dates and length of stay of 5 nights or more
  • &enddate=7/11/2009   # checkout is 7/11/2009, any checkin date

&weekend=  specifies whether or not to limit the results to weekend stays

• value may be true or false, and defaults to false if the parameter is not specified
• requests a "weekend stay", which is defined as a stay of at least 2 nights, checking in on a Thursday, Friday, or Saturday and checking out the following Saturday, Sunday, or Monday.
• Example
  • weekend=true

&weekends= specifies whether or not to limit the results to weekend stays falling in the next n weekends relative to the current date.

• Allows developers to maintain a static URL pointing to the coming one or more weekends without requiring a specific date in the URL string.
• Example
  • &weekends=2  # return results for weekend stays falling on the current weekend and the following weekend only

&daystoarrival=  limit checkin dates to a range of days specified relative to the current date.

• allows developers to maintain a static URL pointing to values such as "tomorrow" or "the next 7 days" without requiring a specific date in the URL string.
• Examples
  • &daystoarrival=1   # checkin tomorrow
  • &daystoarrival=7~14   # checkin 7-14 days from today

&tonight= shorthand for a one night stay.  Equivalent to “&daystoarrival=0”

• allows developers to maintain a static URL pointing representing a "tonight" search without requiring a specific date in the URL string.
• Example
  • &tonight=true    # checkin tonight 
  • &tonight=true&duration=1   # 1 night stay beginning tonight

&starrating= limit results to those whose Hotwire.com star rating falls in the specified range.

• Hotwire.com star ratings may fall between 1 and 5 stars in half star increments
• Hotwire results designated as "Deals" must be 3 stars or greater
• Example:  
  • &starrating=4~*   #  4 stars or greater

&age= limit results to those found in a specified lookback period

• Specify the "age" of the deals returned, as indicated by their "founddate" attribute
• Takes a range value, expressed in minutes.
• If no age is specified, deals found in the last 24 hours will be returned
• Example:   
  • &age=0~30   #  deals found on Hotwire.com in the last 30 minutes
  • &age=240~* # deals found on Hotwire.com more than 4 hours ago

&limit= limit response to a specified number of records.

• Optionally specify an offset to support "paging" through results in subsquent calls.
• If no limit is specified, the response will be limited to a default number of records
• A maximum number of records per call will be established.  Specifying a limit above the maximum will result in an error or truncation of results.
• Examples
  • &limit=10  #return 10 records
  • &limit=5|10  #return records 11 through 16
• Note:  the selection of which records will be returned within the specified limit is influenced by the sort field and sort order.

&sort=&sortorder= specify a sort field and sort order for results to be returned

• valid sort fields are "value", "price", and "distance,  defaulting to "value"
• valid sort orders are "asc" and "desc".   Each sort field carries its own default sort order which can be overriden with the "&sortorder=" parameter.
• The default sort order for price is "asc", for value it's "desc", for distance, it's "asc"
• Example:
  • &sort=price&sortorder=desc   # order the results by price, from high to low.

&hwpos=uk toindicate that currency amounts should be presented in GBP, and that deeplinks should point to the Hotwire.co.uk site rather than to Hotwire.com.  At this time, USD and GBP are the only currencies supported.

•  Example: 
  • &hwpos=uk

&diversity= to improve diversity of results, limit result sets to no more than one for the specified dimension.  In the initial release of the Hotel Deals API, the only supported dimension is "city".

•  Example:
  • &diversity=city

3. Example requests:

• Retrieve the top 5 Hotwire hotel deals by value, limiting results to one per city
  • http://api.hotwire.com/v1/deal/hotel?apikey=abc123&limit=5&diversity=city
• Retrieve the top 4-star Hotwire hotel deal by price within 30 miles of New York City
  • http://api.hotwire.com/v1/deal/hotel?apikey=abc123&limit=1&dest=NYC&distance=*~30&starrating=4~*&sort=price
• Retrieve the top 20 hotel deals by value for a stay of 5 or more nights at a nightly rate of under $125, limiting results to one per city
  • http://api.hotwire.com/v1/deal/hotel?apikey=abc123&limit=20&price=*~125&duration=5~*&diversity=city
• Best five deals for the next two weekends between 50 and 150 miles away from San Francisco, limiting results to one per city
  • http://api.hotwire.com/v1/deal/hotel?apikey=abc123&limit=5&dest=san+francisco&distance=50~150&diversity=city
• Lowest priced five star hotel deals worldwide,  limiting results to one per city
  • http://api.hotwire.com/v1/deal/hotel?apikey=abc123&starrating=5&sort=price&diversity=city

4. Response XML:

XML Responses to the deals API may include multiple hotel deal records, tagged as <HotelDeal></HotelDeal>

Each HotelDeal contains the following data:

• FoundDate:  the date and time the specified rate was found on hotwire.com
• City:  hotel location
• StateCode:  hotel location
• CountryCode: hotel location
• Neighborhood: hotel location
• NeighborhoodLatitude:  neighborhood centroid
• NeighborhoodLongitude: neighborhood centroid
• StartDate: checkin date
• EndDate: checkout date
• IsWeekendStay: boolean indicating whether the result is a “weekeend stay”
• NightDuration:  number of nights between StartDate and Enddate
• Price:  Nightly rate, in USD or GBP.
• StarRating: hotwire.com hotel star rating
• Url:  hotwire.com URL to launch a live search on Hotwire.com matching the destination and stay dates.  Note that the results of the live search will include multiple neighborhood and star rating options, and that pricing and availability may be different at the time of the live search relative to the cached "deal".

Additionally, if the incoming request includes a “&impactRadiusId=“ parameter with the Impact Radius Media Partner ID, then the resulting HotelDeal records will include a ImpactRadiusUrl data element.  Traffic from Hotwire affiliates must come through these Impact Radius tracking URLs in order for the affiliate to receive credit for resulting transactions.

Note that "Neighborhood" refers to the Neighborhood on Hotwire.com where the deal is available, and that the Neighborhood latitude and longitude coordinates refer to that neighborhood's geographical center.   If your application uses HotelDeal data, note that you must display either the Url or ImpactRadiusUrl link.  See the API terms of use for details.

Also note that the “FoundDate” data element indicates the last time the rate was observed on Hotwire.com.  The hotel deals API returns data up to 24 hours old.   Rates and availability may change at any time.

5. Example request/response pair:

Retrieve the best hotel deal currently available for Chicago.

http://api.hotwire.com/v1/deal/hotel?dest=chicago&apikey=abc123wxyz&limit=1

<Hotwire>
−
<Result>
−
<HotelDeal>
<City>Chicago</City>
<CountryCode>US</CountryCode>
<FoundDate>2009-06-15T03:49:02-07:00</FoundDate>
<NightDuration>4.0</NightDuration>
<EndDate>07/05/2009</EndDate>
<Headline>Chicago 4 Star Hotel, $49/night</Headline>
<NeighborhoodLatitude>42.007072</NeighborhoodLatitude>
<NeighborhoodLongitude>-87.90308</NeighborhoodLongitude>
<Neighborhood>O'Hare Intl Airport ORD North</Neighborhood>
<Price>48.999996</Price>
<StarRating>4.0</StarRating>
<StartDate>07/01/2009</StartDate>
<StateCode>IL</StateCode>
−
<Url>
http://www.hotwire.com/hotel/search-options.jsp?inputId=hotel-index&destCity=Chicago%2CIL&startDate=07/01/2009&endDate=07/05/2009&bid=B311402&sid=S298
</Url>
<IsWeekendStay>false</IsWeekendStay>
</HotelDeal>
</Result>
</Hotwire>