Introduction

As part of our platform modernization efforts, we are replatforming all our APIs to enhance performance, security, and functionality. This includes the HCI JSON APIs, which require significant changes to align with modern technology stacks, state-of-the-art architecture, and contemporary software design principles.

To facilitate this transition, we are deprecating the existing APIs and allowing a four-month migration period for clients to switch to the new versions. After this period, the legacy APIs will be permanently discontinued, and only the new APIs described in this document will be available.

This guide provides an overview of the new APIs and demonstrates how to use them effectively. It includes implementation examples based on our HCI White-label Solution.

By following this guide, you can seamlessly migrate to the new HCI JSON APIs, improving performance, security, and flexibility. For further information, refer to the AutoScout24 API Documentation or contact our support team.

Legacy APIs Overview

The following APIs were previously used for HCI JSON integrations:

  1. Metadata API – Provided all possible filter values, min and max values, and translations for labels.
  2. List API – Returned listing data based on specified search criteria.
  3. Summaries API – Similar to the List API but included additional data points.
  4. Listing Details API – Returned detailed information for a given listing ID.

Security: These legacy APIs were secured using IP whitelisting or API keys.

New APIs Overview

In line with RESTful principles and modern resilience patterns, we have moved away from monolithic designs. Instead, we have adopted a modular approach, where each API serves a specific purpose. This allows for greater flexibility, improved performance, and enhanced reliability.

All new APIs are fully documented on the AutoScout24 Developer Portal, including:

Within the Swagger documentation, the HCI JSON APIs are organized into the following three groups. Only these APIs should be used for HCI JSON integration:

By leveraging these new APIs, clients can build more efficient, resilient, and scalable integrations while ensuring compliance with the latest security and performance standards.

Note: This guide outlines one possible implementation approach. Clients are free to design their integrations according to their specific requirements.

Authentication and Authorization ↗

As part of our ongoing commitment to enhancing security, we have transitioned away from using IP address whitelisting and API keys for authentication. We now implement a robust client-credentials flow, aligned with modern security standards and industry best practices for API security. This change ensures more secure and scalable access control for our APIs.

For a detailed explanation of the new authentication and authorization mechanisms—including how to obtain client credentials and access tokens—please refer to our Developer Portal and API Reference documentation.

Building the Advanced Search Page (AdvSP)

The Advanced Search Page allows users to apply detailed filters to refine their search. Unlike the Search Results Page (SRP), which focuses on commonly used filters, the AdvSP provides a more comprehensive filtering experience.

Advanced Search Page

APIs for AdvSP

  1. Reference Data API
    • Provides all possible filter values for a given vehicle category.
    • Enables dynamic data retrieval when the user selects a vehicle category.
    • Caching is recommended, as this data is rarely updated.
  2. Facets API
    • Provides faceting based on provided search criteria.
    • Helps display only filtering options that are used in active inventory.
  3. Make API
    • Returns all available vehicle makes supported for filtering and display.
    • Caching is recommended to reduce API calls.
  4. Model API
    • Returns all available models for a given make.
    • Caching is recommended for performance optimization.
  5. Translations API
    • Supports multilingual functionality with translations in German, French, and Italian.
    • Fetches translation labels for UI elements based on the selected language.
    • Caching is recommended as translation data rarely changes.
  6. Listing Count API
    • Returns the number of listings matching search criteria without executing a full search query.
    • Helps display the number of results before performing a full search.
    • More efficient than calling the Listing Search API directly.
  7. Geo Location Search API
    • Returns localized geo location data per specified language, based on a given search query (including pagination).
    • Returns geo location data such as id, type, and name.
  8. Seller Search API
    • Returns seller details based on search criteria, including id and name.

Building the Search Results Page (SRP)

The Search Results Page (SRP) contains commonly used filters and displays listings that match the selected criteria.

Search Results Page

APIs for SRP

  1. All APIs from the Advanced Search Page (AdvSP) section.
  2. Listing Search API
    • Returns listings matching search criteria, with options for sorting, pagination, and result size.
    • Returns essential listing details such as title, price, images, and key specifications.
    • Called whenever the user updates the filters to ensure real-time search updates.

Building the Product Details Page (PDP)

The Product Details Page (PDP) provides detailed listing information, including specifications, images, and seller details. The page should be resilient and support partial loading if some API data is unavailable.

Product Details Page

APIs for PDP

  1. Listing Details API
    • Provides technical listing details, images, and key specifications for a given listing ID.
  2. Listing Equipment API
    • Returns localized equipment data per selected language for a given listing ID.
  3. Quali Logo API
    • Provides localized quali logo information for a given quali logo ID.
    • Caching is recommended as this data is static.
  4. Seller API
    • Fetches seller details, including location, logo, and contact information for a given seller ID.

Sending Message Leads

The Message Lead Form allows potential buyers to contact sellers directly. Messages are sent only after passing fraud detection checks to ensure only valid inquiries reach sellers.

Message Lead

API for Message Lead Submission

  1. Message Lead API
    • The only API that creates a resource in the new system.
    • Accepts buyer details, including first name, last name, email, phone number, and message.
    • Implements fraud detection, checking for data validity, spam filtering, and content validation.
    • Requires the X-AS24-Source header (set to "hci") to track lead performance in AutoScout24 analytics.

Legacy vs New APIs Comparison

The new APIs are designed to be more modular, RESTful, and aligned with modern software design principles. Below is a comparison of the legacy APIs and their new counterparts, as well as the fields that have been added, removed, or changed.

Security

Legacy APIs relied on IP whitelisting or API keys, while the new APIs use a client-credentials flow for authentication and authorization, as explained in the Authentication and Authorization ↗ section.

Fields Mapping Support Legend

  • Green → Supported in the new API’s counterpart
  • Orange → Not directly supported in API’s counterpart, but available in different API
  • Red → Not supported anymore.

Legacy APIs Migration

Metadata API

Response:

[
  {
    "ParameterName": "lng",
    "Description": "The requested language. 'de', 'fr', or 'it', 'de' is default",
    "Label_DE": "Sprache",
    "Label_FR": "Langue",
    "Label_IT": "Lingua",
    "ValueType": "String",
    "AcceptsCustomValues": false,
    "CustomValuesBounds": null,
    "FilterParameterNames": null,
    "Options": [
      {
        "Description": "German",
        "Label_DE": "Deutsch",
        "Label_FR": "Allemand",
        "Label_IT": "Tedesco",
        "Value": "de",
        "OptionFilters": null
      },
      {
        "Description": "French",
        "Label_DE": "Französisch",
        "Label_FR": "Français",
        "Label_IT": "Francese",
        "Value": "fr",
        "OptionFilters": null
      },
      {
        "Description": "Italian",
        "Label_DE": "Italienisch",
        "Label_FR": "Italien",
        "Label_IT": "Italiano",
        "Value": "it",
        "OptionFilters": null
      }
    ]
  },
  ...
]
  • Provides options for language parameter ->
    • Reference Data API – Provides all possible filter values for a given vehicle category specified. This API is providing enumerated values for filters like fuelType, transmissionType, etc. where buyer is presented with pre-defined options.
  • Gave description of what the parameter represents ->
    • Presented in OpenAPI Specification and Swagger UI, through corresponding schema definitions.
  • Provided labels in different languages ->
    • Translations API – Provides translations for labels in German, French, and Italian. This API is used to fetch translation labels for UI elements based on the selected language.
  • In cases of some of the filters (priceFrom, priceTo, etc.) it provided min and max values ->
    • Not supported anymore, our range filters accept custom values, so min and max values are not required. The client can specify any value, and if you want to provide ranges, it’s up to the client to implement this logic on the frontend.
  • In cases of some of the filters (fuelType, transmissionType, make, model, etc.) it provided all possible values for the filter ->
    • Reference Data API - Already mentioned.
    • Make API - Returns all available makes for a given vehicle category, allowing dynamic data retrieval.
    • Model API – Returns all available models for a given make and vehicle category, allowing dynamic data retrieval.

Summaries and List APIs

Summaries and List APIs were used to return listing data based on specified search criteria. The Summaries API returned a subset of the List API, except of CcmText and ThumbnailImageUrl fields. These two legacy APIs is now merged into a single Listing Search API that returns listings matching search criteria, with options for sorting, pagination, and result size. We will give an example of the response from the legacy List API and list corresponding fields in the new Listing Search API, and query parameters that we now support are clearly listed in the Open API Specification and Swagger UI.

Response:

{
  "TotalMatches": 103362,
  "CurrentPage": 1,
  "ItemsOnPage": 25,
  "TotalPages": 4135,
  "ItemsPerPage": 25,
  "Vehicles": [
    {
      "AccountId": 2487890,
      "BatteryRentPrice": null,
      "BodyColorId": 62,
      "BodyColorText": "beige",
      "BodyTypeId": 5,
      "BodyTypeText": "Berlina",
      "BootHeight": 0,
      "BootLength": 0,
      "BootVolume": null,
      "BootWidth": 0,
      "CarNumber": null,
      "Ccm": 1368,
      "CertificationCode": null,
      "ChassisCode": null,
      "Co2Emission": 162,
      "Co2EmissionAverage": null,
      "Co2EmissionAverageText": null,
      "Co2EmissionPowerProduction": null,
      "Co2EmissionPowerProductionText": null,
      "Co2EmissionText": "162 g/km",
      "Comments": "",
      "ConditionTypeId": 49,
      "ConditionTypeText": "Occasione",
      "ConsumptionCity": 8.8,
      "ConsumptionGas": 0,
      "ConsumptionGasText": null,
      "ConsumptionLand": 5.8,
      "ConsumptionPower": 0,
      "ConsumptionPowerText": null,
      "ConsumptionRatingText": null,
      "ConsumptionRatingTypeId": -1,
      "ConsumptionTotal": 7.1,
      "ConsumptionTotalText": "7.1 l/100km",
      "CylinderDesignTypeId": 55,
      "CylinderDesignTypeText": "serie",
      "Cylinders": 4,
      "DateCreated": "/Date(1712153551000+0200)/",
      "DateModified": "/Date(1724845994000+0200)/",
      "DateOfLastInspection": null,
      "DateTopListing": "/Date(1723446210340+0200)/",
      "DealerPrice": 0,
      "Documents": [],
      "Doors": 5,
      "DriveTypeId": 22,
      "DriveTypeText": "Trazione anteriore",
      "Equipment": {
        "AutoIDatEquipment": null,
        "EurotaxEquipment": null,
        "EurotaxEquipmentUncategorized": null,
        "OptionalEquipmentFlatList": [],
        "SearchableEquipment": [
          "Bloccaggio del differenziale ",
          "Cerchi in alluminio",
          "Controllo della stabilità",
          "Impianto di climatizzazione automatico",
          "Interfaccia bluetooth",
          "Isofix",
          "Regolatore di velocità",
          "Regolazione elettrica dei sedili",
          "Sensori di parcheggio anteriori",
          "Sensori di parcheggio posteriori",
          "Sistema di navigazione integrato",
          "Sistema start/stop",
          "Vivavoce"
        ],
        "StandardEquipmentFlatList": [
          "Rétroviseur intérieur électrochrome",
          "Computer di bordo",
          "Chiusura centralizzata con telecomando",
          "Indicatore della temperatura esterna",
          "Servosterzo dipendente dalla velocità",
          "Alzacristalli elettrici anteriori e posteriori",
          "Fari antinebbia",
          "Retrovisori esterni",
          "Tempomat",
          "Sedile conducente regolabile in altezza",
          "Spoiler posteriore",
          "Rivestimento interno del tetto nero",
          "Vetri oscurati nella parte posteriore",
          "Set riparazione pneumatici (Tire Fit)",
          "Catalizzatore regolato",
          "Sistema antibloccaggio delle ruote (ABS)",
          "Attacchi ISOFIX per seggiolini",
          "Illuminazione interna con temporizzazion",
          "Funzione Start/Stop",
          "Antriebsschlupfregelung (ASR)",
          "Airbag: Airbags tendine per la testa",
          "Airbag: Airbag conducente e passeggero",
          "Airbag: Airbag passeggero desattivabile",
          "Controllo di cintura",
          "Assistenza di frenaggio",
          "Cinture di sicurezza a 3 punti",
          "Sedili: Sedile passeggero regolabile in altezza",
          "2a chiave con telecomando",
          "Airbag: Airbags laterali per conducente e",
          "Cambio: Cambio manuale a 6 marce",
          "Regolazione della portata dell'illumina-",
          "Vetri atermici Privacy",
          "Aiuto partenza in pendenza",
          "Terza luce di stop",
          "Pedaleria in alluminio",
          "Schienale posteriore ribaltabile in",
          "Clima: Climatizzatore a regolazione automatica bizona",
          "Sensore pioggia + crepuscolare",
          "Lampade da lettura",
          "ripartizione elettronica della forza",
          "Listelli d'ingresso in alluminio",
          "Fari oscurati",
          "Controllo dinamico della stabilità (VDC)",
          "Luci di marcia diurna (DRL)",
          "Cinture di sicurezza anteriori con pretensionatori",
          "Sistema di protezione antincendio FPS",
          "Alfa Climate Control",
          "Cinture di sicurezza posteriori con meccanismo di avvolgimento automatico",
          "Garanzia: Alfa Garanzia: 3 anni / chilomettraggio illimitato (da 1a messa in circ.)",
          "Elettronica D2: Innovative-asse",
          "Specchietti esterni regolabili elettricamente, riscaldati e ripiegabili manualmente",
          "Hill Holder",
          "Poggiatesta anteriori (con protezione dal colpo di frusta), posteriori regolabili in altezza",
          "Assist: Sensori di parcheggio anteriori e posteriori con avvisatore acustico",
          "Volante multifunzione in pelle con elementi interruttori per autoradio e telefono",
          "Luce: Sistema di fari \"Follow Me Home\"",
          "Cruscotto e pannelli delle porte in carbon look",
          "Paraurti sportivo nella parte posteriore",
          "Ruote: cerchi in lega da 17\" con design a 5 fori e rivestimento scuro con pneumatici 225/45",
          "Aletta parasole passeggero anteriore con specchietto e illuminazione integrata",
          "Media: sistema di navigazione Uconnect con visualizzazione mappa 3D, connessione Bluetooth,"
        ]
      },
      "Extras": null,
      "FirstRegMonth": 7,
      "FirstRegYear": 2020,
      "FuelTypeId": 14,
      "FuelTypeText": "Benzina",
      "HasWarranty": false,
      "Height": 1450,
      "Hp": 120,
      "Id": 8680206,
      "Images": {
        "S": null,
        "M": null,
        "L": null,
        "XL": null,
        "Original": null
      },
      "ImagesCount": 0,
      "ImagesThreeSixty": null,
      "InteriorColorId": -1,
      "InteriorColorText": null,
      "Km": 112313,
      "Kw": 88,
      "Latitude": 0,
      "LeasingCalculatorUrl": "https://www.financescout24.ch/it/credito/finanziamento-auto?vehicleId=8680206&amount=3123123.00&userTypeId=3&utm_source=autoscout24.ch&utm_medium=web&utm_campaign=link_detailpage_credit_",
      "Length": 4351,
      "LicenseCategoryText": "B",
      "LicenseCategoryTypeId": 33,
      "LogoDescription": null,
      "LogoId": 0,
      "LogoImageUrl": null,
      "LogoText": null,
      "LogoUrl": null,
      "Longitude": 0,
      "MakeId": 2,
      "MakeText": "ALFA ROMEO",
      "ModelGroupId": null,
      "ModelGroupText": null,
      "ModelId": 15,
      "ModelText": "GIULIETTA",
      "ModelTypeText": "Giulietta 1.4 Turbo Sport",
      "PayLoad": 326,
      "PetrolEquivalent": null,
      "PetrolEquivalentText": null,
      "PollutionNormTypeId": 239,
      "PollutionNormTypeText": "Euro 6d-TEMP",
      "Price": 3123123,
      "PriceHistory": [],
      "PriceNew": 26900,
      "Properties": null,
      "Seats": 5,
      "SegmentationId": -1,
      "SegmentationText": null,
      "SegmentationTypeId": -1,
      "SegmentationTypeText": null,
      "Seller": {
        "Id": 1983758,
        "Name": "Test Test",
        "Street": "Werdstrasse 21",
        "Zip": "8000",
        "City": "Zurich",
        "PoBox": "",
        "AdditionalInfo": null,
        "Phone": "+41-786076858",
        "Mobile": "+41-786076858",
        "Email": "[email protected]",
        "Url": null
      },
      "SleepingBerths": 0,
      "Teaser": null,
      "TrailerLoadBreaked": 1300,
      "TransmissionShaftId": -1,
      "TransmissionShaftText": null,
      "TransmissionTypeId": 20,
      "TransmissionTypeText": "Cambio manuale",
      "TypeName": "Giulietta 1.4 Turbo Sport",
      "TypeNameFull": "ALFA ROMEO Giulietta 1.4 Turbo Sport",
      "Url": "https://int.autoscout24.ch/api/hci/v3/json/Vehicles/8680206?lng=it&member=60601&cuid=60601",
      "UserType": 3,
      "VehicleTags": null,
      "VehicleType": 10,
      "VehicleTypeText": "Automobile",
      "Videos": [],
      "VisibilityId": 0,
      "WarrantyDescription": "",
      "WarrantyMonths": 0,
      "Weight": 1459,
      "WeightTotal": 1785,
      "Width": 1798
    },
    ...
  ]
Root-level fields
  • TotalMatches -> totalElements
  • CurrentPage -> number
  • ItemsOnPage -> numberOfElements
  • TotalPages -> totalPages
  • ItemsPerPage -> size
  • Vehicles -> content
Vehicle object fields
  • AccountId -> sellerId
  • BatteryRentPrice -> Not supported anymore, removed due to the low usage and benefit for the buyer.
  • BodyColorId -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as bodyColor enumerated field in the Listing Details API.
  • BodyColorText -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This translation is available in the Translations API.
  • BodyTypeId -> bodyType
  • BodyTypeText -> This translation is available in the Translations API.
  • BootHeight -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as boot.height in the Listing Details API.
  • BootLength -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as boot.length in the Listing Details API.
  • BootVolume -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as boot.volume in the Listing Details API.
  • BootWidth -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as boot.width in the Listing Details API.
  • CarNumber -> sellerVehicleId.
  • Ccm -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as cubicCapacity in the Listing Details API.
  • CertificationCode -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as certificationNumber in the Listing Details API.
  • ChassisCode -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as vehicleIdentificationNumber in the Listing Details API.
  • Co2Emission -> co2Emission
  • Co2EmissionAverage -> Not supported anymore.
  • Co2EmissionAverageText -> Not supported anymore.
  • Co2EmissionPowerProduction -> Not supported anymore.
  • Co2EmissionPowerProductionText -> Not supported anymore.
  • Co2EmissionText -> Not supported anymore, formatting is UI concern
  • Comments -> Not supported anymore.
  • ConditionTypeId -> conditionType
  • ConditionTypeText -> This translation is available in the Translations API.
  • ConsumptionCity -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as consumption.urban in the Listing Details API.
  • ConsumptionGas -> Not supported anymore.
  • ConsumptionGasText -> Not supported anymore.
  • ConsumptionLand -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as consumption.extraUrban in the Listing Details API.
  • ConsumptionPower -> Not supported anymore.
  • ConsumptionPowerText -> Not supported anymore.
  • ConsumptionRatingText -> This translation is available in the Translations API.
  • ConsumptionRatingTypeId -> energyLabel
  • ConsumptionTotal -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as consumption.combined in the Listing Details API.
  • ConsumptionTotalText -> Not supported anymore, formatting is UI concern
  • CylinderDesignTypeId -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as cylinderArrangment enumerated field in the Listing Details API.
  • CylinderDesignTypeText -> This translation is available in the Translations API.
  • Cylinders -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as cylinders field in the Listing Details API.
  • DateCreated -> Not supported anymore.
  • DateModified -> Not supported anymore.
  • DateOfLastInspection -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as lastInspectionDate field in the Listing Details API.
  • DateTopListing -> Not supported anymore.
  • DealerPrice -> Not supported anymore.
  • Doors -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as doors field in the Listing Details API.
  • DriveTypeId -> driveType
  • DriveTypeText -> This translation is available in the Translations API.
  • Extras -> Not supported anymore, fields that represented “extras” are now proper independent fields and are available in the * *Listing Details API**.
  • FirstRegMonth -> Not supported anymore.
  • FirstRegYear -> firstRegistrationYear
  • FuelTypeId -> fuelType
  • FuelTypeText -> This translation is available in the Translations API.
  • HasWarranty -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as warranty object in the Listing Details API.
  • Height -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as height field in the Listing Details API.
  • Hp -> horsePower
  • Id -> id
  • ImagesCount -> images
  • ImagesThreeSixty -> Not supported anymore.
  • InteriorColorId -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as interiorColor enumerated field in the Listing Details API.
  • InteriorColorText -> This translation is available in the Translations API.
  • Km -> mileage
  • Kw -> kiloWatts
  • Latitude -> Not supported anymore.
  • LeasingCalculatorUrl -> leasing.url
  • Length -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as length field in the Listing Details API.
  • LicenseCategoryText -> This translation is available in the Translations API.
  • LicenseCategoryTypeId -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as licenseCategory enumerated field in the Listing Details API.
  • LogoDescription -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as description field in the QualiLogo API.
  • LogoId -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as id field in the QualiLogo API.
  • LogoImageUrl -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as imageUrl field in the QualiLogo API.
  • LogoText -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as name field in the QualiLogo API.
  • LogoUrl -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as url field in the QualiLogo API.
  • Longitude -> Not supported anymore.
  • MakeId -> make.key
  • MakeText -> make.name
  • ModelGroupId -> model.group.key
  • ModelGroupText -> model.group.name
  • ModelId -> model.key
  • ModelText -> model.name
  • ModelTypeText -> versionFullName
  • PayLoad -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as payload field in the Listing Details API.
  • PetrolEquivalent -> Not supported anymore.
  • PetrolEquivalentText -> Not supported anymore.
  • PollutionNormTypeId -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as emissionStandard enumerated field in the Listing Details API.
  • PollutionNormTypeText -> This translation is available in the Translations API.
  • Price -> price
  • PriceNew -> listPrice
  • Properties -> Not supported anymore, fields that represented “properties” are now proper independent fields and are available in the Listing Details API.
  • Seats -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as seats field in the Listing Details API.
  • SegmentationId -> Not supported anymore.
  • SegmentationText -> Not supported anymore.
  • SegmentationTypeId -> transmissionType
  • SegmentationTypeText -> This translation is available in the Translations API.
  • SleepingBerths -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as sleepingBerths field in the Listing Details API.
  • Teaser -> teaser
  • TrailerLoadBreaked -> Not supported anymore, this field is removed due to the low usage and benefit for the buyer.
  • TransmissionShaftId -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as driveSystem field in the Listing Details API.
  • TransmissionShaftText -> This translation is available in the Translations API.
  • TransmissionTypeId -> transmissionType
  • TransmissionTypeText -> This translation is available in the Translations API.
  • TypeName -> versionFullName
  • TypeNameFull -> Not supported anymore.
  • Url -> Not supported anymore, you can link to AS24 page by following url structure: https://www.autoscout24.ch/de/d/{id}
  • UserType -> Not supported anymore.
  • VehicleTags -> Not supported anymore.
  • VehicleType -> vehicleCategory
  • VehicleTypeText -> Not supported anymore.
  • VisibilityId -> Not supported anymore.
  • WarrantyDescription -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as warranty.details field in the Listing Details API.
  • WarrantyMonths -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as warranty.duration field in the Listing Details API.
  • Weight -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as weightCurb field in the Listing Details API.
  • WeightTotal -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as weightTotal field in the Listing Details API.
  • Width -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as width field in the Listing Details API.
  • Documents (array) -> Not supported anymore.
  • Equipment (object) -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as the response of the Listing Equipment API.
  • Images (object) -> images, CDN is supported to fetch different image sizes.
  • PriceHistory (array) -> Not supported anymore.
  • Seller (object)
    • Id -> seller.id
    • Name -> seller.name
    • Street -> seller.address
    • Zip -> seller.zipCode
    • City -> seller.city
    • PoBox -> Not supported anymore.
    • AdditionalInfo -> Not supported anymore.
    • Phone -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as phoneNumber field in the Seller Details API.
    • Mobile -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as phones object in the Seller Details API.
    • Email -> Not present in the Listing Search API as it is not part of the projection used on Search Results Page. This data is available as notificationRecipients object in the Seller Details API. We recommend using Message Lead API for sending message leads.
    • Url -> Not supported anymore.
  • Videos (array) -> Not supported anymore

Details API

Details API returns detailed information about a specific listing, including all the fields that were present in the legacy List API, as well as additional four fields. API is replaced by multiple APIs, which foster better separation of concerns and allow for more efficient data retrieval. The following APIs are available:

  • Listing Details API.
  • Listing Equipment API.
  • Seller Details API.
  • QualiLogo API.

Response:

{
  "AccountId": 2486754,
  "BatteryRentPrice": null,
  "BodyColorId": 59,
  "BodyColorText": "blau",
  "BodyTypeId": 5,
  "BodyTypeText": "Limousine",
  "BootHeight": 0,
  "BootLength": 0,
  "BootVolume": null,
  "BootWidth": 0,
  "CarNumber": null,
  "Ccm": 1368,
  "CertificationCode": null,
  "ChassisCode": null,
  "Co2Emission": 0,
  "Co2EmissionAverage": 137,
  "Co2EmissionAverageText": "137 g/km",
  "Co2EmissionPowerProduction": null,
  "Co2EmissionPowerProductionText": null,
  "Co2EmissionText": null,
  "Comments": "",
  "ConditionTypeId": 49,
  "ConditionTypeText": "Occasion",
  "ConsumptionCity": 0,
  "ConsumptionGas": 0,
  "ConsumptionGasText": null,
  "ConsumptionLand": 0,
  "ConsumptionPower": 0,
  "ConsumptionPowerText": null,
  "ConsumptionRatingText": null,
  "ConsumptionRatingTypeId": -1,
  "ConsumptionTotal": 0,
  "ConsumptionTotalText": null,
  "CylinderDesignTypeId": 55,
  "CylinderDesignTypeText": "Reihe",
  "Cylinders": 4,
  "DateCreated": "/Date(1712153469000+0200)/",
  "DateModified": "/Date(1728999816000+0200)/",
  "DateOfLastInspection": null,
  "DateTopListing": "/Date(1719839781000+0200)/",
  "DealerPrice": 0,
  "Documents": [],
  "Doors": 5,
  "DriveTypeId": 22,
  "DriveTypeText": "Vorderradantrieb",
  "Equipment": {
    "AutoIDatEquipment": null,
    "EurotaxEquipment": null,
    "EurotaxEquipmentUncategorized": null,
    "OptionalEquipmentFlatList": [],
    "SearchableEquipment": [
      "Alufelgen",
      "Automatische Klimaanlage",
      "Bluetooth-Schnittstelle",
      "Differenzialsperre",
      "Eingebautes Navigationssystem",
      "Freisprechanlage",
      "Isofix",
      "Parksensoren hinten",
      "Parksensoren vorne",
      "Stabilitätskontrolle",
      "Start-/Stop-System",
      "Tempomat"
    ],
    "StandardEquipmentFlatList": [
      "Bordcomputer",
      "Zentralverriegelung mit Fernbedienung",
      "Aussentemperaturanzeige",
      "Servolenkung geschwindigkeitsabhängig",
      "Elektrische Fensterheber vorne + hinten",
      "Nebelscheinwerfer",
      "Aussenspiegel in Wagenfarbe",
      "Tempomat",
      "Fahrersitz höhenverstellbar",
      "Heckspoiler",
      "Dachhimmel schwarz",
      "Abgedunkelte Seiten- und Heckscheibe",
      "Reifenreparatur-Set (Tire Fit)",
      "Katalysator geregelt",
      "Antiblockiersystem (ABS)",
      "ISOFIX Kindersitzvorrichtung",
      "Innenlicht-Abschaltverzögerung",
      "Start/Stop-Funktion",
      "Antriebsschlupfregelung (ASR)",
      "Airbag: Window-Kopfairbags",
      "Airbag: Airbag Fahrer und Beifahrer",
      "Airbag: Airbag Beifahrer deaktivierbar",
      "Gurtkontrolle",
      "Bremsassistent (BAS)",
      "3-Punkt-Sicherheitsgurte auf allen Plätzen",
      "2. Schlüssel mit Funkfernbedienung",
      "Airbag: Seitenairbag für Fahrer und Beifahrer",
      "Getriebe: 6-Gang-Getriebe",
      "Leuchtweitenregulierung automatisch",
      "Getönte Scheiben Privacy",
      "Berganfahrhilfe (Hill Holder)",
      "Licht: Drittes Bremslicht",
      "Pedalerie mit Aluminiumauflage",
      "Rücksitzlehne geteilt abklappbar",
      "Klima: 2-Zonen-Klimaautomatik",
      "Regen- und Dämmerungssensor",
      "Leseleuchten",
      "Elektronischer Bremskraftverteilung EBD",
      "Aluminiumeinstiegsleisten",
      "Scheinwerfer abgedunkelt",
      "Dynamische Stabilitätskontrolle (VDC)",
      "Tagesfahrlicht (DRL)",
      "Sicherheitsgurte vorne mit Gurtstraffer",
      "Brandschutzsystem FPS",
      "Alfa Climate Control",
      "Sicherheitsgurte hinten mit Rollautomatik",
      "Garantie: Alfa Garantie: 3 Jahre ohne Kilometerbegrenzung (ab 1. Inv.)",
      "Electronic Q2: Innovatives Vorderachs-Sperrdifferenzial für mehr aktive Sicherheit",
      "Elektrisch verstell-, beheizbare und manuell einklappbare Aussenspiegel",
      "Hill Holder",
      "Kopfstützen vorne (mit Schleudertraumaschutz), hinten höhenverstellbar",
      "Assist: Parksensoren vorne und hinten mit akustischer Warnmeldung",
      "Multifunktionslenkrad in Leder mit Schaltelementen für Radio und Telefon",
      "Licht: ''Follow Me Home'' Scheinwerferanlage",
      "Armaturenbrett und Türfüllungen in Carbon-Optik Ausführung",
      "Sport-Stossfänger hinten",
      "Räder: 18\"-Leichtmetallfelgen im Doppelspeichendesign mit Diamanteffekt und 225/40-Bereifung",
      "Sonnenblende Beifahrer mit Spiegel und integrierter Beleuchtung mit Cupholder",
      "Media:Uconnect Navigationssystem mit 3D-Kartendarstellung, Bluetooth-Verbindung, 6,5\"-Touchscreen,"
    ]
  },
  "Extras": null,
  "FirstRegMonth": 11,
  "FirstRegYear": 2020,
  "FuelTypeId": 14,
  "FuelTypeText": "Benzin",
  "HasWarranty": false,
  "Height": 1450,
  "Hp": 120,
  "Id": 8678620,
  "Images": {
    "S": null,
    "M": null,
    "L": null,
    "XL": null,
    "Original": null
  },
  "ImagesCount": 0,
  "ImagesThreeSixty": null,
  "InteriorColorId": -1,
  "InteriorColorText": null,
  "Km": 456,
  "Kw": 88,
  "Latitude": 46.85634,
  "LeasingCalculatorUrl": "",
  "Length": 4351,
  "LicenseCategoryText": "B",
  "LicenseCategoryTypeId": 33,
  "LogoDescription": null,
  "LogoId": 0,
  "LogoImageUrl": null,
  "LogoText": null,
  "LogoUrl": null,
  "Longitude": 9.52676,
  "MakeId": 2,
  "MakeText": "ALFA ROMEO",
  "ModelGroupId": null,
  "ModelGroupText": null,
  "ModelId": 15,
  "ModelText": "GIULIETTA",
  "ModelTypeText": "Giulietta 1.4 Turbo Sprint",
  "PayLoad": 326,
  "PetrolEquivalent": null,
  "PetrolEquivalentText": null,
  "PollutionNormTypeId": 238,
  "PollutionNormTypeText": "Euro 6d",
  "Price": 456,
  "PriceHistory": [],
  "PriceNew": 27300,
  "Properties": null,
  "Seats": 5,
  "SegmentationId": -1,
  "SegmentationText": null,
  "SegmentationTypeId": -1,
  "SegmentationTypeText": null,
  "Seller": {
    "Id": 1978780,
    "Name": "test",
    "Street": "Bahnhoffstrasse 50",
    "Zip": "4234",
    "City": "Zurich",
    "PoBox": "",
    "AdditionalInfo": null,
    "Phone": "+41-441234456",
    "Mobile": "+41-441234456",
    "Email": "[email protected]",
    "Url": null
  },
  "SleepingBerths": 0,
  "Teaser": null,
  "TrailerLoadBreaked": 1300,
  "TransmissionShaftId": -1,
  "TransmissionShaftText": null,
  "TransmissionTypeId": 20,
  "TransmissionTypeText": "Schaltgetriebe manuell",
  "TypeName": "Giulietta 1.4 Turbo Sprint",
  "TypeNameFull": "ALFA ROMEO Giulietta 1.4 Turbo Sprint",
  "Url": "https://int.autoscout24.ch/api/hci/v3/json/Vehicles/8678620?lng=de&member=60601&cuid=60601",
  "UserType": 3,
  "VehicleTags": null,
  "VehicleType": 10,
  "VehicleTypeText": "Personenwagen",
  "Videos": [],
  "VisibilityId": 0,
  "WarrantyDescription": "",
  "WarrantyMonths": 0,
  "Weight": 1459,
  "WeightTotal": 1785,
  "Width": 1798,
  "BatteryCapacity": null,
  "BatteryRange": null,
  "HpCombustionEngine": 120,
  "HpElectro": null
}
Fields mapping

Mapping is the same as in the List API, and additional four fields are mapped as follows:

  • BatteryCapacity -> batteryCapacity in Listing Details API.
  • BatteryRange -> range in Listing Details API.
  • HpCombustionEngine -> combustionEngineHorsePower in Listing Details API.
  • HpElectro -> electricMotorHorsePower in Listing Details API.

FAQ - Frequently Asked Questions

  • Which facets are available?
    • All facets that are available can be found listed in the Facets API OpenApi specification and can be seen in schema on Swagger UI.
  • Is there any way to get a list of all sellers for the specified seller group?
    • Currently, there is no API that provides sellers based on the provided seller group.
  • How do I know if API is supporting pagination?
    • If API supports pagination, it will have page and size query parameters, or pagination object in the request body. Most of the APIs that return a list of items support pagination. You can find out if API supports pagination by checking the OpenApi specification of the API, or by checking the Swagger UI schema.
  • Why do I get paginated response even if I do not provide pagination parameters?
    • If API supports pagination, it will always return paginated response, even if you do not provide pagination parameters. The default pagination values are defined in OpenApi specification of the API, usually page = 0, size = 20. This is done to ensure that the response is not too large and can be processed efficiently.