{
  "openapi": "3.1.0",
  "info": {
    "title": "PistonTraders Vehicles API",
    "version": "1.0.0",
    "description": "Search and filter PistonTraders vehicle listings by full-text query, make, model, fuel type, transmission, dealer, price, mileage, year, engine size, location, distance, sort order, and page."
  },
  "servers": [
    {
      "url": "https://www.pistontraders.co.uk"
    }
  ],
  "paths": {
    "/api/v1/vehicles/": {
      "get": {
        "operationId": "searchVehicles",
        "summary": "Search vehicle listings",
        "description": "Fetch vehicle listings matching the supplied filters.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Full-text vehicle search query.",
            "example": "ford fiesta"
          },
          {
            "name": "make",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Manufacturer name, e.g. Ford, Jaguar, Volkswagen.",
            "example": "Jaguar"
          },
          {
            "name": "model",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Vehicle model name.",
            "example": "XJ"
          },
          {
            "name": "fuel_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Petrol",
                "Diesel",
                "Hybrid",
                "Electric"
              ]
            },
            "description": "Allowed values: Petrol, Diesel, Hybrid, Electric.",
            "example": "Diesel"
          },
          {
            "name": "transmission",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Manual",
                "Automatic"
              ]
            },
            "description": "Allowed values: Manual, Automatic.",
            "example": "Automatic"
          },
          {
            "name": "dealer",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated dealer domains.",
            "example": "dealer1.co.uk,dealer2.co.uk"
          },
          {
            "name": "price_min",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Minimum price in GBP.",
            "example": "5000"
          },
          {
            "name": "price_max",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Maximum price in GBP.",
            "example": "10000"
          },
          {
            "name": "miles_min",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Minimum odometer mileage. Excludes listings where mileage is unavailable.",
            "example": "0"
          },
          {
            "name": "miles_max",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Maximum odometer mileage. Excludes listings where mileage is unavailable.",
            "example": "80000"
          },
          {
            "name": "year_min",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Minimum manufacture year. Excludes listings where year is unavailable.",
            "example": "2015"
          },
          {
            "name": "year_max",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Maximum manufacture year. Use this for searches like 'pre-2008' or 'no later than 2008'.",
            "example": "2008"
          },
          {
            "name": "engine_min",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Minimum engine size in litres. Excludes listings where engine size is unavailable.",
            "example": "1.2"
          },
          {
            "name": "engine_max",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Maximum engine size in litres. Excludes listings where engine size is unavailable.",
            "example": "2.0"
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Postcode used as the origin for distance calculations.",
            "example": "SW1A 1AA"
          },
          {
            "name": "distance",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Distance band: 0=1km, 1=5km, 2=10km, 3=25km, 4=50km, 5=100km, 6=unlimited.",
            "example": "3"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "relevance",
                "price_asc",
                "price_desc",
                "year_desc",
                "miles_asc",
                "distance"
              ]
            },
            "description": "Allowed values: relevance, price_asc, price_desc, year_desc, miles_asc, distance.",
            "example": "price_asc"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Page number, 1-indexed.",
            "example": "1"
          }
        ],
        "responses": {
          "200": {
            "description": "Vehicle search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VehicleSearchResponse"
                },
                "examples": {
                  "JaguarXJPre2008Under10k": {
                    "summary": "Jaguar XJ, 2008 or older, under \u00a310k",
                    "value": {
                      "results": {
                        "cars": [
                          {
                            "year": "2007",
                            "make": "jaguar",
                            "model": "XJ",
                            "mileage": 92500,
                            "fuel_type": "Diesel",
                            "transmission": "automatic",
                            "engine_size": 2.7,
                            "price": 6450.0,
                            "dealer": "exampledealer.co.uk",
                            "url": "https://www.pistontraders.co.uk/cars/redirect/?api_target=...",
                            "loc": "Derbyshire",
                            "thumbnail": "https://example.com/car.jpg",
                            "images": [
                              "https://example.com/car.jpg"
                            ],
                            "full_description": "Example listing description.",
                            "distance_km": null
                          }
                        ],
                        "total_vehicles": 1,
                        "current_page": 1,
                        "total_pages": 1,
                        "per_page": 20
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter type or value."
          },
          "401": {
            "description": "Missing or invalid bearer token."
          },
          "403": {
            "description": "API key is valid but not permitted for this resource."
          },
          "429": {
            "description": "Rate limit exceeded, if rate limits are enforced."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "VehicleSearchResponse": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "object",
            "required": [
              "cars",
              "total_vehicles",
              "current_page",
              "total_pages",
              "per_page"
            ],
            "properties": {
              "cars": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Vehicle"
                }
              },
              "total_vehicles": {
                "type": "integer"
              },
              "current_page": {
                "type": "integer"
              },
              "total_pages": {
                "type": "integer"
              },
              "per_page": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Vehicle": {
        "type": "object",
        "properties": {
          "year": {
            "type": [
              "string",
              "null"
            ]
          },
          "make": {
            "type": [
              "string",
              "null"
            ]
          },
          "model": {
            "type": [
              "string",
              "null"
            ]
          },
          "mileage": {
            "type": [
              "integer",
              "null"
            ]
          },
          "fuel_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "transmission": {
            "type": [
              "string",
              "null"
            ]
          },
          "engine_size": {
            "type": [
              "number",
              "null"
            ]
          },
          "price": {
            "type": [
              "number",
              "null"
            ]
          },
          "dealer": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "loc": {
            "type": [
              "string",
              "null"
            ]
          },
          "thumbnail": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "full_description": {
            "type": [
              "string",
              "null"
            ]
          },
          "distance_km": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      }
    }
  }
}