Request and Response Conventions

Base URL's for APIs currently available are:

  • Hotel Deals http://api.hotwire.com/v1/deal/hotel
  • Hotel Shopping http://api.hotwire.com/v1/search/hotel
  • Rental Car Shopping http://api.hotwire.com/v1/search/car
  • Historical Hotel Rates: http://api.hotwire.com/v1/tripstarter/hotel
  • Historical Air Fares:  http://api.hotwire.com/v1/tripstarter/air

Let's establish some conventions that we intend to apply across all Hotwire API's.

Common Parameters

  • apikey:  all API's require a valid apikey parameter.   Register your application to get one.
  • format:  all API's return XML, JSON, and JSONP, defaulting to XML.  Additionally, RSS and ATOM are supported for the Hotel Deals API only. Use the "format" parameter to select an output format other than XML.
  • linkshareid: if you are a Hotwire.com affiliate and include your valid Linkshare id in your request,  Hotwire.com-bound URLs returned by the API will be constructed to route through Linkshare so that you receive affiliate credit for transactions resulting from traffic you generate. 

Value Specification

  • distance: all distance values are denominated in miles by default.
  • currency: all currency values are denominated in USD by default.  GBP support is provided for the Hotel Deals and Hotel Shopping APIs only.
  • temperature: all temperature values are denominated in degrees Farenheit by default.
  • dates: all date values are specified using the format MM/DD/YYYY (eg 05/23/2009)
  • ranges: ranges are expressed using the tilde character ('~') as a separator (eg &price=100~125). 
    • All numeric parameters may be expressed as ranges (unless the documentation says otherwise).
    • Open-ended ranges may be expressed using an asterisk ('*') in place of a value on either side of the separator.  (eg &price=*~99 or &startdate=06/25/2009~*)
  • lists: lists are expressed using the pipe character ('|') as a separator (eg &dest=miami|chicago|houston). 
    • All parameters may be expressed as lists (unless the documentation says otherwise).
    • Lists of up to 5 elements are supported.

Errors and Status Codes

  • Application developers may inspect the HTTP status code of the response to determine whether an API call was denied execution.  See http://www.w3.org/Protocols/HTTP/HTRESP.html for the exhaustive spec.   In particular, it's useful to understand that a status of 403 is returned in the header when the developer has exceeded a quota threshold.
  • Alternatively,  API calls that execute but return no data due to errors in query parameters will receive a valid HTTP response (HTTP status 200), but a payload including an <Errors></Errors> element, describing the situation.