openapi: 3.0.0
info:
  title: AutoScout24 Listing API
  description: |
    The AutoScout24 Listing API returns the complete detail sheet for a single car listing: the full
    vehicle specification, mileage and registration, price with market context, environmental data
    (CO2 emissions, fuel consumption, Euro emission class and sticker), categorised equipment, the
    seller with contact phones and rating, a geo-located address, images, and the description.

    **Cross-linking**: pass the `link` emitted by the AutoScout24 API (`engine=autoscout24`),
    an `organic_results[].link`, a full offer URL, an offer path (`/angebote/{slug}` on `de`
    and `at`, `/aanbod/{slug}` on `nl`, `/nl/aanbod/{slug}` or `/fr/offres/{slug}` on `be`,
    and so on), or a bare offer slug, which is resolved on the `country` market's own path.
    A `/smyle/details/{id}/` link (AutoScout24's own online checkout) is accepted as well.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: AutoScout24 Listing Detail
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine to use for the search
          schema:
            type: string
            enum: ["autoscout24_listing"]
            default: "autoscout24_listing"
        - name: url
          in: query
          required: true
          description: >-
            AutoScout24 listing URL, offer path (`/angebote/{slug}`, `/aanbod/{slug}`,
            `/nl/aanbod/{slug}`, ...), `/smyle/details/{id}/` link, or bare offer slug.
          schema:
            type: string
        - name: country
          in: query
          required: false
          description: >-
            Marketplace to resolve `url` on. When `url` is a full URL its domain wins. When it is
            an offer path whose localized segment belongs to another market, the path is rebuilt
            on this market's own segment.
          schema:
            type: string
            enum: ["de", "at", "be", "es", "fr", "it", "lu", "nl"]
            default: "de"
        - 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/ListingResponse'
        '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:
    ListingResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        listing:
          $ref: '#/components/schemas/Listing'
        error:
          type: string
          description: Present instead of `listing` when AutoScout24 no longer serves the offer (sold or removed).
    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 listing
        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
        url:
          type: string
        country:
          type: string
    Listing:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        link:
          type: string
        status:
          type: string
        is_online_purchase:
          type: boolean
          description: Present and true on cars sold through smyle, AutoScout24's own online checkout.
        created_at:
          type: string
          format: date-time
        price:
          type: string
        extracted_price:
          type: integer
        previous_price:
          type: string
        currency:
          type: string
        median_price:
          type: integer
        is_negotiable:
          type: boolean
        is_vat_deductible:
          type: boolean
        is_price_on_request:
          type: boolean
          description: Present and true when AutoScout24 lists the car with no price at all.
        vehicle:
          $ref: '#/components/schemas/Vehicle'
        seller:
          $ref: '#/components/schemas/Seller'
        location:
          $ref: '#/components/schemas/Location'
        availability:
          $ref: '#/components/schemas/Availability'
        is_deliverable:
          type: boolean
        has_360_view:
          type: boolean
        has_warranty:
          type: boolean
        warranty:
          type: string
          description: The warranty term as AutoScout24 words it, where the marketplace publishes one (`.de` does not).
        seals:
          type: array
          items:
            $ref: '#/components/schemas/Seal'
        special_conditions:
          type: array
          items:
            type: string
        vehicle_report_url:
          type: string
        youtube_link:
          type: string
        whatsapp_number:
          type: string
        images:
          type: array
          items:
            type: string
        description:
          type: string
    Availability:
      type: object
      properties:
        from_date:
          type: string
        in_days:
          type: integer
    Vehicle:
      type: object
      properties:
        make:
          type: string
        model:
          type: string
        variant:
          type: string
        body_type:
          type: string
          description: Normalised to the `body_type` parameter vocabulary.
        body_type_label:
          type: string
          description: AutoScout24's own label, in the marketplace language.
        condition:
          type: string
          description: Normalised to the `autoscout24` engine's `condition` parameter vocabulary, plus `accident`.
          enum: ["new", "used", "annual", "classic", "demo", "day_registration", "accident"]
        mileage:
          type: string
        extracted_mileage:
          type: integer
        first_registration:
          type: string
        first_registration_date:
          type: string
        power:
          type: string
        power_kw:
          type: integer
        power_hp:
          type: integer
        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.
        gears:
          type: integer
        cylinders:
          type: integer
        displacement:
          type: string
        extracted_displacement:
          type: integer
        drivetrain:
          type: string
          enum: ["front", "rear", "all_wheel"]
        drivetrain_label:
          type: string
          description: AutoScout24's own label, in the marketplace language.
        seats:
          type: integer
        doors:
          type: integer
        color:
          type: string
          description: AutoScout24's machine colour token, snake_cased.
        color_label:
          type: string
          description: AutoScout24's own label, in the marketplace language.
        upholstery:
          type: string
          enum: ["alcantara", "cloth", "full_leather", "part_leather", "velour", "other"]
        upholstery_label:
          type: string
          description: AutoScout24's own label, in the marketplace language.
        previous_owners:
          type: integer
        has_full_service_history:
          type: boolean
        production_year:
          type: integer
        damage:
          $ref: '#/components/schemas/Damage'
        emissions:
          $ref: '#/components/schemas/Emissions'
        equipment:
          $ref: '#/components/schemas/Equipment'
    Damage:
      type: object
      properties:
        is_damaged:
          type: boolean
        is_roadworthy:
          type: boolean
        is_accident_free:
          type: boolean
        has_accident_history:
          type: boolean
        has_repaired_damages:
          type: boolean
        condition_labels:
          type: array
          description: AutoScout24's damage disclosure labels, in the marketplace language. The booleans above carry the same facts.
          items:
            type: string
    Emissions:
      type: object
      properties:
        co2:
          type: string
        extracted_co2:
          type: integer
        consumption:
          type: string
        extracted_consumption:
          type: number
        co2_class:
          type: string
          description: EU CO2 efficiency class, A to G, where AutoScout24 states it.
          enum: [A, B, C, D, E, F, G]
        euro_norm:
          type: string
        emission_sticker:
          type: string
        electric_range:
          type: string
    Equipment:
      type: object
      properties:
        comfort_and_convenience:
          type: array
          items:
            $ref: '#/components/schemas/EquipmentItem'
        entertainment_and_media:
          type: array
          items:
            $ref: '#/components/schemas/EquipmentItem'
        extras:
          type: array
          items:
            $ref: '#/components/schemas/EquipmentItem'
        safety_and_security:
          type: array
          items:
            $ref: '#/components/schemas/EquipmentItem'
    EquipmentItem:
      type: object
      properties:
        id:
          type: integer
          description: AutoScout24's stable equipment id, the same on every marketplace.
        name:
          type: string
          description: The item's label, in the marketplace language.
    Seal:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        info:
          type: string
        image:
          type: string
    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
        is_dealer:
          type: boolean
        rating:
          type: number
          description: The dealer's exact average rating.
        rating_stars:
          type: number
          description: The half-star value AutoScout24 draws the rating widget with.
        reviews:
          type: integer
        recommend_percentage:
          type: integer
        reviews_page:
          type: string
    Location:
      type: object
      properties:
        country:
          type: string
        zip:
          type: string
        city:
          type: string
        street:
          type: string
        latitude:
          type: number
        longitude:
          type: number
    ErrorResponse:
      type: object
      properties:
        error:
          type: string