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.

&dropOffDest= specifies a geographical anchor point for the rental car search. 

  • You may specify the same kind of information as &dest=
  • If &dropOffDest is populated, the search will be one way- the pickup location will be different than the dropOff location.
  • This is an OPTIONAL parameter. If this parameter is NOT included, the search will be assumed to be round trip (roundtrip = where the same location are used for both pickup and dropOff).
  • As a result of using this parameter, these new 4 fields will be returned (each of these has a corresponding field for pickup):
  • DropOffAirport (corresponds to "PickupAirport" for pickup")
  • DropOffLocationDescription (corresponds to the "LocationDescription" for pickup)
  • VendorDropOffLocation (corresponds to "VendorLocation" for pickup)
  • VendorDropOffLocationId (corresponds to "VendorLocationId" for pickup)
  • To optimize performance, we ask that you use discretion when attempting one way searches
    for     resultType=O (hotrate/opaque cars), as there are not usually many results available. 

&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

&resultType=filters API results by opacity type. It is an optional parameter.

  • When not specified there is no change to the existing API response
  • &resultType=O  - returns opaque results only. Will appear with a new element <OpacityCode>Opaque</OpacityCode> and  <CarVendorCategory>
  • &resultType=N  - returns prepaid and postpaid retail results only. Will appear with new elements<OpacityCode>{‘Retail' for postpaid retail results AND ‘Prepaid' for prepaid retail results}</OpacityCode>, <RentalAgency>{name of the vendor}</RentalAgency>, <VendorLocation>{name of the vendor location}</VendorLocation>
  • &resultType=A  - returns all opaque, prepaid and postpaid retail results, distinguished with a new element <OpacityCode> and additional elements in case of retail results (opaque results will also contain <CarVendorCategory>).

            Values for OpacityCode can be Opaque, Retail and Prepaid.

            Values for CarVendorCategory can be 1 or 2.

&includeResultsLink specifies whether or not to include a Hotwire.com link that leads to search results with a selected result on the top. It is an optional parameter.

  • When not specified there is no change to the existing API response
  • &includeResultsLink=true means to  include <ResultsDeepLink> element to each retail result
  • &includeResultsLink=false does not change the existing API response

&includeMobileRates specifies whether or not to include RetailMobile rates in the response.

  • When not specified there is no change to the existing API response.
  • &includeMobileRates=true -  returns RetailMobile rates for qualified Vendors
  • &includeMobileRates=false - will not return RetailMobile rates 

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:

      Car Type

      US

      Canada

      Caribbean, Europe, Mexico, Africa, Asia, Australia, South America

      Economy car

      ECAR

      ECAR

      EBAN, EBAR, EBMN, EBMR, ECAN, ECAR, ECMN, ECMR, EDAN, EDAR, EDMN, EDMR

      Compact car

      CCAR

      CCAR

      CBAN, CBAR, CBMR, CCAN, CCAR, CCMN, CCMR, CDAN, CDAR, CDMN, CDMR

      Full-size car

      FCAR

      FCAR

      FCAR, FCMR, FDAR, FDMR

      Full-size SUV

      FFAR, FRAR

      FFAR, FRAR

      FFAR, FRAR, FFMR, FRMR

      Mid-size car

      ICAR

      ICAR

      ICAR, ICMR, IDAR, IDMR

      Mid-size SUV

      IFAR

      IFAR

      IFAR, IFMR

      Luxury car

      LCAR

      LCAR

      LCAR, LDAR

      Minivan

      MVAR

      MVAR

      MVAR, MVMR

      Premium car

      PCAR

      PCAR

      PCAR, PDAR

      Standard car

      SCAR

      SCAR

      SCAR, SCMR, SDAR, SDMR

      Standard SUV

      SFAR

      SFAR

      SFAR, SFMR

      Standard Pickup truck

      SPAR

      SPAR

      -

      Convertible car

      STAR

      STAR

      STAR

      Special car

      SXAR, XXAR

      -

      -

      Compact Wagon

      -

      -

      CWAR, CWMR

      Mini

      -

      -

      MBAR, MBMN, MBMR, MCAR, MCMN, MCMR, MDAR, MDMN, MDMR

      Standard Wagon

       

       

      SWAR, SWMR
    • <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.

Result consists 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.
  • <OpacityCode> Indicates if the car result is 'Opaque' or 'Prepaid' or 'Retail' or 'RetailMobile'. Note that 'RetailMobile' is used for only mobile retail rates. 
  • <VendorLocation> Location of the car vendor, only appears when result is retail
  • <RentalAgency> Name of the car vendor, only appears when result is retail
  • <CarVendorCategory> Appears when the result is an Opaque (Hotrate) car, is a number such as 1 or 2
  • <ResultsDeepLink>  A Hotwire.com link that leads to search results with a selected result on top. All rates and availability are subject to change at any time. Use &includeResultsLink=true request parameter to get this element.

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 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>
 
<CarVendorCategory>1</CarVendorCategory>

<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="ImpactRadiusUrl" 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:element type="xs:string" name="RentalAgency"/>
            <xs:element type="xs:string" name="VendorLocation"/> 
            <xs:element type="xs:string" name="OpacityCode"/>
            <xs:element type="xs:string" name="ResultsDeepLink" minOccurs="0" maxOccurs="1"/>
        </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 42 as of 4 years ago by Adina