# Car search

Spotnana APIs provide car rental search functionality using the [get car search results](/openapi/carapi/car/carsearch) 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.

## Car search parameters

Using the [get car search results](/openapi/carapi/car/carsearch) 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](/openapi/usersapi/users/queryuser) 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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](/openapi/carapi/car/carsearch) API containing the search parameters:


```json 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"
}
```

## Car search filters

The `filters` field in the [get car search results](/openapi/carapi/car/carsearch) 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: * `PUBLISHED`: The retail rate set by the car vendor for all customers.
* `CORPORATE`: Rates negotiated by the company on behalf of their travelers.
* `SPOTNANA`: Rates negotiated by Spotnana on behalf of its customers.
* `TMC`: Rates negotiated by the TMC on behalf of their customer organizations.

 |


Here's a sample request payload showing several filters being used in combination:


```json 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"]
  }
}
```

## Sorting search results

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: * `PRICE`: Sorts the results by price. When combined with ascending order, the cheapest cars are listed first.
* `DISTANCE`: Sorts the results by the distance of the car pickup location from the search location. When combined with ascending order, the closest pickup locations are listed first.

 |
| `sortOrder` | The sort direction. Accepts `ASCENDING` or `DESCENDING`. |


Here's a sample request payload that sorts the results by price in ascending order:


```json POST /v2/car/search
// ... payload truncated for focus
{
  "sortOptions": {
    "sortBy": "PRICE",
    "sortOrder": "ASCENDING"
  }
}
```

## Combining search parameters, filters, and sorting

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):


```json 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"
  }
}
```

## Tips for refining search results

The following are some recommendations to refine the car search results:

- Setting `preferredOnly` to `true` displays 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 `citizenCountryCode` and `pickupCountryCode` for 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.