The Vehicle Matrix transaction provides a basic Vehicle Search Availability request that returns a maximum amount of vehicle rates in the fastest time possible. This transaction supports web-based applications that display a table of vehicle rates where the axes represent vehicle suppliers by vehicle types. The Vehicle Matrix response provides all of the data necessary to complete this grid in one transaction. Additional (Get More) transactions are not required to obtain all response data.
Important! Wordspan (1P) do not support Vehicle Matrix functionality. If a Vehicle Matrix request is sent to Worldspan (1P), the Matrix-specific request attributes are ignored and a standard Vehicle Search response is returned with a warning message: ReturnAllRates not supported by Worldspan, and has been ignored.
Schema
See the following transactions for Vehicle Search:
- VehicleSearchAvailabilityReq
- VehicleSearchAvailabilityRsp
Request
VehicleSearchAvailabilityReq is used to request Vehicle Matrix searches. The Vehicle Matrix request is similar to a standard Vehicle Search request, but is differentiated by a Return All Rates indicator. The response returns all response items in a single call, but typically includes truncated response data for individual Vehicle items.
Note: Vehicle Matrix is equivalent to the CarMatrix transaction in GWS.
Set ReturnAllRates to "True" to return a Vehicle Matrix response.
For a more specific response:
- Set ReturnApproximateTotal to "True" to have rates in the response quoted in approximate totals. Because only suppliers with an Inside Availability connection to Apollo or Galileo can support approximate totals, only Inside Availability suppliers are returned. If ReturnApproximateTotal is set to "False", best rates for all applicable suppliers are returned.
- Set ReturnExtraRateInfo to "True" to return expanded rate information in the response. Note that fewer total rates are returned because each rate item is longer.
A single VehicleDateLocation/PickupLocation and /PickupLocationNumber item can be requested. Only one PickupLocationType is currently supported by Universal API, and should be considered when using Vehicle Matrix. Only one specific ReturnLocation is currently supported when using Vehicle Matrix.
VehicleSearchModifiers/ReferencePoint is not supported for the Vehicle Matrix request; reference points are supported in the response only. Reference point data is ignored if it is sent in the request.
Only Vehicle Class 'A' is supported, so VehicleType must begin with an 'A'. See Vehicle Search by Vehicle Type for a list of supported Vehicle Types.
VehicleSearchModifiers @PreferredCurrency can be specified to request vehicle rates in a user's preferred currency. E.g., PreferredCurrency="EUR". All converted rates are returned, regardless of the providers to whom the request was submitted. See the response for details.
NextResultReference data is not included in Vehicle Matrix requests because all data is returned in one response.
Requests can include an exact pickup, exact return, or exact pickup and return locations.
- Include VendorLocation @VendorLocationID in the request to specify an exact pickup location OR include VendorDateLocation @ PickupLocation, @PickupLocationType, and @PickupLocationNumber in the request to specify an exact pickup location.
- Include VendorDateLocation @ReturnLocation, @ReturnLocationType, and @ReturnLocationNumber in the request to specify an exact return location.
If only @ReturnLocation is specified it is assumed to be an airport. If @ReturnLocation is not specified, the pickup location is assumed to be the return location as well.
All schema versions support submitting exact pickup and return locations.
Exact Pickup and Return Locations
Vehicle Search requests on the Galileo (1G) and Apollo (1V) providers can include:
- Up to three generic pickup locations for up to 10 vendors, and one exact return location.
- Up to three exact pickup locations for up to 10 vendors, and one generic return location.
Multiple pickup locations, or an exact pickup location, can be specified by including VehicleDateLocation/VendorLocation:
- @LocationCode
- @LocationType
- @VendorLocationID
- @VendorCode
Notes:
- The request can include exact pickup locations and an exact return location with one or multiple vendors. All attributes must be included in the request (@ProvidorCode, @VendorCode, @LocationCode, @LocationType, @VendorLocationID, @Type) for both Pickup and Return.
- For Exact Pickup and Return to Pickup Location with one or multiple vendors, all attributes must be included in the request (@ProvidorCode, @VendorCode, @LocationCode, @LocationType, @VendorLocationID, and @Type) for Pickup; the return is not included in request.
Only one generic return location can be specified.
-
If VendorLocation @LocationType and @LocationID are not included in the request, the default return location is an airport.
- If VendorLocation @Type="Pickup" or ="Return", and VehicleDateLocation attributes are specified, only VendorLocation attributes are processed and a warning is returned.
A warning is returned if:
- The maximum number of vendors/exact pickup/exact return locations allowed per provider is exceeded. Universal API processes up to the maximum number and ignores all others. The warning lists the pickup and return locations that were not processed.
- The request includes VendorLocation @Type and VehicleDateLocation attributes (@PickupLocation, @PickupLocationType, @PickupLocationNumber, @ReturnLocation, @ReturnLocationType, or @ReturnLocationNumber). The warning lists the VehicleDateLocation attributes that were not processed.
If @Type (Pickup or Return) is specified in /VendorLocation and any one of required /VendorLocation attributes for exact pickup and return locations are not specified; @ProviderCode, @VendorCode, @LocationCode, and @LocationType, Universal API fails and returns an error that “XXX” attribute was not specified. Error Message: “”XXX”, “XXX” not specified in / VendorLocation”
For exact Pickup and exact Return requests where both VehicleDateLocation/VendorLocation@VendorCode and VehicleSearchModifiers@PermittedVendors are present, Universal API takes the value from VehicleDateLocation/VendorLocation@VendorCode and ignore @PermittedVendors. Universal API returns the following warning message “PermittedVendors “XX” was not processed in the request” where XX = vendor code.
See the response for more details.
Response
A Vehicle Matrix response is returned when ReturnAllRates is set to "True". The response contains all rates in VehicleSearchAvailabilityRsp. If ReturnAllRates is set to "False", a standard Vehicle Search response is returned, based on existing Universal API functionality.
- The following elements are not specifically returned in the Vehicle Matrix response; however, Universal API automatically converts the four-letter pseudo Vehicle Type into the applicable description.
- TransmissionType
- AirConditioning
- FuelType
- DoorCount
- Because the Vehicle Matrix transaction has limited description and detail, the following elements are not returned. A follow-on Vehicle Rules transaction is required to obtain this data:
- Description
- VendorName
- Alternate Vendor
- VehicleRateDescription
- ThirdPartySupplierName
- When specifying all rates, the VendorLocationKey is returned.
- Depending on whether ReturnApproximateTotal is set to "True" or "False" in the request, either Approximate Total Rate or Base Rates are returned:
- "True": Rates in the response are quoted in approximate totals in @EstimatedTotalAmount. Because only suppliers with an Inside Availability connection to Apollo or Galileo can support approximate totals, only Inside Availability suppliers are returned.
- "False": Best rates for all applicable suppliers are returned in @BaseRate.
- DropOffChargesIncluded indicates if the supplier included drop-off charges in the rate. The inclusion of this data is at the discretion of the supplier, and may not always be reflected in the result.
- Required Payment information in the response varies depending on whether ReturnExtraRateItems is set to "True" or "False" in the request.
- "False": Required Payment information is returned in @RequiredPayment, when applicable.
- "True": Required Payment information is returned in @RateGuaranteeType.
Note: Vehicle Search Availability requests do not support Approximate Total functionality, regardless of Inside Availability status for the supplier. This functionality is available through Vehicle Matrix only.
Universal API processes up to the maximum number of vendors and maximum number of exact pickup and return locations allowed per provider and ignores all others. A warning is returned in the response that lists the pickup locations that were not processed.
VehicleSearchRsp @ReturnAtPickup indicates whether a vehicle can be returned at any location (ReturnAtPickup="false") or at the pickup point only (ReturnAtPickup="true"). Only Galileo (1G) and Apollo (1V) support the attribute.
Two new elements were added to Vehicle/VehicleRate:
- SupplierRate: Non-converted rates from the vehicle supplier.
- ApproximateRate: Converted rates into the preferred currency specified in the request.
The following attributes were removed from VehicleRate and added to each of the new elements:
- EstimatedTotalAmount
- BaseRate
- DropOffCharge
- RateForPeriod
- ExtraMileageCharge
If PreferredCurrency is specified in the request, converted rates are returned in the VehicleRate/ApproximateRate element. If PreferredCurrency is not specified, the SupplierRate element is populated. If Preferred Currency is requested in the same currency as the vendor currency, the rates that are returned are not converted. Only one type of rate (converted or non-converted) is returned in a response by Galileo or Apollo, not both.
For example, in a request to the Galileo provider, if the Pseudo City Code (PCC) has a currency of EUR, and @PreferredCurrency="USD" in the Vehicle Search request, converted rates are returned in USD.
Note: This functionality is not backwards compatible.
Exceptions
Galileo and Apollo
The Return Location Attributes are echoed from VehicleSearchAvailabilityReq:
- /VehicleDateLocation
- @ReturnLocation
- @ReturnLocationNumber
- @ReturnLocationType
Or
- /VendorLocation@LocationCode
- /VendorLocation@VendorLocationID
- /Veh:VendorLocation@LocationType
When /Veh:VendorLocation@Type =”Return”
Note: These attributes are not be returned or echoed in the response if not populated in the request.
Worldspan
Wordspan (1P) does not support Vehicle Matrix functionality. If a Vehicle Matrix request is sent to Worldspan, the Matrix-specific request attributes are ignored and a standard Vehicle Search response is returned with a warning message: ReturnAllRates not supported by Worldspan , and has been ignored.
