This page describes the basic concepts used by Spotnana APIs for car rental bookings. Review this page before starting work with the Car APIs.
A car booking on the Spotnana platform represents a car rental reservation made by the traveler, an arranger, or by an agent. Each booking is created through a workflow that searches for available cars, retrieves rate details and pickup context (when specified), verifies the price, and finally creates the booking.
The Car APIs are designed for car rentals (i.e., the traveler picks up the car, drives it themselves, and returns it). These APIs do not support taxi/cab, ride-hailing, or chauffeured (e.g., Black car) transport bookings. Chauffeured services are handled separately as black car bookings on the Spotnana Online Booking Tool.
Every car booking on Spotnana must be associated with a trip. When a new car booking is created, a unique pnrId is generated by Spotnana, and this PNR ID is linked to a trip using the tripId.
If the car booking is part of an existing trip (e.g., the traveler has already booked a flight or a hotel for the same trip), use the existing tripId when creating the booking. Otherwise, use the create trip API to create a new trip first.
To learn more about trips, see basic trip concepts.
The Car APIs use two terms that sound similar but mean very different things: rate details and rate information. Understanding the distinction between them is essential for working with the APIs correctly.
Rate details refers to the response from the get car rate details endpoint. It returns detailed information about a specific car (e.g., vendor information) selected by the traveler.
The get car rate details response includes:
| Field | Description |
|---|---|
pickupLocation and dropOffLocation | Full location details including address, coordinates, counter location type (in-terminal, off-airport shuttle, etc.), operating schedule, and contact info. |
vendor | The rental company's details (e.g., name, phone number, etc.). |
additionalDetails | Free-text descriptions including driver age requirements, fuel policy, drop-off restrictions, fees, geographic restrictions, insurance notes, and shuttle information. |
co2Emission | Sustainability data (i.e., the CO2 emission value for the rental in kilograms). |
isFlightNumberMandatoryForPickup | Indicates whether the traveler must provide their flight number when making a booking. |
checkoutApprovalInfo | Approval workflow details, including who needs to approve this booking and what type of approval is required. |
Rate information refers to the rateInfo field in the API response, which contains the actual price breakdown for a specific car offer. This rateInfo field is returned in the following API responses:
- For each offer in the car search response (under
cars>rateInfo). - On the car price check response.
Note: The car price check API response contains
rateInfoandfinalRateInfo. See rate difference components to learn more about their differences.
The rateInfo field contains:
| Field | Description |
|---|---|
carRateComponents | The rate is broken down into components such as base rate, taxes, mandatory charges, total price, and modification rate differences (when applicable). |
carExtras | Optional add-ons available with the rental, such as child seats, GPS, ski racks, or additional drivers. Pricing for each add-on is displayed in carExtras > amount. |
rateType | Indicates whether the rate is GUARANTEED (pay at the counter) or PREPAID (pay upfront when the booking is made). |
fareType | Indicates one of the following fare types:
|
refundable | Indicates whether the rate is refundable. |
dailyRates | Per-day rate breakdown across the rental duration. |
allowedPaymentTypes | The payment method types (e.g., card payment) that can be used to book this rate. |
Car rental search depends on where the traveler plans to pick up and return the car. The Car APIs model this with rich location data, since the practical difference between an in-terminal counter and an off-airport shuttle pickup can significantly affect a traveler's plans.
In the car search API request, the pickup and dropOff objects each contain a location and a datetime. The location can be specified in one of the following ways:
| Field | Description |
|---|---|
airportCode | The 3-letter IATA airport code (e.g., SFO, JFK). Returns rentals available at or near the specified airport. |
cityCode | The IATA city code. Returns rentals available within the specified city's IATA code. |
coordinates | Latitude and longitude coordinates. Returns rentals available near the specified geographic point. |
The pickup and drop-off locations can be the same (round-trip rentals) or different (one-way rentals). For one-way rentals, the vendor may charge a drop-off fee, which appears in the rate components as DROP_OFF_CHARGE.
The cars > pickupParams > pickupLocation > counterLocation field on the car search API response indicates how the traveler accesses the rental counter. This is important for trip planning because shuttle-based pickups can add extra time to the journey.
| Field | Description |
|---|---|
IN_TERMINAL | The counter is located inside the airport terminal. Travelers can walk directly from the gate to the counter. |
ON_AIRPORT_RENTAL_SHUTTLE | The counter is located on airport property but requires a rental-company shuttle from the terminal. |
OFF_AIRPORT_RENTAL_SHUTTLE | The counter is located off airport property and requires a shuttle. Travelers should expect additional travel time. |
ON_AIRPORT_AIRPORT_SHUTTLE | The counter is on airport property and is reached via the airport's own shuttle service. |
IN_TERMINAL_RENTAL_SHUTTLE | The counter is located inside the airport terminal but the cars themselves require a shuttle (provided by the rental company) to reach. |
TWO_SHUTTLES_AIRPORT_AND_RENTAL | The pickup requires two shuttle rides: one airport shuttle from the terminal to the car check-in counter followed by a second rental-company shuttle that takes you to the car location. |
CALL_FOR_SHUTTLE | The traveler must phone the vendor to arrange a shuttle pickup. |
NON_AIRPORT_LOCATION | The pickup is at a non-airport location (e.g., a downtown branch). The traveler must travel to this location from the airport on their own (e.g., using public transport or cab). |
Each location includes an operatingSchedule and a weeklyOperatingSchedule describing when the vendor is open. The operating schedule contains an interval with a start and end DateTimeLocal, and the weekly schedule provides per-day-of-week operating hours.
Travelers should be informed of operating hours in advance, especially for late-night arrivals or early-morning returns. If the traveler is arriving outside operating hours, the rental may not be possible without prior arrangement.
The pickupLocation > contactInfo object on the car search API provides arrays of phone numbers, fax numbers, email addresses, and emergency phone numbers for the vendor at that specific location. This information is useful for the traveler and should be kept accessible during the rental period.
Consider a traveler arriving at SFO airport. The search response might include:
- Vendor A with
counterLocation:IN_TERMINAL. The traveler walks straight to the counter from baggage claim. - Vendor B with
counterLocation:OFF_AIRPORT_RENTAL_SHUTTLE. The traveler must take a shuttle to reach the counter, adding 20 to 30 minutes travel time to their arrival.
Even if Vendor B's rate is cheaper, the in-terminal pickup may be preferable for travelers with tight schedules or heavy luggage. Displaying the counter location prominently in the user interface helps the traveler make an informed choice.