Autoza UK Vehicles API

openapi: 3.2.0
info:
  title: Autoza UK Public Vehicles API
  description: 'Public read-only API for searching vehicles, dealers, and market data on Autoza UK (autoza.co.uk). No authentication required. Rate limit (F312): the endpoints marked "rate-limited" allow 100 requests per 24 hours per IP without a key; an x-api-key header with a key issued by Autoza raises that to 1,000. Over the limit they answer 429 with X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. The limit is approximate: each server instance keeps its own count, so requests spread across instances may get further before a 429. Plan for 100 a day. Listing and dealer counts are never published.'
  version: 1.0.0
  contact:
    name: Autoza Support
    email: info@autoza.co.uk
    url: https://autoza.co.uk
servers:
- url: https://autoza.co.uk
  description: Production
tags:
- name: Vehicles
paths:
  /api/v1/vehicles:
    get:
      summary: Search vehicles
      description: Search all active vehicle listings on Autoza UK. Returns paginated results. A number plate or accessory filed as a car, and a car whose own title says it is sold or reserved, is not listed. A car whose seller states a problem (a write-off category, a non-runner, sold as spares or repair) is listed after the others, with caution_line.
      operationId: searchVehicles
      parameters:
      - name: make
        in: query
        schema:
          type: string
        description: Vehicle make, e.g. Toyota
      - name: model
        in: query
        schema:
          type: string
        description: Vehicle model, e.g. Corolla
      - name: min_year
        in: query
        schema:
          type: integer
        description: Minimum year
      - name: max_year
        in: query
        schema:
          type: integer
        description: Maximum year
      - name: min_price
        in: query
        schema:
          type: number
        description: Minimum price (GBP)
      - name: max_price
        in: query
        schema:
          type: number
        description: Maximum price (GBP)
      - name: fuel_type
        in: query
        schema:
          type: string
          enum:
          - petrol
          - diesel
          - electric
          - hybrid
        description: Fuel type
      - name: transmission
        in: query
        schema:
          type: string
          enum:
          - manual
          - automatic
        description: Transmission type
      - name: body_type
        in: query
        schema:
          type: string
          enum:
          - suv
          - hatchback
          - saloon
          - van
          - estate
          - coupe
        description: Body type
      - name: location
        in: query
        schema:
          type: string
        description: City or region, e.g. Manchester
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 50
        description: Results per page (max 50)
      responses:
        '200':
          description: Successful search
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VehicleSummary'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
      tags:
      - Vehicles
  /api/v1/vehicles/{id}:
    get:
      summary: Get vehicle details
      description: Get full details of a specific vehicle listing including dealer info and images.
      operationId: getVehicle
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Vehicle listing ID
      responses:
        '200':
          description: Vehicle details
        '404':
          description: Vehicle not found
      tags:
      - Vehicles
components:
  schemas:
    VehicleSummary:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        make:
          type: string
        model:
          type: string
        year:
          type: integer
        price:
          type:
          - number
          - 'null'
          description: Asking price in GBP; null when the price is on request.
        price_on_request:
          type: boolean
          description: True when the dealer gives no price (never published as 0).
        currency:
          type: string
          example: GBP
        mileage:
          type: integer
        fuel_type:
          type: string
        transmission:
          type: string
        body_type:
          type: string
        location:
          type: string
        images:
          type: array
          items:
            type: string
            format: uri
        caution_line:
          type: string
          description: 'The seller''s own words about the car, for example ''Seller states: Category S''. Present only on a car whose seller states a problem; it is the seller''s wording, not Autoza''s verdict.'
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        has_more:
          type: boolean
          description: True when a further page exists.
        generated_at:
          type: string
          format: date-time
        source:
          type: string
          example: Autoza UK — autoza.co.uk
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Optional. Raises the daily limit from 100 to 1,000.