PistonTraders
Home / Developers / Vehicles API
Public API documentation

docs

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

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