TripStarter APIs

Tripstarter API

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

1. Overview

Tripstarter is a Hotwire feature designed to help travelers find the best time of year to travel to a particular destination.   The feature offers a view of price trends for for airfares between your home city and your destination of interest, as well as historical weather data and price trends for hotels at the destination.  Each record in the data returned indicates an average price (historical hotel rates or air fares) over a historical seven day period.  Trends are revealed by examing price data over a period of time, or by examing year-over-year price changes.

Visit the Tripstarter page on Hotwire.com to see the full list of supported Origin and Destination cities.  Of note, all origin cities currently included in the Tripwatcher Air data are located within North America.

Tripstarter Air data includes historical weekly averages of the lowest published coach-class airfares found in searches on Hotwire or its affiliates. Searches were conducted 14-30 days prior to departure date. Fares include applicable tax recovery charges and fees and are subject to change and availability. 

Tripstarter Hotel data includes historical weekly averages of the lowest published rates of 3-star, 3.5-star and 4-star hotels found in searches on Hotwire or its affiliates. Searches were conducted 3-30 days prior to check-in date. Rates do not include applicable tax recovery charges and fees and are subject to change and availability.

Using the Tripstarter APIs, it will be possible for developers to create a variety of travel planning and travel research applications leveraging the Hotwire TripStarter data sets.   In addition to using an origin and destination as a starting point for travel planning,  the API allows

• queries across multiple origins and destnations
• queries restricted to specified times of year
• queries based on historical pricing (absolute pricing, year-over-year trends, or high-season/low-season)
• queries based on historical weather data

The Tripstarter API base URLs are:

• TripStarter Historical Hotel Rates: http://api.hotwire.com/v1/tripstarter/hotel
• TripStarter Historical Air Fares:  http://api.hotwire.com/v1/tripstarter/air
Formats supported:  xml, json, jsonp

2. Request Parameters:

The Tripstarter APIs take the following request parameters, in addition to the common parameters described in URL Conventions:

&startdate=&enddate=  specify the range of travel dates for which to return historical hotel rate or airfare data.

• TripStarter historical price data reflects averages paid for airfares (based on date of departure) and 3 to 4 star hotel rooms (based on  date of checkin) over historical calendar weeks.  Records returned will be bounded by weeks including the specified start and end dates.
• Note that “startdate” and “enddate” refer to the boundaries of the ranges to consider for departure/checkin dates.  Specifically, “enddate” does not refer to return or checkout dates.
• Examples: 
  • &startdate=01/01/2008&enddate=12/31/2008 # departures/checkins during calendar year 2008

&dest=&distance=  specify a destination of interest and a distance radius from the given destination.

• Examples: 
  • &dest=SFO&distance=300  #within 300 miles of SFO 
  • &dest=Chicago|Detroit|Cleveland  #  destination can be any of Chicago, Detroit, or Cleveland

&origin=  specify an origin city (applies only to queries for air fares, not hotel rates)

• Examples: 
  • &origin=Seattle   # all flights originating from Seattle 
  • &origin=Seattle&dest=Miami   # specific origin/destination of Seattle to Miami

&price= restrict results to records that fall within the specified price range

• Examples 
  • &price=*~300   #  price <=  $300 (USD) 
  • &price=200~400   #  price between $200 and $400 (USD)

&yoychange= limit results to records where the year-over-year change for the given week falls within the specified range

• Examples 
  • &yoychange=10~20  # year over year price increase between 10% and 20% 
  • &yoychange=-20~-30   # year over year price drop between 20% and 30%

&travelseason= if specified as "high" or "low", limits results, respectively, to those records whose price falls above or below the yearly average for the record's destination (or in the case of air fare records, for the record's origin and destination). 

• Examples 
  • &travelseason=high
  • &travelseason=low

&avghightemp=&avglowtemp=&precip= restrict results to those records for which the average monthly high temperature and/or low temperature (in deg F), and rainfall (in inches) at the destination falls in the specified range.

• Examples
  • &avghightemp=70~*  # high avg temperature >= 70F
  • &avglowtemp=50~60  #low avg monthly temperature between 50F and 60F
  • &precip=*~2  # monthly rainfall <= 2 inches

&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  "price", "distance", "date', and "rainfall"  defaulting to "price"
• 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 and rainfall is "asc", for distance and date it's "desc"
• Example:
  • &sort=price&sortorder=desc   # order the results by price, from high to low.

3. Example requests:

• Retrieve historical hotel rate data for May 2009 in locations where the monthly average high temperature is between 70 and 75 degrees and where prices fell more than 30% vs the previous year
  • http://api.hotwire.com/v1/tripstarterl/hotel?apikey=abc123&limit=20&startdate=5/1/2009&enddate=5/31/2009&avghightemp=70~75&yoychange=*~-30
• Retrieve historical hotel rate data showing dates and locations within 300 miles of boston, sorted by distance to Boston where prices were below the yearly average, and where monthly average high temperature is at least 50 degrees F.
  • http://api.hotwire.com/v1/tripstarter/hotel?apikey=abc123&startdate=1/1/2009&dest=boston&distance=*~300&travelseason=low&avghightemp=50~*&sort=distance
• Retrieve historical hotel rate data showing price decreases of at least 40% where hotel prices are above $150 per night.
  • http://api.hotwire.com/v1/tripstarter/hotel?apikey=abc123&price=150~*&yoychange=*~-40
• Retrieve historical airfare data for departures from the three major New York airports (JFK, LGA, and EWR) to the two Bay Area airports (SFO and OAK)
  • http://api.hotwire.com/v1/tripstarter/air?apikey=abc123&origin=JFK|LGA|EWR&dest=SFO|OAK
• Retrieve historical airfare data from Seattle in October 2008 to destinations averaging less than 1 inch of rain for the month, with roundtrip fares under $200
  • http://api.hotwire.com/v1/tripstarter/air?apikey=abc123&origin=Seattle&price=*~200&precip=*~1&startdate=10/1/2008&enddate=10/31/2008

4. Response XML:

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

Each AirPricing or HotelPricing contains the following data:

• AverageMaxTemp:  The historical multi-year average of high temperatures at the destination for the given calendar month (in deg F)
• AverageMinTemp: The historical multi-year average of low temperatures at the destination for the given calendar month (in deg F)
• AveragePrecipitationInches: The historical multi-year average of rainfall at the destination for the given calendar month (in inches)
• AveragePrice:  The historical average hotel rate or roundtrip airfare for the given destination or origin/destination for the week starting "WeekStartDate"
• CurrencyCode: The currency code to associate with "AveragePrice"
• DestinationAirportCode:  The primary airport code associated with the destination
• DestinationCity:  The destination city
• DestinationCountryCode:  The destination country
• DestinationLatitude:  The latitude of the destination city's primary airport
• DestinationLongitude: The longitude of the destination city's primary airport
• DestinationStateCode: The destination state
• Season:  The "travel season", often called "high season" or "low season".  We define high season as the set of weeks where the price was greater than the yearly avarage.
• Month:  The numerical month (1-12) of the record in question.
• Url:  The hotwire.com URL to display with the given record, as required by the API terms of use. 
• WeatherAttribution:  Display the WeatherAttribution value along with any textual or graphical representation of weather data returned by the API.
• WeekStartDate: The start of the calendar week whose average pricing is reflected in the given record.
• YearOverYearChange:  The percentage change in average price relative to the same calendar week in the previous year.  May be positive or negative.

Additionally, AirPricing records contain "Origin*" data elements mirroring the "Destination*" data elements described above.

−
<Hotwire>
−
<Result>
−
<HotelPricing>
<AverageMaxTemp>99.0</AverageMaxTemp>
<AverageMinTemp>69.0</AverageMinTemp>
<AveragePrecipitationInches>0.1</AveragePrecipitationInches>
<AveragePrice>62.0</AveragePrice>
<CurrencyCode>USD</CurrencyCode>
<DestinationAirportCode>LAS</DestinationAirportCode>
<DestinationCity>Las Vegas</DestinationCity>
<DestinationCountryCode>US</DestinationCountryCode>
<DestinationLatitude>36.08036</DestinationLatitude>
<DestinationLongitude>-115.152336</DestinationLongitude>
<DestinationStateCode>NV</DestinationStateCode>
<Season>high</Season>
<Month>6</Month>
−
<Url>
http://www.hotwire.com/tripstarter/details.jsp?originAirportCode=SFO&destinationAirportCode=LAS&origCity=San+Francisco%2C+CA&destCity=Las+Vegas%2CNV&showTab=hotel&bid=B311402&sid=S298
</Url>
−
<WeatherAttribution>
WEATHER SOURCE: National Oceanic and Atmospheric Administration, National Climatic Data Center, Asheville, North Carolina
</WeatherAttribution>
<WeekStartDate>06/14/2009</WeekStartDate>
<YearOverYearChange>-42.056076%</YearOverYearChange>
</HotelPricing>
</Result>
</Hotwire>