# DiscoverCars API — compare rental-car offers & prices from 35+ suppliers across 145 countries, with location resolver, supplier comparison & reviews

> aggregated rental-car offers for a location + dates → offers[]{vehicle(name/category/ACRISS/transmission/seats/bags/fuel), price{amount,currency}, supplier(name/rating/pickup_address/coords), pickup.type, mileage, fuel_policy, free_cancellation, book_url} + facets. Location via `query` OR explicit place_id/city_id/country_id. One-way via drop_query. Dates pickup_date/dropoff_date (YYYY-MM-DD). Narrow with category/supplier/transmission/max_price/min_supplier_rating/free_cancellation_only filters + sort.
> ReefAPI engine `discovercars` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## Measured
- DiscoverCars API, measured on live customer calls 17 Oct – 16 Nov 2026: 99.2% of calls succeeded, median response 4.6 s. Failures count only when the problem is ours (blocked, source error, parse error, timeout); not-found results and invalid parameters are not failures.
- OpenAPI 3.0 spec for this API: https://api.reefapi.com/openapi/discovercars.json

## How to call
- **Endpoint:** `POST https://api.reefapi.com/discovercars/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/discovercars/v1/cars/search — 2 credits
aggregated rental-car offers for a location + dates → offers[]{vehicle(name/category/ACRISS/transmission/seats/bags/fuel), price{amount,currency}, supplier(name/rating/pickup_address/coords), pickup.type, mileage, fuel_policy, free_cancellation, book_url} + facets. Location via `query` OR explicit place_id/city_id/country_id. One-way via drop_query. Dates pickup_date/dropoff_date (YYYY-MM-DD). Narrow with category/supplier/transmission/max_price/min_supplier_rating/free_cancellation_only filters + sort.

**Parameters:**
- `query` (string, optional) — Pickup location to resolve (city / airport name, or an IATA code such as NCE or 'Nice Airport (NCE)'). The best whole-word / code match wins; data.location_resolution shows which place was used and the runners-up. Provide this OR an explicit place_id + city_id + country_id.
- `place_id` (string, optional) — Explicit DiscoverCars place id (from cars/autocomplete). Use together with city_id + country_id to skip resolution.
- `city_id` (string, optional) — Explicit DiscoverCars city id (pairs with place_id + country_id).
- `country_id` (string, optional) — Explicit DiscoverCars country id (pairs with place_id + city_id).
- `pickup_date` (string, optional) — Pickup date (YYYY-MM-DD). Defaults to ~30 days out if omitted.
- `dropoff_date` (string, optional) — Drop-off date (YYYY-MM-DD). Defaults to ~30 days out if omitted.
- `pickup_time` (string, optional, default "10:00") — Pickup time of day (HH:MM, 24h). Default 10:00.
- `dropoff_time` (string, optional, default "10:00") — Drop-off time of day (HH:MM, 24h). Default 10:00.
- `currency` (string, optional, default "EUR") — ISO-4217 currency for prices (e.g. EUR, USD, GBP). Default EUR.
- `residence_country` (string, optional, default "US") — Driver's country of residence (ISO-2, e.g. US, GB) — affects pricing/availability. Default US.
- `driver_age` (integer, optional, default 35) — Driver age (affects young/senior-driver fees). Default 35.
- `drop_query` (string, optional) — Different drop-off location (city/airport name) for a one-way rental. Omit for same-location return.
- `drop_place_id` (string, optional) — Explicit drop-off place id (one-way; pairs with drop_city_id).
- `drop_city_id` (string, optional) — Explicit drop-off city id (one-way).
- `drop_country_id` (string, optional) — Explicit drop-off country id (one-way).
- `max_offers` (integer, optional) — Cap the number of offers returned. Omit for all.
- `include_facets` (boolean, optional, default true) — Include aggregation facets (supplier/category/price buckets) in the response. Default true.
- `prefer_airport` (boolean, optional, default true) — When resolving `query` and `drop_query`, prefer the airport location. false picks the city-wide '(all locations)' or downtown entry instead. Default true.
- `category` (string, optional) — Filter by vehicle category substring (case-insensitive), e.g. Mini, Economy, Compact, Intermediate, SUV, Luxury, Van. From facets.carGroups.
- `supplier` (string, optional) — Filter by supplier name substring (case-insensitive), e.g. Avis, Hertz, Sixt, Budget, Enterprise. See the `suppliers` rollup for what's available.
- `transmission` (enum, optional) — Filter by transmission. One of: automatic, manual. [one of: automatic, manual]
- `min_seats` (integer, optional) — Only offers with at least this many seats.
- `max_price` (number, optional) — Only offers whose TOTAL rental price is at or below this (in `currency`).
- `min_supplier_rating` (number, optional) — Only suppliers rated at or above this score (0-10 scale).
- `free_cancellation_only` (boolean, optional, default false) — Only offers with free cancellation. Default false.
- `unlimited_mileage_only` (boolean, optional, default false) — Only offers with unlimited mileage. Default false.
- `sort` (enum, optional, default "price_asc") — Sort order. One of: price_asc (default, cheapest first), price_desc, rating_desc (best-rated supplier first). [one of: price_asc, price_desc, rating_desc]
- `include_supplier_summary` (boolean, optional, default true) — Include a per-supplier rollup (cheapest price, offer count, rating) in the response. Default true.

**Returns:** offers[]{vehicle{name,category,ACRISS,transmission,seats,bags,fuel}, price{amount,currency,daily,rental_days}, supplier{name,rating,pickup_address,coords}, pickup.type, mileage, fuel_policy, free_cancellation, book_url} + suppliers[] (per-supplier cheapest/count/rating), price_range, total_available, facets, pickup_location, dropoff_location, location_resolution{pickup,dropoff}{query, matched_by, autocomplete_probe, label, place_id, city_id, country_id, alternatives[]}, notice (only when DiscoverCars returned no offers), one_way, guid, search_url

**Example request body:**
```json
{
  "query": "Madrid Airport",
  "currency": "EUR",
  "pickup_date": "2027-01-03",
  "dropoff_date": "2027-01-06",
  "max_offers": 40
}
```

### POST https://api.reefapi.com/discovercars/v1/cars/autocomplete — 1 credit
resolve a location string (`query`) → place/city/country IDs (for cars/search)

**Parameters:**
- `query` (string, required) — Location string to resolve into place/city/country IDs.

**Returns:** results[]{place_id, city_id, country_id, label, is_airport} (DiscoverCars' own order), best_match{... , matched_by} (the row cars/search picks for this text), count, query

**Example request body:**
```json
{
  "query": "London"
}
```

### POST https://api.reefapi.com/discovercars/v1/cars/reviews — 1 credit
DiscoverCars customer reviews for a location → reviews[]{rating(0-10), text, author, author_country, car_name, date, photos} + average_rating + count. Location via `query` (city/country name; resolved automatically) OR explicit location_url. Filter with min_rating / with_text_only; country_only widens city→country scope.

**Parameters:**
- `query` (string, optional) — Location (city or country name) to fetch DiscoverCars customer reviews for. Provide this OR an explicit location_url.
- `location_url` (string, optional) — Explicit DiscoverCars review slug `country/city` (or `country`), e.g. spain/madrid, usa-california/los-angeles. Skips query resolution.
- `country_only` (boolean, optional, default false) — Fetch country-wide reviews instead of city-level. Default false (city-level, auto-falls back to country if the city has none).
- `min_rating` (integer, optional) — Only reviews rated at or above this (0-10 scale).
- `with_text_only` (boolean, optional, default false) — Only reviews that include written text. Default false.
- `max_reviews` (integer, optional) — Cap the number of reviews returned. Omit for all (~up to 50 most recent).

**Returns:** reviews[]{review_id, date, rating, text, author, author_country, car_name, photos, helpful_votes}, count, average_rating, location{country,city,location_url}, query

**Example request body:**
```json
{
  "query": "Madrid"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=discovercars
- Human docs page: https://reefapi.com/docs/discovercars
- Overview page: https://reefapi.com/discovercars-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
