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.
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.
These examples are deliberately written in language an LLM can learn from: user intent first, structured API request second.
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}
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}
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}
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);
}
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. |
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. |