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.
- &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.
&origin= specify an origin city (applies only to queries for air fares, not hotel rates)
&price= restrict results to records that fall within the specified price range
&yoychange= limit results to records where the year-over-year change for the given week falls within the specified range
&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).
&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.
&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.
- &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"
- &sort=price&sortorder=desc # order the results by price, from high to low.
- The geography associated with TripStarter origins and destinations is currently based on airports. This is true for both historical airfare records and historical hotel rate records. For example, a TripStarter hotel record for the origin "San Francisco" is associated with the latitude and longitude of SFO. As a result, searches requesting records within a distance range from a specified location may at times return surprisng results, since the distance computation is relative to the city's airport, not the city's center.
- 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
- 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.
- Retrieve historical hotel rate data showing price decreases of at least 40% where hotel prices are above $150 per night.
- 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)
- 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
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.
- 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.
Note that if the incoming request includes a valid "&linkshareid=" parameter, then the resulting HotelDeal records will include a LinkshareUrl data element.
Retrieve the most recent historical hotel record where the average price is under $75
- <DestinationCity>Las Vegas</DestinationCity>
- WEATHER SOURCE: National Oceanic and Atmospheric Administration, National Climatic Data Center, Asheville, North Carolina
− <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>