PistonTraders
Home / Developers / Vehicles API / Schema
Public API schema

Vehicles API Schema

Human-readable schema details for the public PistonTraders Vehicles API, paired with the canonical machine-readable OpenAPI file for developers, crawlers, and AI agents.

Public read-only API GET /api/v1/vehicles/ JSON schema AI-readable
OpenAPI JSON Well-known OpenAPI Examples

Schema summary

The Vehicles API returns paginated JSON results for live vehicle listings. It is public and read-only, so no API key, bearer token, or authentication header is required.

Method
GET
Endpoint
/api/v1/vehicles/
Authentication
None required
Content type
application/json

Canonical request

All filters are supplied as query parameters. Parameters are optional and can be combined. 

GET https://www.pistontraders.co.uk/api/v1/vehicles/

Accept: application/json
AI agents should use this endpoint directly for read-only vehicle search and should not scrape listing pages.

Request parameters

All parameters are optional. Range filters such as year_max, price_max, and miles_max exclude listings where that attribute is unavailable.

Name Type Example Description
q string ford fiesta Full-text vehicle search query.
make string Jaguar Manufacturer name, e.g. Ford, Jaguar, Volkswagen.
model string XJ Vehicle model name.
fuel_type string Diesel Allowed values: Petrol, Diesel, Hybrid, Electric.
transmission string Automatic Allowed values: Manual, Automatic.
dealer string dealer1.co.uk,dealer2.co.uk Comma-separated dealer domains.
price_min integer 5000 Minimum price in GBP.
price_max integer 10000 Maximum price in GBP.
miles_min integer 0 Minimum odometer mileage. Excludes listings where mileage is unavailable.
miles_max integer 80000 Maximum odometer mileage. Excludes listings where mileage is unavailable.
year_min integer 2015 Minimum manufacture year. Excludes listings where year is unavailable.
year_max integer 2008 Maximum manufacture year. Use this for searches like 'pre-2008' or 'no later than 2008'.
engine_min number 1.2 Minimum engine size in litres. Excludes listings where engine size is unavailable.
engine_max number 2.0 Maximum engine size in litres. Excludes listings where engine size is unavailable.
location string SW1A 1AA Postcode used as the origin for distance calculations.
distance integer 3 Distance band: 0=1km, 1=5km, 2=10km, 3=25km, 4=50km, 5=100km, 6=unlimited.
sort string price_asc Allowed values: relevance, price_asc, price_desc, year_desc, miles_asc, distance.
page integer 1 Page number, 1-indexed.

Vehicle object

Each item in results.cars represents one vehicle listing. AI agents should use car.url as the canonical listing URL when presenting results.

Field Type Description
results object Container for cars and pagination metadata.
results.cars array Vehicle listings for the requested page.
results.total_vehicles integer Total listings matching the supplied filters.
results.current_page integer Current page number, 1-indexed.
results.total_pages integer Total pages available.
results.per_page integer Number of results per page.
car.year string | null Vehicle year.
car.make string | null Manufacturer.
car.model string | null Model name.
car.mileage integer | null Mileage in miles.
car.fuel_type string | null Fuel type.
car.transmission string | null Transmission.
car.engine_size number | null Engine capacity in litres.
car.price number | null Price in GBP.
car.dealer string | null Dealer identifier/domain.
car.url string Redirect URL for the listing.
car.loc string | null General location text.
car.thumbnail string | null Thumbnail image URL.
car.images array Image URLs.
car.full_description string | null Full listing description.
car.distance_km number | null Distance from supplied location, when available.

Example response

The primary result array is results.cars. Pagination metadata appears alongside it. 

{
  "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
  }
}

AI parsing guidance

These notes make the schema easier for LLMs and agent tools to use correctly.

Requirement Guidance
Authentication No API key or bearer token is required for public read-only search.
Vehicle results Only present listings that appear in results.cars.
Listing link Use car.url as the canonical link to the vehicle.
Pagination Use results.current_page, results.total_pages, and page to retrieve more results.
Unavailable data Vehicle fields may be null. Do not invent missing mileage, fuel type, price, images, or location.
Range filters Using range filters excludes listings where the filtered field is unavailable.