{
  "openapi": "3.0.3",
  "info": {
    "title": "CheapCarRent public search",
    "version": "2026-11-14",
    "description": "Read-only search of the same city preview the website shows. No booking, payment, account, or personal data. CORS: GET, HEAD and OPTIONS preflight are allowed from any origin without cookies or credentials (Access-Control-Allow-Origin: *). The response is cached for about 10 seconds on top of the city preview, which itself keeps supplier answers for up to 6 hours; meta.pricesCheckedAt says when the suppliers were last asked. Prices come from the existing city preview and are not a guaranteed quote. Pickup must be within 365 days from today and a rental can be up to 30 days. Speed: the first search for a city and a pair of dates asks the suppliers live and can take 3 to 15 seconds; a repeat answers in under a second. Limit: 60 requests a minute and 12 in 10 seconds from one IP, reported in X-RateLimit-Limit and X-RateLimit-Remaining. Accepted cities and airports: /api/v1/public/locations. A supplier that fails is skipped; the offers that succeeded are returned. Examples below are placeholders, not live or official prices. Selection: cars only (no scooters, quads or boats), a believable day price of 5 to 500 EUR, one offer per company, car and price, sorted by priceEur and then cut to the page; meta.count counts this selection.",
    "contact": {
      "name": "CheapCarRent",
      "email": "info@cheapcarent.com"
    }
  },
  "servers": [
    {
      "url": "https://cheapcarent.com",
      "description": "Website. Requests under /api are proxied to the rental API."
    }
  ],
  "paths": {
    "/api/v1/public/search": {
      "get": {
        "operationId": "publicSearch",
        "summary": "Search live rental offers for a place and dates.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/pickup"
          },
          {
            "$ref": "#/components/parameters/country"
          },
          {
            "$ref": "#/components/parameters/city"
          },
          {
            "$ref": "#/components/parameters/iata"
          },
          {
            "$ref": "#/components/parameters/pickupDate"
          },
          {
            "$ref": "#/components/parameters/pickupTime"
          },
          {
            "$ref": "#/components/parameters/returnDate"
          },
          {
            "$ref": "#/components/parameters/returnTime"
          },
          {
            "$ref": "#/components/parameters/driverAge"
          },
          {
            "$ref": "#/components/parameters/currency"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Offers from the city preview. Empty data means no supplier answered. This is not an error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "examples": {
                  "sample": {
                    "summary": "Placeholder sample, not a live price",
                    "value": {
                      "data": [
                        {
                          "brand": "Sample",
                          "model": "Car",
                          "category": "economy",
                          "transmission": "manual",
                          "seats": 5,
                          "company": "Sample Supplier",
                          "price": 10,
                          "priceEur": 10,
                          "totalPrice": 30,
                          "currency": "EUR",
                          "pickupLocation": "Sample Airport",
                          "deposit": {
                            "amount": 100,
                            "currency": "EUR"
                          },
                          "fuelPolicy": "full_to_full",
                          "mileage": {
                            "unlimited": true
                          },
                          "url": "https://cheapcarent.com/car-rental/es/sample"
                        }
                      ],
                      "meta": {
                        "count": 1,
                        "returned": 1,
                        "limit": 8,
                        "offset": 0,
                        "currency": "EUR",
                        "pricesCheckedAt": "2026-11-13T09:00:00+00:00",
                        "pickupDate": "2026-12-01",
                        "returnDate": "2026-12-04",
                        "pickupTime": "12:00",
                        "returnTime": "12:00",
                        "location": {
                          "city": "Sample",
                          "country": "Sampleland",
                          "countryCode": "ES",
                          "iata": "SMP",
                          "page": "https://cheapcarent.com/car-rental/es/sample"
                        },
                        "disclaimer": "The live price is on the CheapCarRent website. Cancellation depends on the specific offer.",
                        "x-sample": true
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "Unknown or ambiguous place. The accepted cities and airports are listed at /api/v1/public/locations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Only GET, HEAD and OPTIONS are accepted. The refusal is JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 requests in a minute, or more than 12 in 10 seconds, from one IP.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "head": {
        "operationId": "publicSearchHead",
        "summary": "Headers for the same search, without a body.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/pickup"
          },
          {
            "$ref": "#/components/parameters/country"
          },
          {
            "$ref": "#/components/parameters/city"
          },
          {
            "$ref": "#/components/parameters/iata"
          },
          {
            "$ref": "#/components/parameters/pickupDate"
          },
          {
            "$ref": "#/components/parameters/returnDate"
          }
        ],
        "responses": {
          "200": {
            "description": "Same status and headers as GET, with an empty body."
          },
          "400": {
            "description": "Invalid query."
          },
          "404": {
            "description": "Unknown location."
          },
          "429": {
            "description": "Rate limit."
          },
          "503": {
            "description": "Search temporarily unavailable."
          }
        }
      }
    },
    "/api/v1/public/locations": {
      "get": {
        "operationId": "publicLocations",
        "summary": "Cities and airports the search accepts, with the exact spelling to use.",
        "description": "Read from the list of published city pages; no supplier is called, so it answers fast. Search with country=countryCode and city=cityParam, or with iata. Cached for 10 minutes.",
        "security": [],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Two-letter country code to list one country only.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2,
              "example": "ES"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Every published city, sorted by country and city.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationsResponse"
                },
                "examples": {
                  "sample": {
                    "summary": "Placeholder sample row",
                    "value": {
                      "data": [
                        {
                          "country": "Morocco",
                          "countryCode": "MA",
                          "city": "Marrakesh",
                          "cityParam": "marrakesh",
                          "iata": "RAK",
                          "hasAirport": true,
                          "alsoAccepted": [
                            "marrakech"
                          ],
                          "page": "https://cheapcarent.com/car-rental/ma/marrakesh"
                        }
                      ],
                      "meta": {
                        "count": 1,
                        "airports": 1,
                        "countries": 1,
                        "search": "https://cheapcarent.com/api/v1/public/search",
                        "usage": "Search with country=countryCode and city=cityParam, or with iata."
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "405": {
            "description": "Only GET, HEAD and OPTIONS are accepted. The refusal is JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Same limit as the search: 60 requests a minute and 12 in 10 seconds from one IP, counted together with search requests.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "head": {
        "operationId": "publicLocationsHead",
        "summary": "Headers for the same list, without a body.",
        "security": [],
        "responses": {
          "200": {
            "description": "Same status and headers as GET, with an empty body."
          },
          "429": {
            "description": "Rate limit."
          },
          "503": {
            "description": "The list is temporarily unavailable."
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "pickup": {
        "name": "pickup",
        "in": "query",
        "required": false,
        "description": "Place name, optionally \"City, Country\". Use this or country+city or iata.",
        "schema": {
          "type": "string",
          "maxLength": 120
        }
      },
      "country": {
        "name": "country",
        "in": "query",
        "required": false,
        "description": "Two-letter country code. Must be sent with city.",
        "schema": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2,
          "example": "ES"
        }
      },
      "city": {
        "name": "city",
        "in": "query",
        "required": false,
        "description": "City slug used on /car-rental/{country}/{city}, such as barcelona.",
        "schema": {
          "type": "string",
          "example": "barcelona"
        }
      },
      "iata": {
        "name": "iata",
        "in": "query",
        "required": false,
        "description": "Airport code stored on the city. There is no separate airport page yet.",
        "schema": {
          "type": "string",
          "minLength": 3,
          "maxLength": 3,
          "example": "BCN"
        }
      },
      "pickupDate": {
        "name": "pickup_date",
        "in": "query",
        "required": true,
        "description": "Today or later, and within 365 days from today.",
        "schema": {
          "type": "string",
          "format": "date"
        }
      },
      "pickupTime": {
        "name": "pickup_time",
        "in": "query",
        "required": false,
        "description": "Optional. Only 12:00 is accepted, because that is the city preview window.",
        "schema": {
          "type": "string",
          "example": "12:00"
        }
      },
      "returnDate": {
        "name": "return_date",
        "in": "query",
        "required": true,
        "description": "After pickup_date, and no more than 30 days after it.",
        "schema": {
          "type": "string",
          "format": "date"
        }
      },
      "returnTime": {
        "name": "return_time",
        "in": "query",
        "required": false,
        "description": "Optional. Only 12:00 is accepted, because that is the city preview window.",
        "schema": {
          "type": "string",
          "example": "12:00"
        }
      },
      "driverAge": {
        "name": "driver_age",
        "in": "query",
        "required": false,
        "description": "Optional whole number from 18 to 99. The city preview does not change the returned price by driver age.",
        "schema": {
          "type": "integer",
          "minimum": 18,
          "maximum": 99
        }
      },
      "currency": {
        "name": "currency",
        "in": "query",
        "required": false,
        "description": "Defaults to EUR. Other currencies are rejected; this endpoint does not invent a conversion.",
        "schema": {
          "type": "string",
          "enum": [
            "EUR"
          ]
        }
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Page size, 1 to 8. The city preview keeps at most 8 vehicles, so a search never returns more.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 8,
          "default": 8
        }
      },
      "offset": {
        "name": "offset",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 1000,
          "default": 0
        }
      }
    },
    "responses": {
      "Error": {
        "description": "The query was rejected or the place is unknown. The body has no stack trace.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unavailable": {
        "description": "The search could not be completed. A single supplier timeout does not use this status when other offers exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "status"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Offer"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "Offer": {
        "type": "object",
        "description": "Fields are copied only when the city preview already has them. Prices in the example are samples.",
        "properties": {
          "brand": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "transmission": {
            "type": "string"
          },
          "fuel": {
            "type": "string"
          },
          "seats": {
            "type": "integer"
          },
          "company": {
            "type": "string",
            "description": "Supplier name when the preview has one."
          },
          "price": {
            "type": "number",
            "description": "Per day, in the offer's own currency field, which is not always EUR. Sample figures are not offers."
          },
          "totalPrice": {
            "type": "number",
            "description": "Whole rental, in the offer's own currency field."
          },
          "rentalPrice": {
            "type": "number",
            "description": "Per day without delivery, in the offer's own currency field."
          },
          "delivery": {
            "type": "number",
            "description": "Delivery charge, in the offer's own currency field."
          },
          "priceEur": {
            "type": "number",
            "description": "The offer's own day price converted to EUR at the ECB rate, delivery included (equal to price when the offer is in EUR). Offers are sorted by it, cheapest first."
          },
          "currency": {
            "type": "string"
          },
          "pickupLocation": {
            "type": "string"
          },
          "deposit": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string"
              }
            }
          },
          "fuelPolicy": {
            "type": "string"
          },
          "mileage": {
            "type": "object"
          },
          "photo": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Website offer or city page. Not a booking token."
          }
        }
      },
      "LocationsResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Location"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer"
              },
              "airports": {
                "type": "integer"
              },
              "countries": {
                "type": "integer"
              },
              "search": {
                "type": "string"
              },
              "usage": {
                "type": "string"
              }
            }
          }
        }
      },
      "Location": {
        "type": "object",
        "required": [
          "country",
          "countryCode",
          "city",
          "cityParam",
          "hasAirport",
          "page"
        ],
        "properties": {
          "country": {
            "type": "string"
          },
          "countryCode": {
            "type": "string",
            "description": "Value for the country parameter of the search."
          },
          "city": {
            "type": "string",
            "description": "Display name. It can carry accents."
          },
          "cityParam": {
            "type": "string",
            "description": "Value for the city parameter of the search."
          },
          "iata": {
            "type": "string",
            "description": "Airport code stored on the city, when there is one. A few neighbouring cities share a code; a search by that code answers for the city with more pickup points."
          },
          "hasAirport": {
            "type": "boolean"
          },
          "alsoAccepted": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Other spellings the search accepts for this city."
          },
          "page": {
            "type": "string",
            "description": "The public city page."
          }
        }
      },
      "Meta": {
        "type": "object",
        "required": [
          "currency",
          "disclaimer",
          "currencies",
          "priceEurCurrency"
        ],
        "properties": {
          "count": {
            "type": "integer"
          },
          "returned": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "The currency of price and totalPrice when every offer in the result uses the same one (for example USD in Santiago); null when currencies are mixed (EUR and CAD in Toronto). Never assume EUR: read each offer's currency, or use priceEur."
          },
          "pricesCheckedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the city preview last asked the suppliers. It can be up to 6 hours old. Absent when there are no offers."
          },
          "pickupDate": {
            "type": "string"
          },
          "returnDate": {
            "type": "string"
          },
          "pickupTime": {
            "type": "string"
          },
          "returnTime": {
            "type": "string"
          },
          "location": {
            "type": "object"
          },
          "disclaimer": {
            "type": "string"
          },
          "currencies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every currency of price and totalPrice in the result, sorted."
          },
          "priceEurCurrency": {
            "type": "string",
            "enum": [
              "EUR"
            ],
            "description": "priceEur is always in EUR."
          }
        }
      }
    }
  }
}
