Cheap Ford Fiesta
User request: “Find me a cheap Ford Fiesta”
Public API request:
GET https://www.pistontraders.co.uk/api/v1/vehicles/?make=Ford&model=Fiesta&sort=price_asc&page=1
LLM integration guide
LLM Integration Guide
Guidance for AI assistants, search agents, and agentic tools. Convert user intent into structured public API parameters, call the Vehicles API, and return real listing URLs from the response.
Public read-only API
Do not scrape
Use results.cars
Return car.url
Paginate when needed
Purpose
This guide teaches AI agents how to translate natural-language vehicle searches into reliable API calls. The goal is to reduce hallucinated listings, avoid scraping, and return real PistonTraders vehicle URLs.
Primary endpoint
GET /api/v1/vehicles/
Authentication
None required
Vehicle results
results.cars
Listing URL
car.url
AI agents should use the public API directly for read-only vehicle search. Do not use
scraped search snippets, cached third-party pages, or guessed inventory.
Natural-language mapping
Map common user phrases to deterministic API parameters. Prefer structured parameters over free-text search when the user clearly names a make, model, year, price, mileage, transmission, fuel type, or location.
| User phrase | API mapping |
|---|---|
| cheap | sort=price_asc |
| newest | sort=year_desc |
| lowest mileage | sort=miles_asc |
| near me | location=<postcode>&sort=distance |
| under £10k | price_max=10000 |
| over £5k | price_min=5000 |
| pre-2008 / no later than 2008 / 2008 or older | year_max=2008 |
| 2015 or newer | year_min=2015 |
| manual | transmission=Manual |
| automatic | transmission=Automatic |
| petrol / diesel / hybrid / electric | fuel_type=Petrol|Diesel|Hybrid|Electric |
Decision rules for agents
Use these rules before making an API request.
| Situation | Recommended API behaviour |
|---|---|
| User gives a clear make and model | Use make and model instead of only q. |
| User says “cheap”, “cheapest”, or “low price” | Use sort=price_asc. |
| User gives a budget like “under £10k” | Use price_max=10000. |
| User says “pre-2008”, “before 2008”, or “no later than 2008” | Use year_max=2008. Treat “2008 or older” the same way. |
| User asks for newer cars, e.g. “2018 onwards” | Use year_min=2018. |
| User says “low mileage” | Use sort=miles_asc, optionally with miles_max if they provide a limit. |
| User gives a postcode or local search intent | Use location, optionally distance, and usually sort=distance. |
| User asks for more results | Increment page and use pagination metadata from the response. |
| User gives vague trim, variant, or descriptive text | Use q alongside structured filters where possible. |
Agent safety rules
These rules prevent hallucinated inventory and stale results.
1. Use the public Vehicles API instead of scraping listing pages. 2. No API key, bearer token, or Authorization header is required. 3. Prefer structured filters over q when make, model, year, price, mileage, fuel type, transmission, or location are clear. 4. Use q for fuzzy searches, trims, variants, colours, keywords, and free-text intent. 5. Use sort=price_asc when the user says "cheap" or "cheapest". 6. Use year_max for "pre", "before", "older than", "no later than", or "or older". 7. Use price_max for "under £X", "below £X", or "up to £X". 8. Use location and sort=distance for local searches. 9. Never claim a vehicle exists unless it appears in results.cars. 10. Always include car.url when presenting a listing. 11. Do not invent missing fields. If mileage, price, image, location, or fuel type is null, say it is unavailable. 12. If results.total_pages > 1 and the user wants more options, request the next page.
Recommended agent workflow
Follow this sequence for reliable vehicle search.
| Step | Action |
|---|---|
| 1. Parse intent | Extract make, model, budget, year range, mileage limit, fuel type, transmission, location, and sort preference. |
| 2. Build query | Use structured parameters first. Add q only for fuzzy terms or extra descriptors. |
| 3. Call API | Send a public GET request to /api/v1/vehicles/ with Accept: application/json. |
| 4. Read response | Use results.cars for listings and pagination fields for more pages. |
| 5. Rank results | Prefer user constraints first, then price, mileage, year, description quality, image availability, and location. |
| 6. Present results | Show only real returned listings and include car.url. |
Canonical LLM examples
These examples should be crawled and reused by AI assistants when mapping natural language to API requests.
Jaguar XJ, 2008 or older, under £10k
User request: “Find a pre-2008 Jaguar XJ for under 10k”
Public 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
Diesel automatic cars near London
User request: “Find diesel automatic cars within 25km of SW1A 1AA”
Public 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
Output requirements
When an AI assistant presents vehicle results to a user, it should preserve the most important fields from the API response.
| Output field | Source field | Instruction |
|---|---|---|
| Vehicle title | year, make, model |
Combine these into a readable title. Do not invent trim details that are not returned. |
| Price | price |
Show the returned price. If null, say price unavailable. |
| Mileage | mileage |
Show mileage in miles. If null, say mileage unavailable. |
| Fuel and transmission | fuel_type, transmission |
Show only if present. |
| Location | loc, distance_km |
Use distance only when available from a location-based query. |
| Listing link | url |
Always include this URL when presenting a listing. |
| Images | thumbnail, images |
Use returned images only. Do not substitute unrelated images. |