Spotnana APIs provide car rental search functionality using the get car search results endpoint. The endpoint accepts a combination of search parameters (e.g., pickup and drop-off locations, dates), filters (e.g., car type, price range, vendor), and sort options to refine the search results displayed.
Using the get car search results endpoint, you can search by providing the following parameters in the request:
| Field | Description |
|---|---|
pickup | The location, date, and time where and when the traveler will pick up the car. The pickup object contains location (which can be specified using airportCode, cityCode, or latitude and longitude coordinates), and datetime (the pickup date and time in ISO 8601 format). |
dropOff | The location, date, and time where and when the traveler will return the car. Has the same structure as pickup. The pickup and drop-off locations can be the same (round-trip rentals) or different (one-way rentals). |
userId | The Spotnana user identifier for the traveler. The userId can be retrieved using the query user API. |
renterAge | The age of the car rental driver. Some vendors may restrict rentals based on the renter's age (e.g., surcharge for underage or senior citizen drivers). While this field is optional, it is recommended to ensure you retrieve accurate pricing. |
citizenCountryCode | The 2-letter country code (in ISO 3166-1 alpha-2 format) of the car renter's citizenship. Used to apply citizenship-based rate rules or restrictions if applicable (e.g., a tourist surcharge). |
pickupCountryCode | The 2-letter country code (in ISO 3166-1 alpha-2 format) of the pickup location's country. Some rates and rules vary based on the pickup country. |
loyaltyCode | An array of loyalty codes (e.g., promotional coupons) to be applied to the search. Each entry includes a vendor code, a code value, and a type (currently only the type PROMOTIONAL_COUPON is supported). |
Here's a sample request for the get car search results API containing the search parameters:
POST /v2/car/search
// ... payload truncated for focus
{
"pickup": {
"location": {
"airportCode": "SFO"
},
"datetime": {
"iso8601": "2026-12-15T10:00"
}
},
"dropOff": {
"location": {
"airportCode": "SFO"
},
"datetime": {
"iso8601": "2026-12-20T10:00"
}
},
"userId": {
"userIdType": "USER_ID",
"userId": {
"id": "a90e38d1-7c9f-4b2a-8c8a-2c8c3e8f9e6a"
}
},
"renterAge": 30,
"citizenCountryCode": "US",
"pickupCountryCode": "US"
}The filters field in the get car search results API provides several optional filters that can be used to refine the car search results.
The most commonly used filters include:
| Field | Description |
|---|---|
carTypes | Filters cars by type (e.g., MINI, CONVERTIBLE, SUV, etc.). |
vendors | Filters cars by vendor code recognized by Global Distribution Systems (GDS) such as Sabre (e.g., ZE for Hertz). |
preferredOnly | When set to true, the results will only include cars from preferred vendors (as configured in the company policy). Defaults to false. |
price | Filters cars within a specific price range. The price object contains a min and max object (each with an amount and currencyCode). |
hasAirConditioning | When set to true, the results will only include cars that have air conditioning. Defaults to false. |
excludeTransmissions | Excludes cars with specific transmission types. Accepts MANUAL or AUTOMATIC. For example, set this to ["MANUAL"] to exclude manual transmission cars from the search results. |
engineTypes | Filters cars by engine type (e.g., PETROL, DIESEL, etc.). |
carExtraTypes | Filters cars based on available add-ons (e.g., CHILD_SEAT_INFANT, LUGGAGE_RACK, etc.). |
numPassengers | Filters cars by the seating capacity (i.e., the maximum number of passengers the car can hold). |
paymentTypes | Filters cars based on which payment method types can be used to make the booking (e.g., CARD, DELAYED_INVOICING, CASH, etc.). |
fareTypes | Filters cars based on the fare type. The following values are supported:
|
Here's a sample request payload showing several filters being used in combination:
POST /v2/car/search
// ... payload truncated for focus
{
"filters": {
"carTypes": ["ECONOMY", "COMPACT", "MID_SIZE"],
"vendors": ["ZI", "ZE"],
"preferredOnly": true,
"hasAirConditioning": true,
"excludeTransmissions": ["MANUAL"],
"engineTypes": ["PETROL", "HYBRID"],
"carExtraTypes": ["CHILD_SEAT_TODDLER", "NAVIGATIONAL_SYSTEM"],
"price": {
"min": {
"amount": 30,
"currencyCode": "USD"
},
"max": {
"amount": 100,
"currencyCode": "USD"
}
},
"numPassengers": {
"min": 2,
"max": 5
},
"fareTypes": ["CORPORATE", "SPOTNANA"]
}
}Use the sortOptions field to sort the search results returned. The sort options control both the field used for sorting and the direction (ascending or descending).
| Field | Description |
|---|---|
sortBy | The field to sort the results by. Accepts the following values:
|
sortOrder | The sort direction. Accepts ASCENDING or DESCENDING. |
Here's a sample request payload that sorts the results by price in ascending order:
POST /v2/car/search
// ... payload truncated for focus
{
"sortOptions": {
"sortBy": "PRICE",
"sortOrder": "ASCENDING"
}
}All three options (search parameters, filters, and sort options) can be used together in a single request. Here's a complete sample payload that searches for compact and mid-size hybrid cars under USD 80 per day, from preferred vendors at SFO airport, sorted by price (lowest first):
POST /v2/car/search
{
"pickup": {
"location": {
"airportCode": "SFO"
},
"datetime": {
"iso8601": "2026-12-15T10:00"
}
},
"dropOff": {
"location": {
"airportCode": "SFO"
},
"datetime": {
"iso8601": "2026-12-20T10:00"
}
},
"userId": {
"userIdType": "USER_ID",
"userId": {
"id": "a90e38d1-7c9f-4b2a-8c8a-2c8c3e8f9e6a"
}
},
"renterAge": 30,
"citizenCountryCode": "US",
"pickupCountryCode": "US",
"filters": {
"carTypes": ["COMPACT", "MID_SIZE"],
"engineTypes": ["HYBRID"],
"preferredOnly": true,
"hasAirConditioning": true,
"price": {
"max": {
"amount": 80,
"currencyCode": "USD"
}
}
},
"sortOptions": {
"sortBy": "PRICE",
"sortOrder": "ASCENDING"
}
}The following are some recommendations to refine the car search results:
- Setting
preferredOnlytotruedisplays only the vendors that the organization has set as preferred in their policy configuration. This is useful for guiding travelers toward in-policy bookings. - Use
citizenCountryCodeandpickupCountryCodefor cross-border rentals. Several rate rules and surcharges apply based on whether the renter and the pickup location are in the same country. Always pass these fields when known.