openapi: 3.0.0
info:
  title: AutoScout24 API
  description: |
    The AutoScout24 API returns real-time car listings from Europe's largest online car marketplace.
    Search by make and model and refine with structured filters like price, mileage, first registration,
    power, fuel type, transmission, body type, seller type, and location radius, across the German,
    Austrian, Belgian, Spanish, French, Italian, Luxembourgish, and Dutch marketplaces.

    **Cross-linking**: each result includes a `link` you can pass to the AutoScout24 Listing API
    (`engine=autoscout24_listing`) to retrieve the full vehicle detail sheet.

    **Promoted results**: rows with `is_promoted: true` are paid placements. They ignore `sort_by`
    and can repeat on the following page. A promoted car that also holds an organic slot on the
    same page is returned once, as the organic row.

    **Pagination limit**: AutoScout24 caps browsable results at 200 pages (4,000 listings) per query
    regardless of the total match count, so narrow with filters to reach deeper inventory.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: AutoScout24 Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine to use for the search
          schema:
            type: string
            enum: ["autoscout24"]
            default: "autoscout24"
        - name: make
          in: query
          required: false
          description: Vehicle make (brand), e.g. `volkswagen`. Names are lower-cased and hyphenated. Valid makes are returned in the response `filters` block.
          schema:
            type: string
        - name: model
          in: query
          required: false
          description: Vehicle model, e.g. `golf`. Requires `make`.
          schema:
            type: string
        - name: country
          in: query
          required: false
          description: AutoScout24 marketplace (domain, currency, inventory).
          schema:
            type: string
            enum: ["de", "at", "be", "es", "fr", "it", "lu", "nl"]
            default: "de"
        - name: price_min
          in: query
          required: false
          description: Minimum price in the marketplace currency (EUR).
          schema:
            type: integer
            minimum: 0
        - name: price_max
          in: query
          required: false
          description: Maximum price in the marketplace currency (EUR).
          schema:
            type: integer
            minimum: 0
        - name: mileage_min
          in: query
          required: false
          description: Minimum mileage in kilometres.
          schema:
            type: integer
            minimum: 0
        - name: mileage_max
          in: query
          required: false
          description: Maximum mileage in kilometres.
          schema:
            type: integer
            minimum: 0
        - name: registration_year_min
          in: query
          required: false
          description: Earliest first-registration year, between 1900 and 2100.
          schema:
            type: integer
            minimum: 1900
            maximum: 2100
        - name: registration_year_max
          in: query
          required: false
          description: Latest first-registration year, between 1900 and 2100.
          schema:
            type: integer
            minimum: 1900
            maximum: 2100
        - name: power_min
          in: query
          required: false
          description: Minimum engine power, in the unit set by `power_unit`.
          schema:
            type: integer
            minimum: 0
        - name: power_max
          in: query
          required: false
          description: Maximum engine power, in the unit set by `power_unit`.
          schema:
            type: integer
            minimum: 0
        - name: power_unit
          in: query
          required: false
          description: Unit `power_min` and `power_max` are given in. AutoScout24 filters in kW, so `hp` values are converted before the search runs.
          schema:
            type: string
            enum: ["kw", "hp"]
            default: "kw"
        - name: fuel_type
          in: query
          required: false
          description: Fuel type filter.
          schema:
            type: string
            enum: ["petrol", "diesel", "electric", "hybrid_petrol", "hybrid_diesel", "cng", "hydrogen", "lpg", "ethanol", "other"]
        - name: transmission
          in: query
          required: false
          description: Transmission filter.
          schema:
            type: string
            enum: ["automatic", "manual", "semi_automatic"]
        - name: body_type
          in: query
          required: false
          description: >-
            Body type filter. Filter only: a list row does not echo it, the `autoscout24_listing`
            engine's `vehicle.body_type` does.
          schema:
            type: string
            enum: ["compact", "convertible", "coupe", "suv", "station_wagon", "sedan", "van", "transporter", "other"]
        - name: seller_type
          in: query
          required: false
          description: Seller type filter.
          schema:
            type: string
            enum: ["dealer", "private"]
        - name: condition
          in: query
          required: false
          description: >-
            AutoScout24's offer type. `annual` is a one-year-old ex-fleet car, `demo` a dealer
            demonstrator, `day_registration` a new car registered by the dealer, `classic` a
            vintage car. Omit for every type. Accident vehicles are selected with `damage`, not here.
          schema:
            type: string
            enum: ["new", "used", "annual", "classic", "demo", "day_registration"]
        - name: damage
          in: query
          required: false
          description: >-
            How damaged and accident vehicles are treated. AutoScout24 hides them by default,
            so use `include` to search all cars and `only` to search damaged cars alone. On `de`,
            `only` selects currently damaged cars and results carry `is_damaged`. On the other
            marketplaces it selects cars with an accident history instead, so results carry
            `condition: accident` and can come back without `is_damaged` set.
          schema:
            type: string
            default: "exclude"
            enum: ["exclude", "include", "only"]
        - name: zip
          in: query
          required: false
          description: Postal code to search around. Works on its own, in which case AutoScout24 applies its own default radius.
          schema:
            type: string
            pattern: '^[A-Za-z0-9 -]{1,10}$'
            maxLength: 10
        - name: radius
          in: query
          required: false
          description: Search radius in kilometres around `zip`. Requires `zip`.
          schema:
            type: integer
            minimum: 1
        - name: sort_by
          in: query
          required: false
          description: Result ordering.
          schema:
            type: string
            enum: ["best_match", "price_asc", "price_desc", "mileage_asc", "mileage_desc", "registration_asc", "registration_desc", "power_asc", "power_desc", "newest"]
            default: "best_match"
        - name: page
          in: query
          required: false
          description: Page number (20 results per page). Capped at 200.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 1
        - name: api_key
          in: query
          required: false
          description: Your SearchApi API key (or use the Authorization header).
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
        organic_results:
          type: array
          items:
            $ref: '#/components/schemas/OrganicResult'
        pagination:
          $ref: '#/components/schemas/Pagination'
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: AutoScout24 URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        make:
          type: string
        model:
          type: string
        country:
          type: string
        price_min:
          type: integer
        price_max:
          type: integer
        mileage_min:
          type: integer
        mileage_max:
          type: integer
        registration_year_min:
          type: integer
        registration_year_max:
          type: integer
        power_min:
          type: integer
        power_max:
          type: integer
        power_unit:
          type: string
        fuel_type:
          type: string
        transmission:
          type: string
        body_type:
          type: string
        seller_type:
          type: string
        condition:
          type: string
        damage:
          type: string
        zip:
          type: string
        radius:
          type: integer
        sort_by:
          type: string
        page:
          type: integer
    SearchInformation:
      type: object
      properties:
        total_results:
          type: integer
        total_pages:
          type: integer
        page:
          type: integer
        results_on_page:
          type: integer
    Filter:
      type: object
      properties:
        type:
          type: string
        options:
          type: array
          items:
            type: string
    OrganicResult:
      type: object
      properties:
        position:
          type: integer
        id:
          type: string
        title:
          type: string
        link:
          type: string
          description: Offer URL. Pass it as `url` to `engine=autoscout24_listing`.
        is_online_purchase:
          type: boolean
          description: >-
            Present and true on cars sold through smyle, AutoScout24's own online checkout. Their
            `link` is a `/smyle/details/{id}/` page, which the listing engine accepts.
        is_promoted:
          type: boolean
          description: Present and true on paid placements, which ignore `sort_by`.
        price:
          type: string
        extracted_price:
          type: integer
        previous_price:
          type: string
        currency:
          type: string
        make:
          type: string
        model:
          type: string
        variant:
          type: string
        motor:
          type: string
        condition:
          type: string
          description: >-
            `new`, `used`, or `accident` for cars AutoScout24 files under its accident-vehicle
            offer type (reachable with `damage=only`). A list row flattens the finer offer types
            (`annual`, `demo`, ...) to `used`; the `autoscout24_listing` engine's `vehicle.condition`
            carries them.
          enum: ["new", "used", "accident"]
        is_damaged:
          type: boolean
        mileage:
          type: string
        extracted_mileage:
          type: integer
        first_registration:
          type: string
          description: '`MM/YYYY`. Omitted on new cars, which carry `condition: new` instead.'
        fuel_type:
          type: string
          description: Normalised to the `fuel_type` parameter vocabulary.
        fuel_type_label:
          type: string
          description: AutoScout24's own label, in the marketplace language.
        transmission:
          type: string
          description: Normalised to the `transmission` parameter vocabulary.
        transmission_label:
          type: string
          description: AutoScout24's own label, in the marketplace language.
        power:
          type: string
        power_kw:
          type: integer
        power_hp:
          type: integer
        emissions:
          $ref: '#/components/schemas/Emissions'
        seller:
          $ref: '#/components/schemas/Seller'
        location:
          $ref: '#/components/schemas/Location'
        thumbnail:
          type: string
          description: The 250x188 list-card rendition of the first image.
        images:
          type: array
          description: The full gallery at 1280x960, the same assets `autoscout24_listing` returns.
          items:
            type: string
        images_count:
          type: integer
    Emissions:
      type: object
      description: Combined WLTP figures as AutoScout24 displays them. Absent when the listing carries no figure.
      properties:
        co2:
          type: string
          example: 136 g/km (komb.)
        consumption:
          type: string
          example: 5,2 l/100 km (komb.)
        co2_class:
          type: string
          description: EU CO2 efficiency class, A to G. Shown on markets that display it (Germany since 2024).
          enum: [A, B, C, D, E, F, G]
    Seller:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: ["dealer", "private"]
        name:
          type: string
        contact:
          type: string
        phones:
          type: array
          items:
            type: string
        info_page:
          type: string
        rating_stars:
          type: number
          description: >-
            The half-star value AutoScout24 draws the rating widget with. The exact average is on
            the `autoscout24_listing` seller as `rating`.
        reviews:
          type: integer
    Location:
      type: object
      properties:
        country:
          type: string
        zip:
          type: string
        city:
          type: string
        street:
          type: string
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
        total_pages:
          type: integer
        next_page:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string