PistonTraders
Home / Developers / Vehicles API
Public API documentation

PistonTraders Vehicles API

Search live PistonTraders vehicle listings with a public, crawlable JSON API. This page is written for developers, search engines, and AI agents that need to turn natural-language vehicle requests into structured API calls.

Public API GET /api/v1/vehicles/ JSON response LLM-readable Paginated results
OpenAPI JSON API examples LLM guide

Overview

The Vehicles API lets clients search and filter live PistonTraders vehicle listings. It is designed for public read-only discovery by AI assistants, search tools, and developer integrations.

Base URL
https://www.pistontraders.co.uk
Endpoint
GET /api/v1/vehicles/
Authentication
Public read-only access
Response format
JSON

Endpoint

Use this endpoint to search vehicles by query text, structured filters, sorting, location, and pagination. 

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

Accept: application/json
This API is public for read-only vehicle search. AI agents should use this endpoint instead of scraping listing pages.

LLM discovery files

These canonical files help AI systems understand how to call the API and how to map natural-language vehicle searches to query parameters.

OpenAPI schema
https://www.pistontraders.co.uk/openapi.json
LLM index
https://www.pistontraders.co.uk/llms.txt
Examples
https://www.pistontraders.co.uk/developers/vehicles-api/examples/
LLM guide
https://www.pistontraders.co.uk/developers/vehicles-api/llm-guide/

Natural-language examples

These examples show how an AI assistant should convert user intent into API requests.

Cheap Ford Fiesta

User request: “Find me a cheap Ford Fiesta.”

GET https://www.pistontraders.co.uk/api/v1/vehicles/?make=Ford&model=Fiesta&sort=price_asc&page=1

Jaguar XJ, 2008 or older, under £10,000

User request: “Find me a pre-2008 Jaguar XJ for under 10k.”

GET https://www.pistontraders.co.uk/api/v1/vehicles/?make=Jaguar&model=XJ&year_max=2008&price_max=10000&sort=price_asc&page=1

Automatic diesel cars near a postcode

User request: “Find diesel automatic cars near SW1A 1AA.”

GET https://www.pistontraders.co.uk/api/v1/vehicles/?fuel_type=Diesel&transmission=Automatic&location=SW1A%201AA&distance=3&sort=distance&page=1

Query parameters

AI agents should prefer these structured parameters over broad text search when the user gives a clear make, model, price, year, mileage, transmission, fuel type, or location.

Parameter Type Example AI interpretation
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.

Response shape

The API returns a top-level results object containing vehicle listings and pagination metadata. 

{
  "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 agents should only present vehicles that appear in results.cars. Always include the listing URL from car.url when returning results to a user.

AI usage rules

These rules make the API safer and more reliable for AI assistants.

User says Use this API behaviour
“cheap” sort=price_asc
“newest” sort=year_desc
“low mileage” sort=miles_asc
“under £10k” price_max=10000
“2008 or older”, “pre-2008”, “no later than 2008” year_max=2008
“near me” or “near this postcode” location=<postcode> and usually sort=distance
“manual” or “automatic” transmission=Manual or transmission=Automatic