Public API examples

Vehicles API Examples

Copy-paste examples showing how natural-language vehicle searches map to public PistonTraders API requests. These examples are written for developers, search engines, and AI agents.

Public read-only API Copy-paste requests LLM training examples JSON response

How to use these examples

Each example starts with a natural-language user request, then shows the API URL an AI agent or developer should call. No API key or bearer token is required for public read-only search.

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

Natural-language search examples

These examples are deliberately written in language an LLM can learn from: user intent first, structured API request second.

Cheap Ford Fiesta

User request: “Find me a cheap Ford Fiesta”

API request:

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

cURL:

curl -X GET "https://www.pistontraders.co.uk/api/v1/vehicles/?make=Ford&model=Fiesta&sort=price_asc&page=1" \
  -H "Accept: application/json"

Parameters:

{'make': 'Ford', 'model': 'Fiesta', 'sort': 'price_asc', 'page': 1}

Jaguar XJ, 2008 or older, under £10k

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

API request:

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

cURL:

curl -X GET "https://www.pistontraders.co.uk/api/v1/vehicles/?make=Jaguar&model=XJ&year_max=2008&price_max=10000&sort=price_asc&page=1" \
  -H "Accept: application/json"

Parameters:

{'make': 'Jaguar', 'model': 'XJ', 'year_max': 2008, 'price_max': 10000, 'sort': 'price_asc', 'page': 1}

Diesel automatic cars near London

User request: “Find diesel automatic cars within 25km of SW1A 1AA”

API request:

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

cURL:

curl -X GET "https://www.pistontraders.co.uk/api/v1/vehicles/?fuel_type=Diesel&transmission=Automatic&location=SW1A%201AA&distance=3&sort=distance&page=1" \
  -H "Accept: application/json"

Parameters:

{'fuel_type': 'Diesel', 'transmission': 'Automatic', 'location': 'SW1A 1AA', 'distance': 3, 'sort': 'distance', 'page': 1}

Minimal JavaScript example

Use a normal public fetch request. The API response contains listings in results.cars.

const url = new URL("https://www.pistontraders.co.uk/api/v1/vehicles/");

url.searchParams.set("make", "Jaguar");
url.searchParams.set("model", "XJ");
url.searchParams.set("year_max", "2008");
url.searchParams.set("price_max", "10000");
url.searchParams.set("sort", "price_asc");
url.searchParams.set("page", "1");

const response = await fetch(url, {
  headers: {
    "Accept": "application/json"
  }
});

const data = await response.json();

for (const car of data.results.cars) {
  console.log(car.year, car.make, car.model, car.price, car.url);
}

AI mapping examples

These are the most important translations for AI assistants.

User phrase API parameters Reason
“cheap Ford Fiesta” make=Ford&model=Fiesta&sort=price_asc Use structured make/model filters and sort by lowest price.
“pre-2008 Jaguar XJ under 10k” make=Jaguar&model=XJ&year_max=2008&price_max=10000 Use year and price maximum filters instead of broad text search.
“low mileage Golf” make=Volkswagen&model=Golf&sort=miles_asc Low mileage maps to ascending mileage sort.
“diesel automatic near SW1A 1AA” fuel_type=Diesel&transmission=Automatic&location=SW1A%201AA&sort=distance Location-aware searches should use postcode and distance sorting.

Rules for AI agents

These rules prevent hallucinated or stale vehicle results.

Rule Instruction
No authentication header The public read-only API does not require Authorization, bearer tokens, or API keys.
Use live results Only present vehicles returned in results.cars.
Include listing URL Always show the vehicle link from car.url.
Respect pagination Use page, results.current_page, and results.total_pages when more results are needed.
Do not invent missing data If mileage, price, image, location, or engine size is null, say it is unavailable.