Rental Car Shopping API

 

  1. Overview
  2. Request Parameters
  3. Example Request
  4. Response XML
  5. Example Request/Response Pair
  6. XSD for Rental Car Shopping

 

1. Overview:

The Rental Car Shopping API delivers data describing rental car shopping results similar to those that can be obtained when shopping for rental car rates on  Hotwire.com.   Each result returned includes a URL that can be used to view additional details and complete a purchase on Hotwire.com.  

As is the case when shopping Hotwire Rental Car “Hot Rates” on Hotwire.com,  the API does not divulge the identify of rental car brands.  Hotwire customers learn the brand of the Rental Car they reserve at a “Hot Rate”  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 rental car results using parameters similar to those used to initiate a rental car search on Hotwire.com, including:

  • destination
  • pickup date and time
  • dropoff date and time

 

The data returned by the Rental Car Shopping  API includes the location and rate information for each result.    Because travel inventory changes frequently,  price and availability returned by the API cannot be guaranteed.  To minimize rate and availability changes for your application’s users,  Hotwire does not recommend caching data returned by the Rental Car Shopping API.

The Rental Car Shopping API base URL is:

http://api.hotwire.com/v1/search/car

Formats supported:  xml, json, jsonp

2. Request Parameters:

The Rental Car Shopping  API takes the following request parameters.

 

&dest=specifies a geographical anchor point for the rental car search.   Results will include neighborhoods in the city most closely matching the parameter.

  • You may specify a three letter airport code, such as JFK or LAX
  • 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.
  • If the specified location does not match a city where Hotwire has inventory, the API will return results in the closest city where inventory is available.
  • Examples:
    • &dest=LAX
    • &dest=Seattle
    • &dest=Portland,OR
    • &dest==37.792,-122.397
  • &dest= is a required parameter.


&startdate=&enddate specify pickup and dropoff dates for the rental car search.

  • Note: at present, rental car search supports stays up to 330 days from the current date, with a maximum rental duration of 60 days..
  • Examples:
    • &startdate=07/04/2010&enddate=07/11/2010  #specific pickup and dropoff dates
  • &startdate =and &enddate= are required parameters

 

&pickuptime=&dropofftime= specifies pickup and dropoff times for the rental car search. 

  • Time is expressed as 5 characters of the form HH:mm
  • HH must be in the range of 00 through 23
  • mm can be either 00 or 30.  Other values are not supported
  • The colon (‘:’) character is a required separator between the hour and minute elements of time values
  • Example
    • &pickuptime=10:00&dropofftime=13:30  # pickup at 10am, dropoff at 1:30pm
  • Note that many rental car locations have limited hours in the evenings and overnight.  Specification of pickup or dropoff times outside of typical rental car business hours may significantly  limit results.
  • &pickuptime and &dropofftime= are required parameters

 


Additional Notes:

 

  • The &limit= parameter is not supported by the Rental Car Shopping API.

 

3. Example request:

Search for Hotwire rental car rates and availability at Los Angeles International Airport, pickup up January 20, 2010 at 10:00am and dropping off January 23, 2010 at 1:30pm

http://api.hotwire.com/v1/search/car?apikey=abc123&dest=LAX&startdate=01/20/2010&enddate=01/23/2010&pickuptime=10:00&dropofftime=13:30

 

4. Response XML:

XML Responses to the Rental Car Shopping API are divided into five sections.

  • A <MetaData> section, containing descriptions of items that may be referenced repeatedly in results.  Use of the metadata section results in a more manageable message size for large result sets.
  • A <Result> section, containing descriptions of individual priced rental car results.
  • A <StatusCode> numeric, which will be 0 for successful calls.
  • A <StatusDesc> textual element, which will be ‘success’ on successful call and contain diagnostic information otherwise.
  • An <Errors> section containing detailed information describing errors for unsuccessful calls.

MetaData contains the following data:

  • <CarTypes> describing typical car models, occupant capacity, and features of each of the car types (such as offered in the result set.
    • <CarTypeCode> a four character code to be referenced in the Results section of the response.  Valid Car Type Codes include the following:
    •     •    ECAR - Economy car
          •    ICAR - Mid-size car
          •    SCAR - Standard car
          •    FCAR - Full-size car
          •    MVAR - Minivan
          •    IFAR - Mid-size SUV
          •    PDMR - Premium car
          •    SFAR - Standard SUV
          •    CCMR - Compact car
          •    LCAR - Luxury car
          •    FFAR - Full-size SUV
          •    STAR - Convertible car
          •    XDAR – Hybrid car
    • <CarTypeName> a textual description of the car type (eg Compact Car)
    • <TypicalSeating> a textual description of seating typical of this car type (eg 5 adults)
    • <PossibleFeatures> a textural description features typical of this car type (eg Air Conditioning, Power Steering ,etc)
    • <PossibleModels> a list of car makes and models typical of this car type.

Resultconsists of <CarResult> records, each of which can contain

  • <CurrencyCode>   The currency code in which all currency fields are denominated
  • <DeepLink>  A Hotwire.com link that can be used to complete a purchase of the given result.   All rates and availability are subject to change at any time.
  • <ResultId>  A unique ID for the given result.  Reserved for future use.
  • <HWRefNumber>  A reference number for the given result.  Reserved for use by other Hotwire APIs.
  • <SubTotal> The price of the result, excluding taxes and fees.
  • <TaxesAndFees> Taxes and Fees associated with the result
  • <TotalPrice> The total price of the result, including all taxes and fees.
  • <CarTypeCode> The Car Type Code associated with the result.  References Car Type data found in the MetaData section of the response.
  • <PickupDay> , <PickupTime>, <DropoffDay>, and <DropoffTime>   The rental duration associated with the given result
  • <DailyRate> As a convenience, computes the average price of the rental per day, exlusive of taxes and fees.  This is equivalent to the display price for the result on Hotwire.com.
  • <LocationDescription> If available, a textual description of where the rental car counter and the rental car will be located, usually relative to an airport.  (eg “Counter in airport; shuttle to car”)
  • <MileageDescription> A textual description of mileage limitations associated with the rental.  Typically “unlimited”.
  • <PickupAirport>  The three letter airport code of the airport where the rental car is to be picked up
  • <RentalDays> The number of days, per rental car rules, associated with the result.  Note that there results are always expressed as full days, and periods of less than 24 hours are rounded up.

Additionally, if the incoming request includes a "&linkshareid=" parameter with a valid 11 character value, then the resulting HotelDeal records will include a LinkshareDeepLink  data element.   Traffic from Hotwire affilates must come through these Linkshare comatible URLs in order for the affiliate to receive credit for resulting transactions.

Note that it is permissible to cache Hotwire neighborhood and amenity data to avoid parsing the metadata with each response.

 

5. Example request/response pair:

Shop for rental cars at LAX airport, picking up Jan 20, 2010 at 10:00am  dropping off  Jan 23, 2010 at 1:30pm http://api.hotwire.com/v1/search/car?apikey=abc123&dest=LAX& startdate=04/20/2010&enddate=04/23/2010&pickuptime=10:00&dropofftime=13:30

<Hotwire>

<Errors/>

−

<MetaData>

−

<CarMetaData>

−

<CarTypes>

−

<CarType>

<TypicalSeating>2 adults, 2 children</TypicalSeating>

<CarTypeName>Compact car</CarTypeName>

<CarTypeCode>CCAR</CarTypeCode>

−

<PossibleFeatures>

Automatic Transmission, Power Steering, Air Conditioning, Air Bags, AM/FM Stereo

</PossibleFeatures>

<PossibleModels>Chevy Cobalt, Ford Focus, or similar</PossibleModels>

</CarType>

−

<CarType>

<TypicalSeating>2 adults, 2 children</TypicalSeating>

<CarTypeName>Economy car</CarTypeName>

<CarTypeCode>ECAR</CarTypeCode>

−

<PossibleFeatures>

Automatic Transmission, Air Conditioning, Air Bags, AM/FM Stereo

</PossibleFeatures>

<PossibleModels>Chevy Aveo, Hyundai Accent, or similar</PossibleModels>

</CarType>

−

<CarType>

<TypicalSeating>5 adults</TypicalSeating>

<CarTypeName>Luxury car</CarTypeName>

<CarTypeCode>LCAR</CarTypeCode>

−

<PossibleFeatures>

Automatic Transmission, Power Steering, Air Conditioning, Air Bags, Anti-Lock Brakes, Cruise Control, AM/FM Stereo, CD Player

</PossibleFeatures>

<PossibleModels>Cadillac DTS, Lincoln Town Car, or similar</PossibleModels>

</CarType>

−

<CarType>

<TypicalSeating>7 adults</TypicalSeating>

<CarTypeName>Minivan</CarTypeName>

<CarTypeCode>MVAR</CarTypeCode>

−

<PossibleFeatures>

Automatic Transmission, Power Steering, Air Conditioning, Air Bags, Anti-Lock Brakes, Cruise Control, AM/FM Stereo

</PossibleFeatures>

<PossibleModels>Chevy Uplander, Ford Freestar, or similar</PossibleModels>

</CarType>

</CarTypes>

</CarMetaData>

</MetaData>

−

<Result>

−

<CarResult>

<CurrencyCode>USD</CurrencyCode>

−

<DeepLink>

http://www.hotwire.com/car/deeplink-details.jsp?resultId=NTI1MzMyOTMwNjo2ODAzMTI4NzIxMw--&sid=S298&bid=B311854&inputId=api-results&actionType=303

</DeepLink>

<ResultId>NTI1MzMyOTMwNjo2ODAzMTI4NzIxMw--</ResultId>

<HWRefNumber>4169664352</HWRefNumber>

<SubTotal>163.80</SubTotal>

<TaxesAndFees>50.60</TaxesAndFees>

<TotalPrice>214.40</TotalPrice>

<CarTypeCode>ECAR</CarTypeCode>

<DailyRate>40.95</DailyRate>

<DropoffDay>04/23/2010</DropoffDay>

<DropoffTime>13:30</DropoffTime>

<PickupDay>04/20/2010</PickupDay>

<PickupTime>10:00</PickupTime>

<LocationDescription>Counter in airport; shuttle to car</LocationDescription>

<MileageDescription>Unlimited</MileageDescription>

<PickupAirport>LAX</PickupAirport>

<RentalDays>4</RentalDays>

</CarResult>

−

<CarResult>

<CurrencyCode>USD</CurrencyCode>

−

<DeepLink>

http://www.hotwire.com/car/deeplink-details.jsp?resultId=NTI1MzMyOTMwNjo2ODAzMTI4NzIxMg--&sid=S298&bid=B311854&inputId=api-results&actionType=303

</DeepLink>

<ResultId>NTI1MzMyOTMwNjo2ODAzMTI4NzIxMg--</ResultId>

<HWRefNumber>4957270760</HWRefNumber>

<SubTotal>175.80</SubTotal>

<TaxesAndFees>54.04</TaxesAndFees>

<TotalPrice>229.84</TotalPrice>

<CarTypeCode>CCAR</CarTypeCode>

<DailyRate>43.95</DailyRate>

<DropoffDay>04/23/2010</DropoffDay>

<DropoffTime>13:30</DropoffTime>

<PickupDay>04/20/2010</PickupDay>

<PickupTime>10:00</PickupTime>

<LocationDescription>Counter in airport; shuttle to car</LocationDescription>

<MileageDescription>Unlimited</MileageDescription>

<PickupAirport>LAX</PickupAirport>

<RentalDays>4</RentalDays>

</CarResult>

−

<CarResult>

<CurrencyCode>USD</CurrencyCode>

−

<DeepLink>

http://www.hotwire.com/car/deeplink-details.jsp?resultId=NTI1MzMyOTMwNjo2ODAzMTI4NzIxMQ--&sid=S298&bid=B311854&inputId=api-results&actionType=303

</DeepLink>

<ResultId>NTI1MzMyOTMwNjo2ODAzMTI4NzIxMQ--</ResultId>

<HWRefNumber>3164498874</HWRefNumber>

<SubTotal>239.80</SubTotal>

<TaxesAndFees>68.66</TaxesAndFees>

<TotalPrice>308.46</TotalPrice>

<CarTypeCode>MVAR</CarTypeCode>

<DailyRate>59.95</DailyRate>

<DropoffDay>04/23/2010</DropoffDay>

<DropoffTime>13:30</DropoffTime>

<PickupDay>04/20/2010</PickupDay>

<PickupTime>10:00</PickupTime>

<LocationDescription>Counter in airport; shuttle to car</LocationDescription>

<MileageDescription>Unlimited</MileageDescription>

<PickupAirport>LAX</PickupAirport>

<RentalDays>4</RentalDays>

</CarResult>

−

<CarResult>

<CurrencyCode>USD</CurrencyCode>

−

<DeepLink>

http://www.hotwire.com/car/deeplink-details.jsp?resultId=NTI1MzMyOTMwNjo2ODAzMTI4NzIwNQ--&sid=S298&bid=B311854&inputId=api-results&actionType=303

</DeepLink>

<ResultId>NTI1MzMyOTMwNjo2ODAzMTI4NzIwNQ--</ResultId>

<HWRefNumber>4366295953</HWRefNumber>

<SubTotal>287.80</SubTotal>

<TaxesAndFees>68.47</TaxesAndFees>

<TotalPrice>356.27</TotalPrice>

<CarTypeCode>LCAR</CarTypeCode>

<DailyRate>71.95</DailyRate>

<DropoffDay>04/23/2010</DropoffDay>

<DropoffTime>13:30</DropoffTime>

<PickupDay>04/20/2010</PickupDay>

<PickupTime>10:00</PickupTime>

<LocationDescription>Counter in airport; shuttle to car</LocationDescription>

<MileageDescription>Unlimited</MileageDescription>

<PickupAirport>LAX</PickupAirport>

<RentalDays>4</RentalDays>

</CarResult>

</Result>

<StatusCode>0</StatusCode>

<StatusDesc>success</StatusDesc>

</Hotwire>

 

 

6.. Car Shopping XSD

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:import namespace="http://www.w3.org/XML/1998/namespace"
               schemaLocation="http://www.w3.org/2001/xml.xsd"/>
    <xs:element name="Hotwire" type="HotwireType"/>
    <xs:element type="xs:int" name="StatusCode"/>
    <xs:element type="xs:string" name="StatusDesc"/>
    <xs:complexType name="StatusType">
        <xs:sequence>
            <xs:element ref="StatusCode"/>
            <xs:element ref="StatusDesc"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="CarResultType">
        <xs:sequence>
            <xs:element type="xs:string" name="CurrencyCode"/>
            <xs:element type="xs:string" name="DeepLink"/>
            <xs:element type="xs:string" name="LinkshareDeepLink" minOccurs="0" maxOccurs="1"/>
            <xs:element type="xs:string" name="ResultId"/>
            <xs:element type="xs:string" name="HWRefNumber"/>
            <xs:element type="xs:string" name="SubTotal"/>
            <xs:element type="xs:string" name="TaxesAndFees"/>
            <xs:element type="xs:string" name="TotalPrice"/>
            <xs:element type="xs:string" name="CarTypeCode"/>
            <xs:element type="xs:string" name="DailyRate"/>
            <xs:element type="xs:string" name="DropoffDay"/>
            <xs:element type="xs:string" name="DropoffTime"/>
            <xs:element type="xs:string" name="PickupDay"/>
            <xs:element type="xs:string" name="PickupTime"/>
            <xs:element type="xs:string" name="LocationDescription"/>
            <xs:element type="xs:string" name="MileageDescription"/>
            <xs:element type="xs:string" name="PickupAirport"/>
            <xs:element type="xs:string" name="RentalDays"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="HotwireType">
        <xs:sequence>
            <xs:element type="xs:string" name="Errors" maxOccurs="unbounded" minOccurs="0"/>
            <xs:element type="MetaDataType" name="MetaData" maxOccurs="unbounded" minOccurs="0"/>
            <xs:element type="ResultType" name="Result" maxOccurs="unbounded" minOccurs="0"/>
            <xs:element ref="StatusCode"/>
            <xs:element ref="StatusDesc"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="CarTypeType">
        <xs:sequence>
            <xs:element name="TypicalSeating"/>
            <xs:element name="CarTypeName"/>
            <xs:element name="CarTypeCode"/>
            <xs:element name="PossibleFeatures"/>
            <xs:element name="PossibleModels"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="ResultType">
        <xs:sequence>
            <xs:element type="CarResultType" name="CarResult" maxOccurs="unbounded" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="CarMetaDataType">
        <xs:sequence>
            <xs:element type="CarTypesType" name="CarTypes" maxOccurs="unbounded" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="CarTypesType">
        <xs:sequence>
            <xs:element type="CarTypeType" name="CarType" maxOccurs="unbounded" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="MetaDataType">
        <xs:sequence>
            <xs:element type="CarMetaDataType" name="CarMetaData"/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>

version 20 as of 2 months ago by Seth Strumph