Zum Inhalt springen

API-Referenz V2 (Beta) und V1

API-Dokumentation

Alle Endpunkte, Parameter und Antwortfelder der api4cars-API V2. REST mit JSON-Antworten, Beispiele für cURL und JavaScript. Die bisherige API V1 ist weiter dokumentiert.

Basis-URL
https://api.api4cars.com/v2/ · openapi.json
Authentifizierung
ck_v2_… + X-API-Secret oder Bearer key:secret, immer von deinem Server
Kontingent
je Tarif pro Monat, gemeinsam für alle Schlüssel deines Kontos (V1 + V2), Header X-RateLimit-*, ohne freigeschalteten Mehrverbrauch nach Erschöpfen HTTP 429 mit Retry-After

BetaAPI V2 ist in der Beta. Endpunkte und Felder können wir noch erweitern oder anpassen. Änderungen, die bestehende Integrationen betreffen, kündigen wir vorher an. V1 bleibt bis auf Weiteres verfügbar. Was Beta bedeutet

API V2 ist die aktuelle API. Neue Integrationen baust du hier. Du nutzt noch V1? Was sich ändert und wie du umsteigst, steht auf der Seite Umstieg auf API V2.

Zum Umstieg
Referenz

api4cars API V2

openapi.json

Einführung

Die api4cars API V2 liefert Fahrzeugdaten für den deutschen Markt und darauf aufbauend Felgenangebote mit Reifen, Auflagen und Gutachten. Alle Endpunkte sind GET-Anfragen und antworten mit JSON. Fahrzeug- und Anzeigedaten sind deutsch; maschinenlesbare Felder tragen stabile Codes. Jede Antwort nennt den aktiven Datenstand in meta.data_version.

Basis-URL: https://api.api4cars.com, alle Pfade beginnen mit /v2/. Die maschinenlesbare Beschreibung (OpenAPI 3, Version 2.0.0) liegt unter https://api.api4cars.com/v2/openapi.json – daraus kannst du dir Typen oder einen eigenen Client erzeugen. Alle Endpunkte, Parameter, Felder und Fehler dieser Seite sind aus ihr erzeugt.

Begriffe

BegriffKennungBedeutung
Fahrzeugvehicle_id = HSN-TSNHerstellerschlüsselnummer (4 Ziffern) und Typschlüsselnummer (3 Zeichen), mit Bindestrich, z. B. 0603-COB.
Auswahlselection_idEine Variante (var_…), EU-Konfiguration (cfg_…), ein mehrdeutiger ersetzter Schlüssel (als_…) oder eine Ausführung (exe_…) innerhalb eines Fahrzeugs. Das Präfix der Kennung und das Feld kind nennen die Art. Eine Auswahl grenzt die Felgenangebote ein (selection). Eine Ausführung mit genau einer Variante wirkt wie diese Variante; hat sie mehrere, gilt das Ergebnis ohne Auswahl (meta.selection.status = ambiguous). meta.selection.applied_ids nennt, was tatsächlich angewendet wurde.
Angebotoffer_idEine Felge (Code, Breite, Durchmesser, ET) mit Passungsstatus für das Fahrzeug.
Gutachtendocument_id (doc_…)Teilegutachten oder ABE mit Auflagentexten und Link zur PDF-Datei.
Passungsstatusstatusno_registration (eintragungsfrei), registration_required (mit Eintragung), unknown (unklar), not_fitting (passt nicht).

Alle Endpunkte

API V2 hat 26 Pfade. Alle sind GET; /v2/status und /v2/openapi.json brauchen keinen Schlüssel.

PfadLiefert
/v2/statusService status and active data release
/v2/meOwn API key: monthly quota and usage
/v2/me/usageOwn API key: requests per day and endpoint
/v2/openapi.jsonThis description
/v2/brandsBrands
/v2/brands/{brand_id}/modelsModels of a brand
/v2/brands/{brand_id}/models/{model_id}/generationsGenerations of a model, with executions
/v2/generations/{generation_id}/enginesEngines of a generation with their vehicles and selections
/v2/vehiclesSearch vehicle variants by name, body, powertrain, dimensions, production year and towing capacity
/v2/vehicles/{vehicle_id}Vehicle with selections
/v2/vehicle-listVehicles (HSN/TSN) of a brand, model or bolt pattern
/v2/insuranceInsurance type classes of all vehicles of a brand or model
/v2/vehicles/{vehicle_id}/technicalTechnical profile per variant: dimensions, weights, towing, powertrain, engines with fluid capacities and axle loads
/v2/vehicles/{vehicle_id}/configurationsEU configurations of a vehicle
/v2/vehicles/{vehicle_id}/wheelsWheel offers for a vehicle
/v2/vehicles/{vehicle_id}/wheels/{wheel_code}One wheel on a vehicle (all offsets and documents)
/v2/engine-codesEngine codes with power range and number of vehicles
/v2/engine-codes/{engine_code}/vehiclesVehicle variants with this engine code
/v2/wheelsWheel catalog
/v2/wheels/{wheel_code}Catalog wheel with colors, images, variants and documents
/v2/vehicles/{vehicle_id}/imagesConfigurator image sets for a vehicle (add-on module)
/v2/vehicles/{vehicle_id}/images/{wheel_code}Configurator images of one wheel, paint and finish on a vehicle (add-on module)
/v2/vehicle-images/{vehicle_image_id}One configurator image group with its published wheels (add-on module)
/v2/vehicle-images/{vehicle_image_id}/{wheel_code}Configurator images of one wheel, paint and finish in an image group (add-on module)
/v2/documentsApproval documents (Gutachten) per wheel code: geometries, obligation codes, fasteners and link
/v2/documents/{document_id}Approval document (Gutachten) with obligation texts and link

Authentifizierung

Wie bei V1 bekommst du einen Schlüssel und ein Secret; V2-Schlüssel beginnen mit ck_v2_…. Jede Anfrage trägt den Schlüssel im Header X-API-Key und das Secret im Header X-API-Secret; alternativ geht Authorization: Bearer KEY:SECRET.

Rufe die API immer von deinem eigenen Server aus auf. Das Secret gehört nie in Browser-Code, in eine App oder in ein Repository. Soll deine Website Fahrzeug- oder Felgendaten zeigen, fragt dein Server die API ab und gibt das Ergebnis an deine Seite weiter.

# Schlüssel und Secret als Header
curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles/0603-COB"

# Alternativ als Bearer-Token
curl -H "Authorization: Bearer $A4C_KEY:$A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles/0603-COB"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicles/0603-COB', {
  headers: {
    'X-API-Key': process.env.A4C_KEY,       // ck_v2_…
    'X-API-Secret': process.env.A4C_SECRET
  }
});
const { data, meta } = await res.json();

API V2 steht allen Kunden offen. Nach der Registrierung legst du deinen V2-Schlüssel selbst im Konto an; das Secret wird einmal angezeigt. Ohne eigenen Schlüssel kannst du Anfragen in der Sandbox ausprobieren.


Antwort, Seiten, Datenstand

  • Antwortform: { "data": …, "meta": { "api_version": 2, "data_version": "…" } }; bei Listen zusätzlich meta.next_cursor, Felgenangebote bringen included mit (Sätze und Gutachten).
  • Quellenangabe: Antworten, die KBA-Daten verwenden, tragen ein Feld attribution (Lizenz dl-de/by-2-0). Gibst du die Daten weiter oder zeigst du sie an, nenne diese Quelle mit.
  • Seiten: Listen arbeiten mit Cursor. limit legt die Seitengröße fest (Grenzen und Standard stehen je Endpunkt in der Parametertabelle), die nächste Seite holst du mit cursor aus meta.next_cursor. Ist next_cursor null, bist du am Ende. Eine Gesamtzahl steht nur dort in meta.total, wo der Endpunkt sie in den Feldern von meta nennt.
  • Datenstand festhalten: Gib data_version als Parameter mit; weicht der aktive Datenstand ab, antwortet die API mit 409. So mischst du beim Blättern keine zwei Datenstände.
  • Fehlende Werte: Felder ohne Wert fehlen in der Antwort, außer die Feldtabelle nennt null als möglichen Wert (z. B. next_cursor). Zeigst du die Daten an, kennzeichne Lücken sichtbar statt sie zu ersetzen.
  • Caching: Für Datenrouten kannst du den ETag bei derselben Anfrage als If-None-Match senden: Bei unveränderter Antwort folgt 304 ohne Body. Verwende dann deinen gespeicherten Body und rufe nicht res.json() auf. Ausnahme Verbrauch: /v2/me und /v2/me/usage immer frisch ohne If-None-Match abrufen; keinen gespeicherten Body wiederverwenden. Dort kann sich der Verbrauch trotz gleichem ETag ändern. Falls 304 kommt, ohne diesen Header erneut abrufen. Auch ein authentifizierter Abruf mit 304 zählt zum Verbrauch. Die feste OpenAPI-Datei ist von diesem ETag-Verfahren ausgenommen.
# Erste Seite
curl -H "X-API-Key: $A4C_KEY" -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/wheels?limit=100"

# Nächste Seite: cursor aus meta.next_cursor, Datenstand festhalten
curl -H "X-API-Key: $A4C_KEY" -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/wheels?limit=100&cursor=CURSOR&data_version=DATA_VERSION"
// Alle Seiten einer Liste lesen (auf deinem Server)
const headers = { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET };
let cursor = null, version = null;
const all = [];
do {
  const url = new URL('https://api.api4cars.com/v2/wheels');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  if (version) url.searchParams.set('data_version', version);
  const { data, meta } = await (await fetch(url, { headers })).json();
  all.push(...data);
  version = meta.data_version;
  cursor = meta.next_cursor;
} while (cursor);

Kontingent und Rate-Limit

Dein Konto hat ein Monatskontingent (je Tarif). Alle Schlüssel deines Kontos zählen zusammen dagegen, Anfragen an API V1 eingerechnet. Dazu kommt eine kurzzeitige Begrenzung. Bei erfolgreich authentifizierten Anfragen mit begrenztem Kontingent zeigen diese Header den Stand:

HeaderBedeutung
X-RateLimit-LimitMonatskontingent deines Kontos (V1 und V2 gemeinsam), keine kurzfristige Ratenbegrenzung
X-RateLimit-RemainingVerbleibende Anfragen im Monatskontingent
Retry-AfterBei 429: Sekunden, bis du es erneut versuchen kannst

Mehrverbrauch über das Monatskontingent hinaus schalten wir auf Anfrage für dein Konto frei.

Ist das Monatskontingent verbraucht, folgt 429 rate_limited nur ohne freigeschalteten Mehrverbrauch. Mit freigeschaltetem Mehrverbrauch werden ansonsten gültige Anfragen weiter mit 200 beantwortet. Die getrennte kurzzeitige Begrenzung (100 Anfragen je 10 Sekunden je Schlüssel) gilt weiterhin und antwortet mit 429 too_many_requests. Beachte bei 429 jeweils Retry-After. Monatsverbrauch und Rest liefert GET /v2/me, deine Anfragen je Tag und Endpunkt GET /v2/me/usage; beide frisch ohne If-None-Match abrufen und keinen gespeicherten Body wiederverwenden.

# -i zeigt die Antwort-Header mit X-RateLimit-*
curl -i -H "X-API-Key: $A4C_KEY" -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/brands"
const res = await fetch('https://api.api4cars.com/v2/brands', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
console.log(res.headers.get('X-RateLimit-Remaining'));
if (res.status === 429) {
  const wait = Number(res.headers.get('Retry-After') || 60);
  // nach „wait“ Sekunden erneut versuchen
}

JS-Client

Für Node ≥ 18 auf deinem Server gibt es einen kleinen JavaScript-Client ohne Abhängigkeiten. Er setzt die Header, liest X-RateLimit-* mit, wirft bei Fehlern einen Api4CarsError (mit status, code, details, retryAfter) und blättert Listen über meta.next_cursor. Du kannst die Datei herunterladen und in dein Projekt legen.

import { Api4Cars } from './api4cars-v2.mjs';

// Auf deinem Server: Schlüssel und Secret aus der Umgebung
const api = new Api4Cars({ key: process.env.A4C_KEY, secret: process.env.A4C_SECRET });

const brands  = await api.brands({ withFitments: true, withLogo: true });
const vehicle = await api.vehicle('0603-COB');
const offers  = await api.vehicleWheels('0603-COB', { view: 'full', limit: 20 });

for await (const wheel of api.paginate(cursor => api.catalog({ cursor }))) {
  console.log(wheel.wheel_code);
}

Methoden: paginate(), status(), me(), usage(), brands(), models(), generations(), engines(), vehicle(), configurations(), technical(), insurance(), searchVehicles(), engineCodes(), engineCodeVehicles(), vehicleWheels(), vehicleWheel(), catalog(), catalogWheel(), document(), documents(), vehicleImages(), vehicleImage(), imageGroup(), imageGroupImage().


Navigation: Marke bis Motor

So führst du Nutzer ohne Fahrzeugschein zum Fahrzeug: Marke → Modell → Generation (mit Ausführung) → Motor. Die Motorliste nennt je Motor die Fahrzeuge (vehicles[].id = HSN-TSN) und die zugehörigen Auswahlen.

GET /v2/brands

Brands

Parameter

NameOrtTypPflichtBeschreibung
with_fitmentsQuerystring
Werte: 0, 1
neinOnly brands with wheel assignments.
with_logoQuerystring
Werte: 0, 1
neinOnly brands with a logo.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
idstringja
namestringja
vehicle_countintegernein
with_fitments_countintegernein
logo_urlstringnein

Mögliche Fehlerstatus: 400, 401, 403, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/brands"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/brands', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "id": "bmw",
      "name": "BMW",
      "vehicle_count": 1234,
      "with_fitments_count": 980,
      "logo_url": "https://cdn.example/brand-logos/bmw.jpeg"
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

GET /v2/brands/{brand_id}/models

Models of a brand

Parameter

NameOrtTypPflichtBeschreibung
brand_idPfadstringjaBrand id from /v2/brands.
with_fitmentsQuerystring
Werte: 0, 1
neinOnly models with wheel assignments.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
idstringja
namestringja
with_fitments_countintegernein

Mögliche Fehlerstatus: 400, 401, 403, 404, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/brands/{brand_id}/models"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/brands/{brand_id}/models', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "id": "3er-reihe",
      "name": "3er-Reihe",
      "with_fitments_count": 120
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

GET /v2/brands/{brand_id}/models/{model_id}/generations

Generations of a model, with executions

Parameter

NameOrtTypPflichtBeschreibung
brand_idPfadstringjaBrand id.
model_idPfadstringjaModel id.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
idstringja
namestringja
yearsstringnein
brand_idstringnein
model_idstringnein
executionsobject[]nein
executions[].idstringja
executions[].labelstringnein
executions[].body_typestringnein
executions[].body_type_codestringneinWerte: hatchback, estate, sedan, suv, van, coupe, convertible, pickup
executions[].engine_countintegernein

Mögliche Fehlerstatus: 400, 401, 403, 404, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/brands/{brand_id}/models/{model_id}/generations"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/brands/{brand_id}/models/{model_id}/generations', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "id": "gen_0123456789abcdef",
      "name": "G20",
      "years": "2018 - heute",
      "brand_id": "bmw",
      "model_id": "3er-reihe",
      "executions": [
        {
          "id": "e1",
          "label": "Limousine",
          "body_type": "Limousine",
          "body_type_code": "sedan",
          "engine_count": 12
        }
      ]
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

GET /v2/generations/{generation_id}/engines

Engines of a generation with their vehicles and selections

Parameter

NameOrtTypPflichtBeschreibung
generation_idPfadstring
Muster: ^gen_[a-f0-9]{16}$
jaGeneration id.
executionQuerystringneinExecution id from the generation.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
namestringnein
labelstringnein
engine_namesstring[]nein
power_kwnumbernein
power_psnumbernein
fuelstringnein
fuel_codestringneinWerte: petrol, diesel, electric, hybrid, plugin_hybrid, hydrogen, cng, lpg
drivetrainstringnein
drivetrain_codestringneinWerte: fwd, rwd, awd
derived_from_variantsstring[]neinFields that the catalog did not name for this engine group and that were set because every variant of every vehicle of the group carries the same value (the value shown on the vehicle's selections). Absent when nothing was derived; a field without a unanimous value stays missing.
Werte: fuel, drivetrain
transmissionsstring[]nein
transmission_codesstring[]neinWerte: manual, automatic, dual_clutch, automated_manual, cvt, single_speed
yearsstringneinProduction period of the engine choice as one range: earliest start to latest end of all periods ("MM/YY - MM/YY"; an open end is "MM/YY - -"). Gaps between periods are not shown here; see periods.
year_fromstringneinEarliest start in the granularity of the periods ("YYYY-MM" for MM/YY periods, "YYYY" for year periods). Absent when the periods cannot be summarised.
year_tostringneinLatest end in the same granularity. Absent when the end is open or the periods cannot be summarised.
periodsstring[]neinAll source periods of the engine choice (unchanged).
executionobjectnein
execution.idstringja
execution.labelstringnein
execution.body_typestringnein
execution.body_type_codestringneinWerte: hatchback, estate, sedan, suv, van, coupe, convertible, pickup
execution.engine_countintegernein
selection_requiredbooleannein
vehiclesobject[]nein
vehicles[].idstringja
vehicles[].selectionsstring[]nein
vehicles[].selection_requiredbooleannein

Mögliche Fehlerstatus: 400, 401, 403, 404, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/generations/{generation_id}/engines"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/generations/{generation_id}/engines', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "name": "330e",
      "label": "330e",
      "power_kw": 135,
      "fuel": "Hybrid",
      "fuel_code": "hybrid",
      "drivetrain": "Hinterrad",
      "drivetrain_code": "rwd",
      "transmissions": "…",
      "transmission_codes": "…",
      "years": "07/19 - 06/22",
      "year_from": "2019-07",
      "year_to": "2022-06",
      "periods": "…",
      "execution": "…",
      "vehicles": "…"
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

Fahrzeug

GET /v2/vehicles/{vehicle_id}

Vehicle with selections

Parameter

NameOrtTypPflichtBeschreibung
vehicle_idPfadstring
Muster: ^[0-9]{4}-[A-Z0-9]{3}$
jaHSN-TSN, e.g. 0005-DFY.
selectionQuerystringneinSelection id from the vehicle (var_…, als_…, exe_…, cfg_…). The chosen selection is returned as selected; for a variant the bolt pattern and center bore are those of the variant and include=data_sheet is narrowed to the data sheets of the variant. meta.selection tells what was applied.
includeQuerystringneinComma-separated list of extra blocks, any of: insurance, market, market_history, safety, environment, data_sheet (e.g. include=market,safety). insurance: insurance type classes (liability, partial and full comprehensive) with annual values; insurance_unavailable when none are known. market, safety, environment: official statistics and recalls for this vehicle. market_history: the stock of exactly this HSN/TSN per year (1 January) and its trend. intelligence_unavailable when the data release has none of the requested sections. data_sheet: technical data sheet with numeric values and the unit in the field name; data_sheet_unavailable when none is known. vehicle_image: preview image of the vehicle for configurators (signed link, valid at least one hour; expires_at). sections: which detail sections have content for this vehicle (workshop, market, recalls). An unknown value gives 400 invalid_include.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
vehicle_idstringja
hsnstringja
tsnstringja
brandstringnein
modelstringnein
yearsstringnein
displayobjectnein
identity_onlybooleannein
brand_idstringneinBrand id as in /v2/brands (only when the brand is unambiguous).
brand_logo_urlstringneinPublic logo of the brand (same file as logo_url in /v2/brands).
Format: uri
wheelsobjectnein
wheels.pcdstringnein
wheels.pcd_statusstringneinWerte: verified, unverified, missing
wheels.center_bore_mmnumbernein
wheels.center_bore_statusstringneinWerte: verified, unverified, missing
wheels.threadstringnein
wheels.torque_nmnumbernein
wheels.fastenerstringnein
wheels.fastener_codestringneinWerte: bolts, nuts
wheels.mountingobjectnein
tpmsobjectnein
oe_tiresobject[]nein
factory_wheelsobjectneinFactory wheels from the certificate of conformity: references and wheel/tyre options; staggered = different front/rear size. Empty values are omitted.
factory_wheels.referencesstring[]nein
factory_wheels.optionsobject[]nein
has_wheelsbooleannein
wheels_unavailablestringnein
selectionsobject[]nein
selections[].selection_idstringja
selections[].kindstringjaWerte: variant, configuration, alias, execution
selections[].labelstringneinVariants and executions: display name.
selections[].variant_selection_idsstring[]neinExecutions only: the variants (var_…) of this execution on the vehicle. One entry = the execution is applied like that variant.
selections[].variant_selection_idstringneinConfigurations only: linked variant selection, when documented. Keep its technical profile separate from the configuration observations.
selections[].technical_observationsobject[]neinConfigurations only: documented technical values of this EU configuration (value or minimum/maximum, unit, basis). confirmed=false marks a value that is not confirmed by further data; confirmed values carry no such field.
selections[].approval_observationsobject[]neinConfigurations only: reported withdrawal records of the type approval.
selections[].approval_validitystringneinWerte: not_determined
selections[].registration_observationsobject[]neinConfigurations only: annual registration statistics (documented counts and measured values).
configuration_countintegernein
insuranceobjectneinInsurance type classes per HSN/TSN (include=insurance and /v2/insurance). All classes are integers; a value that is not a whole number in the data is omitted, never guessed. Empty values are omitted.
insurance.liabilityintegerneinCurrent liability (third-party) type class.
min 0
insurance.partial_comprehensiveintegerneinCurrent partial comprehensive type class.
min 0
insurance.full_comprehensiveintegerneinCurrent full comprehensive type class.
min 0
insurance.yearintegerneinYear of the current type classes: the latest year (YYYY) in history across all lines. Omitted without history.
min 1900
insurance.historyobjectneinType class per line and year (key YYYY).
insurance_unavailablestringneinOnly with include=insurance: no insurance type classes are known for this vehicle.
Werte: no_type_classes
marketobjectneininclude=market: newest figure per metric for this vehicle; never brand, region or class aggregates.
market.latestobject[]ja
market.scopestringja
market.reasonstringneinWhy latest is empty.
market_historyobjectneininclude=market_history: stock of exactly this HSN/TSN per year (official count on 1 January) and the trend calculated from these counts. Empty values are omitted; a figure whose years are not in the series is left out, never estimated.
market_history.availablebooleanja
market_history.scopestringja
market_history.hsn_tsn_exactbooleannein
market_history.registration_historyobject[]neinRegistered vehicles of this HSN/TSN per year, oldest first.
market_history.registration_trendobjectneinChange of the stock in percent, calculated from registration_history.
market_history.reasonstringneinWhy nothing is available.
safetyobjectneininclude=safety: recalls of the validated model (up to 200, newest first) and exact safety figures.
safety.availablebooleanja
safety.scopestringja
safety.hsn_tsn_exactbooleanja
safety.recall_countintegerjamin 0
safety.recallsobject[]ja
safety.factsobject[]nein
safety.reasonstringneinWhy nothing is available.
environmentobjectneininclude=environment: only figures that refer exactly to this HSN/TSN.
environment.availablebooleanja
environment.scopestringja
environment.hsn_tsn_exactbooleanja
environment.latestobject[]ja
environment.reasonstringneinWhy nothing is available.
intelligence_unavailablestringneinOnly with include=market, market_history, safety or environment: the active data release has none of the requested sections.
Werte: not_in_release
data_sheetobjectneininclude=data_sheet. Numbers are numbers; the unit is part of the field name. Values that cannot be read exactly are omitted, never guessed.
data_sheet.sheetsobject[]neinOne data sheet per VSN.
data_sheet.factsobjectneinVehicle facts by name (e.g. length_mm, curb_weight_kg, drivetrain). values only when status is confirmed.
data_sheet_unavailablestringneinOnly with include=data_sheet: no data sheet is known for this vehicle.
Werte: no_data_sheet
vehicle_imageobjectneinOnly with include=vehicle_image.
vehicle_image.availablebooleanja
vehicle_image.ambiguousbooleanja
vehicle_image.delivery_readybooleanja
vehicle_image.vehicle_image_idstring | nullnein
vehicle_image.labelstring | nullnein
vehicle_image.thumbnailobject | nullnein
vehicle_image.body_matchstring | nullneinWerte: exact, unconfirmed, differs, missing, null
vehicle_image.body_noticeobject | nullnein
vehicle_image.matchesobject[]nein
selectedobjectneinOnly with the selection parameter: the applied selection (as in selections).
available_sectionsobjectneinOnly with include=sections: which detail sections have content for this vehicle.
available_sections.workshopbooleanjaFluid capacities in /technical.
available_sections.marketbooleanjaOfficial market figures (include=market).
available_sections.recallsbooleanjaRecalls (include=safety).

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Felder in meta

NameTypImmer vorhandenBeschreibung
selectionobjectneinOnly with the selection parameter: as meta.selection of the wheel endpoints.

Mögliche Fehlerstatus: 400, 401, 403, 404, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles/0005-DFY"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicles/0005-DFY', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "vehicle_id": "0005-DFY",
    "hsn": "0005",
    "tsn": "DFY",
    "brand": "BMW",
    "model": "3er",
    "brand_id": "bmw",
    "brand_logo_url": "https://cdn.example/brand-logos/bmw.jpeg",
    "wheels": "…",
    "has_wheels": true,
    "selections": "…",
    "configuration_count": 1,
    "insurance": "…",
    "market": "…",
    "safety": "…",
    "environment": "…",
    "market_history": "…",
    "data_sheet": "…",
    "vehicle_image": "…",
    "available_sections": "…"
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  },
  "attribution": [
    "…"
  ]
}

GET /v2/vehicle-list

Vehicles (HSN/TSN) of a brand, model or bolt pattern

Call it from your server with your key and secret. One entry per published vehicle, ordered by HSN and TSN, in the same form as /v2/vehicles/{vehicle_id} without selections. Needs at least one filter. Brand and model match like /v2/insurance; pcd matches the stored bolt pattern exactly (case-insensitive).

Parameter

NameOrtTypPflichtBeschreibung
brandQuerystring
Länge ≥ 1
neinBrand name (known spellings of the same brand match, case and accents ignored) or brand id from /v2/brands.
modelQuerystring
Länge ≥ 1
neinModel field of the vehicle contains this text (case and accents ignored).
model_idQuerystring
Muster: ^[a-z0-9-]{1,120}$
neinModel id from /v2/brands/{brand_id}/models; needs brand = the brand id.
pcdQuerystring
Länge ≥ 1
neinBolt pattern, e.g. 5x112.
limitQueryinteger
min 1
max 100
neinPage size (default 50).
cursorQuerystringneinOpaque cursor from meta.next_cursor.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
vehicle_idstringja
hsnstringja
tsnstringja
brandstringnein
modelstringnein
yearsstringnein
displayobjectnein
identity_onlybooleannein
brand_idstringneinBrand id as in /v2/brands (only when the brand is unambiguous).
brand_logo_urlstringneinPublic logo of the brand (same file as logo_url in /v2/brands).
Format: uri
wheelsobjectnein
wheels.pcdstringnein
wheels.pcd_statusstringneinWerte: verified, unverified, missing
wheels.center_bore_mmnumbernein
wheels.center_bore_statusstringneinWerte: verified, unverified, missing
wheels.threadstringnein
wheels.torque_nmnumbernein
wheels.fastenerstringnein
wheels.fastener_codestringneinWerte: bolts, nuts
wheels.mountingobjectnein
tpmsobjectnein
oe_tiresobject[]nein
factory_wheelsobjectneinFactory wheels from the certificate of conformity: references and wheel/tyre options; staggered = different front/rear size. Empty values are omitted.
factory_wheels.referencesstring[]nein
factory_wheels.optionsobject[]nein
has_wheelsbooleannein
wheels_unavailablestringnein
selectionsobject[]nein
selections[].selection_idstringja
selections[].kindstringjaWerte: variant, configuration, alias, execution
selections[].labelstringneinVariants and executions: display name.
selections[].variant_selection_idsstring[]neinExecutions only: the variants (var_…) of this execution on the vehicle. One entry = the execution is applied like that variant.
selections[].variant_selection_idstringneinConfigurations only: linked variant selection, when documented. Keep its technical profile separate from the configuration observations.
selections[].technical_observationsobject[]neinConfigurations only: documented technical values of this EU configuration (value or minimum/maximum, unit, basis). confirmed=false marks a value that is not confirmed by further data; confirmed values carry no such field.
selections[].approval_observationsobject[]neinConfigurations only: reported withdrawal records of the type approval.
selections[].approval_validitystringneinWerte: not_determined
selections[].registration_observationsobject[]neinConfigurations only: annual registration statistics (documented counts and measured values).
configuration_countintegernein
insuranceobjectneinInsurance type classes per HSN/TSN (include=insurance and /v2/insurance). All classes are integers; a value that is not a whole number in the data is omitted, never guessed. Empty values are omitted.
insurance.liabilityintegerneinCurrent liability (third-party) type class.
min 0
insurance.partial_comprehensiveintegerneinCurrent partial comprehensive type class.
min 0
insurance.full_comprehensiveintegerneinCurrent full comprehensive type class.
min 0
insurance.yearintegerneinYear of the current type classes: the latest year (YYYY) in history across all lines. Omitted without history.
min 1900
insurance.historyobjectneinType class per line and year (key YYYY).
insurance_unavailablestringneinOnly with include=insurance: no insurance type classes are known for this vehicle.
Werte: no_type_classes
marketobjectneininclude=market: newest figure per metric for this vehicle; never brand, region or class aggregates.
market.latestobject[]ja
market.scopestringja
market.reasonstringneinWhy latest is empty.
market_historyobjectneininclude=market_history: stock of exactly this HSN/TSN per year (official count on 1 January) and the trend calculated from these counts. Empty values are omitted; a figure whose years are not in the series is left out, never estimated.
market_history.availablebooleanja
market_history.scopestringja
market_history.hsn_tsn_exactbooleannein
market_history.registration_historyobject[]neinRegistered vehicles of this HSN/TSN per year, oldest first.
market_history.registration_trendobjectneinChange of the stock in percent, calculated from registration_history.
market_history.reasonstringneinWhy nothing is available.
safetyobjectneininclude=safety: recalls of the validated model (up to 200, newest first) and exact safety figures.
safety.availablebooleanja
safety.scopestringja
safety.hsn_tsn_exactbooleanja
safety.recall_countintegerjamin 0
safety.recallsobject[]ja
safety.factsobject[]nein
safety.reasonstringneinWhy nothing is available.
environmentobjectneininclude=environment: only figures that refer exactly to this HSN/TSN.
environment.availablebooleanja
environment.scopestringja
environment.hsn_tsn_exactbooleanja
environment.latestobject[]ja
environment.reasonstringneinWhy nothing is available.
intelligence_unavailablestringneinOnly with include=market, market_history, safety or environment: the active data release has none of the requested sections.
Werte: not_in_release
data_sheetobjectneininclude=data_sheet. Numbers are numbers; the unit is part of the field name. Values that cannot be read exactly are omitted, never guessed.
data_sheet.sheetsobject[]neinOne data sheet per VSN.
data_sheet.factsobjectneinVehicle facts by name (e.g. length_mm, curb_weight_kg, drivetrain). values only when status is confirmed.
data_sheet_unavailablestringneinOnly with include=data_sheet: no data sheet is known for this vehicle.
Werte: no_data_sheet
vehicle_imageobjectneinOnly with include=vehicle_image.
vehicle_image.availablebooleanja
vehicle_image.ambiguousbooleanja
vehicle_image.delivery_readybooleanja
vehicle_image.vehicle_image_idstring | nullnein
vehicle_image.labelstring | nullnein
vehicle_image.thumbnailobject | nullnein
vehicle_image.body_matchstring | nullneinWerte: exact, unconfirmed, differs, missing, null
vehicle_image.body_noticeobject | nullnein
vehicle_image.matchesobject[]nein
selectedobjectneinOnly with the selection parameter: the applied selection (as in selections).
available_sectionsobjectneinOnly with include=sections: which detail sections have content for this vehicle.
available_sections.workshopbooleanjaFluid capacities in /technical.
available_sections.marketbooleanjaOfficial market figures (include=market).
available_sections.recallsbooleanjaRecalls (include=safety).

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Felder in meta

NameTypImmer vorhandenBeschreibung
totalintegernein
engine_codestringnein
facetsobjectnein

Mögliche Fehlerstatus: 400, 401, 403, 404, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicle-list"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicle-list', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "vehicle_id": "0005-DFY",
      "hsn": "0005",
      "tsn": "DFY",
      "brand": "BMW",
      "model": "3er",
      "wheels": "…",
      "has_wheels": true
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null,
    "total": 1
  },
  "attribution": [
    {
      "source": "kba",
      "publisher": "Kraftfahrt-Bundesamt (KBA)",
      "license": "…",
      "note": "Daten verändert: eigene Berechnungen auf Grundlage von Daten des Kraftfahrt-B…"
    }
  ]
}

GET /v2/vehicles/{vehicle_id}/technical

Technical profile per variant: dimensions, weights, towing, powertrain, engines with fluid capacities and axle loads

Parameter

NameOrtTypPflichtBeschreibung
vehicle_idPfadstring
Muster: ^[0-9]{4}-[A-Z0-9]{3}$
jaHSN-TSN, e.g. 0005-DFY.
selectionQuerystringneinVariant selection id (var_…) or an execution id (exe_…) that maps to exactly one variant, from the vehicle; configurations are not supported here.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
vehicle_idstringja
brandstringnein
modelstringnein
wheel_mountingobjectneinSame as wheels on /v2/vehicles/{vehicle_id}.
safety_notestringnein
engines_unavailablestringneinEngine rows (fluid capacities, axle loads) are withheld because the vehicle has several EU configurations without verified assignment.
Werte: configuration_evidence_required
variantsobject[]ja
variants[].vehicle_idstringnein
variants[].selection_idstringneinVariant selection id when the variant is a selection of the vehicle.
variants[].brandstringnein
variants[].modelstringnein
variants[].labelstringnein
variants[].bodyobjectnein
variants[].dimensionsobjectnein
variants[].powertrainobjectnein
variants[].productionobjectnein
variants[].weightsobjectnein
variants[].towingobjectnein
variants[].engineobjectnein
variants[].completenessintegerjaNumber of documented technical fields.
variants[].enginesobject[]nein

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Felder in meta

NameTypImmer vorhandenBeschreibung
totalintegerneinWheel offer list only: number of offers matching the request over all pages.
min 0
selectionobjectnein
selection.idstring | nullnein
selection.typestring | nullnein
selection.statusstringjanone: no selection sent; applied: the selection narrowed the result; superseded: an old variant key was replaced by its successor (applied_id); ambiguous: an execution with several or no variants, the result is the one without selection.
Werte: none, applied, superseded, ambiguous
selection.applied_idstringneinSuperseded keys only: the successor that was applied.
selection.applied_idsstring[]neinThe variants or configurations that were actually applied (status applied or superseded), or the candidate variants of an ambiguous execution. Absent when no selection was sent.

Mögliche Fehlerstatus: 400, 401, 403, 404, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles/0005-DFY/technical"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicles/0005-DFY/technical', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "vehicle_id": "0005-DFY",
    "brand": "BMW",
    "model": "3er",
    "variants": [
      "…"
    ]
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null,
    "selection": {
      "id": null,
      "type": null,
      "status": "none"
    }
  },
  "attribution": [
    {
      "source": "kba",
      "publisher": "Kraftfahrt-Bundesamt (KBA)",
      "license": "…",
      "note": "Daten verändert: eigene Berechnungen auf Grundlage von Daten des Kraftfahrt-B…"
    }
  ]
}

GET /v2/vehicles/{vehicle_id}/configurations

EU configurations of a vehicle

Parameter

NameOrtTypPflichtBeschreibung
vehicle_idPfadstring
Muster: ^[0-9]{4}-[A-Z0-9]{3}$
jaHSN-TSN, e.g. 0005-DFY.
limitQueryinteger
min 1
max 100
neinPage size (default 50).
cursorQuerystringneinOpaque cursor from meta.next_cursor.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
includeQuerystring
Werte: registrations
neinregistrations: annual registration statistics per configuration (registration_observations). Opt-in because a single configuration can carry several megabytes of statistics.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
selection_idstringja
kindstringjaWerte: variant, configuration, alias, execution
labelstringneinVariants and executions: display name.
variant_selection_idsstring[]neinExecutions only: the variants (var_…) of this execution on the vehicle. One entry = the execution is applied like that variant.
variant_selection_idstringneinConfigurations only: linked variant selection, when documented. Keep its technical profile separate from the configuration observations.
technical_observationsobject[]neinConfigurations only: documented technical values of this EU configuration (value or minimum/maximum, unit, basis). confirmed=false marks a value that is not confirmed by further data; confirmed values carry no such field.
technical_observations[].fieldstringja
technical_observations[].valuenumber | stringnein
technical_observations[].minimumnumbernein
technical_observations[].maximumnumbernein
technical_observations[].unitstringnein
technical_observations[].measurement_basisstringja
technical_observations[].contextobjectnein
technical_observations[].confirmedbooleanneinPresent (false) only when the value is not confirmed by further data.
fester Wert: false
approval_observationsobject[]neinConfigurations only: reported withdrawal records of the type approval.
approval_observations[].kindstringja
approval_observations[].scopestringja
approval_observations[].record_positionstringja
approval_observations[].reported_startstringja
approval_observations[].reported_endstringnein
approval_validitystringneinWerte: not_determined
registration_observationsobject[]neinConfigurations only: annual registration statistics (documented counts and measured values).
registration_observations[].observation_idstringjaMuster: ^[a-f0-9]{64}$
registration_observations[].measurement_basisstringjafester Wert: "annual_registration_statistics"
registration_observations[].contextobjectja
registration_observations[].rowsintegerjamin 0
registration_observations[].represented_registrationsintegerjamin 0
registration_observations[].unknown_registration_count_rowsintegerjamin 0
registration_observations[].unknown_registration_date_rowsintegerjamin 0
registration_observations[].earliest_registration_datestringneinYYYY-MM-DD; missing when no date is known.
registration_observations[].latest_registration_datestringneinYYYY-MM-DD; missing when no date is known.
registration_observations[].combinationsobject[]ja

Mögliche Fehlerstatus: 400, 401, 403, 404, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles/0005-DFY/configurations"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicles/0005-DFY/configurations', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "selection_id": "cfg_y",
      "kind": "configuration",
      "type_approval": "e1*2007/46*0001",
      "approval_validity": "not_determined",
      "registration_observations": [
        {
          "observation_id": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "measurement_basis": "annual_registration_statistics",
          "context": "…",
          "rows": 2,
          "represented_registrations": 40,
          "unknown_registration_count_rows": 0,
          "unknown_registration_date_rows": 1,
          "earliest_registration_date": "2025-02-01",
          "latest_registration_date": "2025-11-30",
          "combinations": "…"
        }
      ]
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null
  }
}

GET /v2/vehicles

Search vehicle variants by name, body, powertrain, dimensions, production year and towing capacity

One result per vehicle variant. Text filters ignore case and accents. With min_braked_kg this is the towing search. Trailer limits are variant-specific; confirm the registration certificate before use.

Parameter

NameOrtTypPflichtBeschreibung
qQuerystringneinBrand, model, label or engine code contains this text.
brandQuerystringneinBrand contains this text.
modelQuerystringneinModel or label contains this text.
body_typeQuerystringneinComma-separated: suv, wagon, coupe, convertible, van, pickup, small_car, hatchback, sedan, other.
fuelQuerystringneinComma-separated: petrol, diesel, electric, hybrid, gas, hydrogen, other, unknown.
transmissionQuerystringneinComma-separated: manual, automatic, other, unknown.
drive_typeQuerystringneinComma-separated: front, rear, awd, other, unknown.
doorsQueryinteger
min 0
neinExact doors.
seatsQueryinteger
min 0
neinExact seats.
production_startQueryinteger
min 0
neinExact production start.
production_endQueryinteger
min 0
neinExact production end.
min_length_mmQueryinteger
min 0
neinMinimum length mm.
max_length_mmQueryinteger
min 0
neinMaximum length mm.
min_width_mmQueryinteger
min 0
neinMinimum width mm.
max_width_mmQueryinteger
min 0
neinMaximum width mm.
min_height_mmQueryinteger
min 0
neinMinimum height mm.
max_height_mmQueryinteger
min 0
neinMaximum height mm.
min_power_kwQueryinteger
min 0
neinMinimum power kw.
max_power_kwQueryinteger
min 0
neinMaximum power kw.
min_braked_kgQueryinteger
min 0
neinMinimum braked kg.
max_braked_kgQueryinteger
min 0
neinMaximum braked kg.
min_nose_weight_kgQueryinteger
min 0
neinMinimum nose weight kg.
max_nose_weight_kgQueryinteger
min 0
neinMaximum nose weight kg.
production_yearQueryinteger
min 0
neinBuilt in this year (documented period; ongoing production counts from its start).
includeQuerystring
Werte: facets
neinfacets: counts per brand, body type, fuel, transmission and drive type for the whole result.
limitQueryinteger
min 1
max 100
neinPage size (default 50).
cursorQuerystringneinOpaque cursor from meta.next_cursor.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
vehicle_idstringnein
selection_idstringneinVariant selection id when the variant is a selection of the vehicle.
brandstringnein
modelstringnein
labelstringnein
bodyobjectnein
body.typestringneinWerte: suv, wagon, coupe, convertible, van, pickup, small_car, hatchback, sedan, other
body.labelstringnein
body.doorsintegernein
body.seatsintegernein
dimensionsobjectnein
dimensions.length_mmintegernein
dimensions.width_mmintegernein
dimensions.height_mmintegernein
powertrainobjectnein
powertrain.fuelstringneinWerte: petrol, diesel, electric, hybrid, gas, hydrogen, other, unknown
powertrain.fuel_labelstringnein
powertrain.transmissionstringneinWerte: manual, automatic, other, unknown
powertrain.transmission_labelstringnein
powertrain.drive_typestringneinWerte: front, rear, awd, other, unknown
powertrain.drive_type_labelstringnein
powertrain.power_kwintegernein
powertrain.power_psintegernein
powertrain.displacement_ccmintegernein
productionobjectnein
production.start_yearintegernein
production.end_yearintegernein
production.end_statusstringjaWerte: documented, ongoing, unknown
weightsobjectnein
weights.curb_kgintegernein
weights.gross_kgintegernein
towingobjectnein
towing.braked_kgintegernein
towing.unbraked_kgintegernein
towing.nose_weight_kgintegernein
engineobjectnein
engine.typestringnein
engine.codesstring[]nein
engine.codes_normalizedstring[]nein
completenessintegerjaNumber of documented technical fields.

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Felder in meta

NameTypImmer vorhandenBeschreibung
totalintegernein
engine_codestringnein
facetsobjectnein

Mögliche Fehlerstatus: 400, 401, 403, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicles', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "vehicle_id": "0005-DFY",
      "selection_id": "var_x",
      "brand": "BMW",
      "model": "3er",
      "label": "330e",
      "body": "…",
      "dimensions": "…",
      "powertrain": "…",
      "production": "…",
      "towing": "…",
      "engine": "…",
      "completeness": 12
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null,
    "total": 1
  },
  "attribution": [
    {
      "source": "kba",
      "publisher": "Kraftfahrt-Bundesamt (KBA)",
      "license": "…",
      "note": "Daten verändert: eigene Berechnungen auf Grundlage von Daten des Kraftfahrt-B…"
    }
  ]
}

GET /v2/engine-codes

Engine codes with power range and number of vehicles

Parameter

NameOrtTypPflichtBeschreibung
qQuerystringneinEngine code contains this text.
brandQuerystringneinBrand contains this text.
fuelQuerystringneinComma-separated: petrol, diesel, electric, hybrid, gas, hydrogen, other, unknown.
limitQueryinteger
min 1
max 100
neinPage size (default 50).
cursorQuerystringneinOpaque cursor from meta.next_cursor.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
engine_codestringja
display_codestringnein
engine_typestringnein
fuelstringnein
displacement_ccmintegernein
power_kw_minintegernein
power_kw_maxintegernein
vehicle_countintegerja
application_countintegerja

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Felder in meta

NameTypImmer vorhandenBeschreibung
totalintegernein
engine_codestringnein
facetsobjectnein

Mögliche Fehlerstatus: 400, 401, 403, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/engine-codes"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/engine-codes', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "engine_code": "B48B20A",
      "fuel": "Benzin",
      "displacement_ccm": 1998,
      "power_kw_min": 135,
      "power_kw_max": 135,
      "vehicle_count": 1,
      "application_count": 2
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null,
    "total": 1
  },
  "attribution": [
    {
      "source": "kba",
      "publisher": "Kraftfahrt-Bundesamt (KBA)",
      "license": {
        "name": "Datenlizenz Deutschland – Namensnennung – Version 2.0",
        "id": "dl-de/by-2-0",
        "url": "https://www.govdata.de/dl-de/by-2-0"
      },
      "note": "Daten verändert: eigene Berechnungen auf Grundlage von Daten des Kraftfahrt-B…"
    }
  ]
}

GET /v2/engine-codes/{engine_code}/vehicles

Vehicle variants with this engine code

Call it from your server with your key and secret.

Parameter

NameOrtTypPflichtBeschreibung
engine_codePfadstringjaEngine code from /v2/engine-codes.
limitQueryinteger
min 1
max 100
neinPage size (default 50).
cursorQuerystringneinOpaque cursor from meta.next_cursor.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
vehicle_idstringnein
selection_idstringneinVariant selection id when the variant is a selection of the vehicle.
brandstringnein
modelstringnein
labelstringnein
bodyobjectnein
body.typestringneinWerte: suv, wagon, coupe, convertible, van, pickup, small_car, hatchback, sedan, other
body.labelstringnein
body.doorsintegernein
body.seatsintegernein
dimensionsobjectnein
dimensions.length_mmintegernein
dimensions.width_mmintegernein
dimensions.height_mmintegernein
powertrainobjectnein
powertrain.fuelstringneinWerte: petrol, diesel, electric, hybrid, gas, hydrogen, other, unknown
powertrain.fuel_labelstringnein
powertrain.transmissionstringneinWerte: manual, automatic, other, unknown
powertrain.transmission_labelstringnein
powertrain.drive_typestringneinWerte: front, rear, awd, other, unknown
powertrain.drive_type_labelstringnein
powertrain.power_kwintegernein
powertrain.power_psintegernein
powertrain.displacement_ccmintegernein
productionobjectnein
production.start_yearintegernein
production.end_yearintegernein
production.end_statusstringjaWerte: documented, ongoing, unknown
weightsobjectnein
weights.curb_kgintegernein
weights.gross_kgintegernein
towingobjectnein
towing.braked_kgintegernein
towing.unbraked_kgintegernein
towing.nose_weight_kgintegernein
engineobjectnein
engine.typestringnein
engine.codesstring[]nein
engine.codes_normalizedstring[]nein
completenessintegerjaNumber of documented technical fields.

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Felder in meta

NameTypImmer vorhandenBeschreibung
totalintegernein
engine_codestringnein
facetsobjectnein

Mögliche Fehlerstatus: 400, 401, 403, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/engine-codes/{engine_code}/vehicles"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/engine-codes/{engine_code}/vehicles', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    "…"
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null,
    "total": 1,
    "engine_code": "B48B20A"
  },
  "attribution": [
    "…"
  ]
}

GET /v2/vehicles/{vehicle_id}/wheels

Wheel offers for a vehicle

Parameter

NameOrtTypPflichtBeschreibung
vehicle_idPfadstring
Muster: ^[0-9]{4}-[A-Z0-9]{3}$
jaHSN-TSN, e.g. 0005-DFY.
selectionQuerystringneinSelection id from the vehicle: var_… (variant), cfg_… (EU configuration), als_… (superseded key with several successors) or exe_… (execution). An execution that maps to one variant is applied like that variant; with several or no variants the result is the one without selection (meta.selection.status ambiguous, candidates in applied_ids).
wheel_codeQuerystringneinComma-separated, up to 50.
brandQuerystring
Länge ≥ 1
neinWheel brand as in the wheel catalog (/v2/wheels), case-insensitive. Other names of the same brand match too (MM-Concepts = MM-Wheels). Offers whose wheel is not in the catalog never match.
diameter_inchQuerynumberneinRim diameter.
et_mmQuerynumberneinOffset (ET) in mm.
pcdQuerystring
Länge ≥ 1
neinBolt pattern, e.g. 5x112 (case-insensitive).
statusQuerystring
Werte: no_registration, registration_required, unknown, not_fitting
neinOffer status.
tire_sizeQuerystringneinTire size, e.g. 225/45R18.
viewQuerystring
Werte: summary, full
neinsummary (default) or full with tires, tire pairs, sets and obligation texts.
limitQueryinteger
min 1
max 100
neinPage size (default 50, with view=full 20).
cursorQuerystringneinOpaque cursor from meta.next_cursor.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
offer_idstringja
wheel_codestringja
width_inchnumbernein
diameter_inchnumbernein
et_mmnumbernein
pcdstringnein
center_bore_mmnumbernein
axlestringneinWerte: front, rear, both
statusstringjaWerte: no_registration, registration_required, unknown, not_fitting
reasonstringnein
matchstringneinWerte: vehicle, geometry_only
document_idsstring[]nein
centeringobjectnein
selection_recommendedbooleannein
tire_combinationstringneinHow tires combine across axles on this wheel: single (one size per vehicle, axle of each tire still applies), mixed_optional, mixed_required (front and rear sizes differ), restricted_pairs (only the pairs in allowed_pairs).
Werte: single, mixed_optional, mixed_required, restricted_pairs
tiresobject[]neinview=full only
tires[].sizestringja
tires[].axlestringjaWerte: front, rear, both
tires[].statusstringjaWerte: no_registration, registration_required, unknown, not_fitting
tires[].load_indexstring | numbernein
tires[].obligationsstring[]nein
tires[].blocking_obligationsstring[]nein
tires[].open_obligationsstring[]nein
tires[].reasonstringnein
tires[].violated_conditionsany[]nein
tires[].requires_bodyworkbooleannein
tires[].hintsstring[]nein
tire_sizesstring[]neinview=summary only
allowed_pairsobject[]neinview=full only. Front/rear tire pairs on this wheel that the document allows only as a pair (obligation code, e.g. V18). When present, combine front and rear tires only as listed.
allowed_pairs[].front_tirestringja
allowed_pairs[].rear_tirestringja
allowed_pairs[].obligationstringja

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
includedobjectneinview=full only
included.setsobject[]nein
included.documentsobjectnein
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Felder in meta

NameTypImmer vorhandenBeschreibung
totalintegerneinWheel offer list only: number of offers matching the request over all pages.
min 0
selectionobjectnein
selection.idstring | nullnein
selection.typestring | nullnein
selection.statusstringjanone: no selection sent; applied: the selection narrowed the result; superseded: an old variant key was replaced by its successor (applied_id); ambiguous: an execution with several or no variants, the result is the one without selection.
Werte: none, applied, superseded, ambiguous
selection.applied_idstringneinSuperseded keys only: the successor that was applied.
selection.applied_idsstring[]neinThe variants or configurations that were actually applied (status applied or superseded), or the candidate variants of an ambiguous execution. Absent when no selection was sent.

Mögliche Fehlerstatus: 400, 401, 403, 404, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles/0005-DFY/wheels"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicles/0005-DFY/wheels', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    "…"
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null,
    "selection": "…"
  },
  "attribution": [
    "…"
  ]
}

GET /v2/vehicles/{vehicle_id}/wheels/{wheel_code}

One wheel on a vehicle (all offsets and documents)

Parameter

NameOrtTypPflichtBeschreibung
vehicle_idPfadstring
Muster: ^[0-9]{4}-[A-Z0-9]{3}$
jaHSN-TSN, e.g. 0005-DFY.
wheel_codePfadstringjaWheel code.
selectionQuerystringneinSelection id.
diameter_inchQuerynumberneinRim diameter.
et_mmQuerynumberneinOffset (ET) in mm.
pcdQuerystring
Länge ≥ 1
neinBolt pattern, e.g. 5x112 (case-insensitive).
statusQuerystring
Werte: no_registration, registration_required, unknown, not_fitting
neinOffer status.
tire_sizeQuerystringneinTire size, e.g. 225/45R18.
viewQuerystring
Werte: summary, full
neinAccepted for symmetry with /wheels; this endpoint always answers like view=full.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
offer_idstringja
wheel_codestringja
width_inchnumbernein
diameter_inchnumbernein
et_mmnumbernein
pcdstringnein
center_bore_mmnumbernein
axlestringneinWerte: front, rear, both
statusstringjaWerte: no_registration, registration_required, unknown, not_fitting
reasonstringnein
matchstringneinWerte: vehicle, geometry_only
document_idsstring[]nein
centeringobjectnein
selection_recommendedbooleannein
tire_combinationstringneinHow tires combine across axles on this wheel: single (one size per vehicle, axle of each tire still applies), mixed_optional, mixed_required (front and rear sizes differ), restricted_pairs (only the pairs in allowed_pairs).
Werte: single, mixed_optional, mixed_required, restricted_pairs
tiresobject[]neinview=full only
tires[].sizestringja
tires[].axlestringjaWerte: front, rear, both
tires[].statusstringjaWerte: no_registration, registration_required, unknown, not_fitting
tires[].load_indexstring | numbernein
tires[].obligationsstring[]nein
tires[].blocking_obligationsstring[]nein
tires[].open_obligationsstring[]nein
tires[].reasonstringnein
tires[].violated_conditionsany[]nein
tires[].requires_bodyworkbooleannein
tires[].hintsstring[]nein
tire_sizesstring[]neinview=summary only
allowed_pairsobject[]neinview=full only. Front/rear tire pairs on this wheel that the document allows only as a pair (obligation code, e.g. V18). When present, combine front and rear tires only as listed.
allowed_pairs[].front_tirestringja
allowed_pairs[].rear_tirestringja
allowed_pairs[].obligationstringja

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
includedobjectneinview=full only
included.setsobject[]nein
included.documentsobjectnein
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Felder in meta

NameTypImmer vorhandenBeschreibung
totalintegerneinWheel offer list only: number of offers matching the request over all pages.
min 0
selectionobjectnein
selection.idstring | nullnein
selection.typestring | nullnein
selection.statusstringjanone: no selection sent; applied: the selection narrowed the result; superseded: an old variant key was replaced by its successor (applied_id); ambiguous: an execution with several or no variants, the result is the one without selection.
Werte: none, applied, superseded, ambiguous
selection.applied_idstringneinSuperseded keys only: the successor that was applied.
selection.applied_idsstring[]neinThe variants or configurations that were actually applied (status applied or superseded), or the candidate variants of an ambiguous execution. Absent when no selection was sent.

Mögliche Fehlerstatus: 400, 401, 403, 404, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles/0005-DFY/wheels/{wheel_code}"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicles/0005-DFY/wheels/{wheel_code}', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    "…"
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null,
    "selection": "…"
  },
  "included": {
    "sets": "…",
    "documents": "…"
  },
  "attribution": [
    "…"
  ]
}

GET /v2/wheels und GET /v2/wheels/{wheel_code}

GET /v2/wheels

Wheel catalog

Parameter

NameOrtTypPflichtBeschreibung
brandQuerystringneinWheel brand, case-insensitive. Other names of the same brand match too (MM-Concepts = MM-Wheels).
qQuerystring
Länge 2–50
neinSearch code, model or brand.
diameter_inchQuerynumberneinAvailable diameter.
includeQuerystring
Werte: colors
neincolors: colors with all image views per wheel in the list (saves one detail request per wheel).
limitQueryinteger
min 1
max 100
neinPage size (default 50).
cursorQuerystringneinOpaque cursor from meta.next_cursor.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
wheel_codestringja
brandstringnein
model_namestringnein
designstringnein
classificationobjectnein
diameters_inchnumber[]nein
vehicle_countintegernein
variant_countintegernein
color_countintegernein
document_countintegernein
previewobjectnein
updated_atstringnein
colorsobject[]neinOnly with include=colors.
colors[].namestringja
colors[].classificationobjectnein
colors[].viewsobjectja

Felder in meta

NameTypImmer vorhandenBeschreibung
totalintegernein
engine_codestringnein
facetsobjectnein

Mögliche Fehlerstatus: 400, 401, 403, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/wheels"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/wheels', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "wheel_code": "AF801",
      "brand": "Artform",
      "diameters_inch": [
        20
      ],
      "vehicle_count": 1,
      "variant_count": 1,
      "color_count": 1,
      "document_count": 1
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null,
    "total": 1
  }
}

GET /v2/wheels/{wheel_code}

Catalog wheel with colors, images, variants and documents

Parameter

NameOrtTypPflichtBeschreibung
wheel_codePfadstringjaWheel code.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
wheel_codestringja
brandstringnein
model_namestringnein
designstringnein
classificationobjectnein
diameters_inchnumber[]nein
vehicle_countintegernein
variant_countintegernein
color_countintegernein
document_countintegernein
previewobjectnein
updated_atstringnein
descriptionstringnein
showcaseobjectnein
colorsobject[]nein
colors[].namestringja
colors[].classificationobjectnein
colors[].viewsobjectja
variantsobject[]nein
variants[].skustringnein
variants[].sizestringnein
variants[].width_inchnumbernein
variants[].diameter_inchnumbernein
variants[].et_mmnumbernein
variants[].pcdstringnein
variants[].center_bore_mmnumbernein
variants[].colorstringnein
variants[].classificationobjectnein
documentsobject[]nein
documents[].document_idstringja
documents[].approval_typestringnein
documents[].approval_numberstringnein

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Mögliche Fehlerstatus: 400, 401, 403, 404, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/wheels/{wheel_code}"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/wheels/{wheel_code}', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "wheel_code": "AF801",
    "brand": "Artform",
    "diameters_inch": [
      20
    ],
    "vehicle_count": 1,
    "variant_count": 1,
    "color_count": 1,
    "document_count": 1,
    "colors": [
      "…"
    ],
    "variants": [
      "…"
    ],
    "documents": [
      "…"
    ]
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

GET /v2/documents und GET /v2/documents/{document_id}

Das Feld url ist null, wenn die PDF-Datei nicht bereitsteht; zeige das als „Gutachten fehlt“.

GET /v2/documents

Approval documents (Gutachten) per wheel code: geometries, obligation codes, fasteners and link

Call it from your server with your key and secret.

Parameter

NameOrtTypPflichtBeschreibung
wheel_codeQuerystringneinComma-separated wheel codes, up to 50.
brandQuerystring
Länge ≥ 1
neinWheel brand as in the wheel catalog (/v2/wheels), case-insensitive. Other names of the same brand match too (MM-Concepts = MM-Wheels).
limitQueryinteger
min 1
max 100
neinPage size (default 50).
cursorQuerystringneinOpaque cursor from meta.next_cursor.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
document_idstringja
wheel_codestringja
approval_typestringnein
approval_numberstringnein
kba_numberstringnein
entriesobject[]neinWheel geometries covered by the document.
entries[].pcdstringnein
entries[].center_bore_mmnumbernein
entries[].et_mmnumbernein
entries[].width_inchnumbernein
entries[].diameter_inchnumbernein
entries[].approvalsobject[]nein
obligation_codesstring[]nein
fastenersobject[]neinBolts or nuts named by the document (code S01, S02 …).
fasteners[].codestringja
fasteners[].typestringnein
fasteners[].threadstringnein
fasteners[].seatstringnein
fasteners[].seat_diameter_mmnumbernein
fasteners[].seat_angle_degnumbernein
fasteners[].torque_nmnumbernein
fasteners[].shaft_length_mmnumbernein
fasteners[].shaft_length_statusstringnein
fasteners[].row_statusstringnein
fasteners[].missing_fieldsstring[]nein
fastener_statusstringnein
urlstring | nullnein

Mögliche Fehlerstatus: 400, 401, 403, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/documents"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/documents', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "document_id": "doc_aaaaaaaaaaaaaaaaaaaaaaaa",
      "wheel_code": "AF801",
      "approval_type": "KBA",
      "approval_number": "123456",
      "entries": [
        "…"
      ],
      "obligation_codes": [
        "A12"
      ],
      "fasteners": [
        "…"
      ],
      "url": "https://cdn.example/AF801/a.pdf"
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null
  }
}

GET /v2/documents/{document_id}

Approval document (Gutachten) with obligation texts and link

Parameter

NameOrtTypPflichtBeschreibung
document_idPfadstring
Muster: ^doc_[a-f0-9]{24}$
jaDocument id.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
document_idstringja
approval_typestringnein
approval_numberstringnein
kba_numberstringnein
obligationsobjectnein
urlstring | nullnein

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Mögliche Fehlerstatus: 400, 401, 403, 404, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/documents/{document_id}"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/documents/{document_id}', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "document_id": "doc_aaaaaaaaaaaaaaaaaaaaaaaa",
    "approval_type": "KBA",
    "approval_number": "123456",
    "obligations": {
      "A12": "Example obligation text"
    },
    "url": "https://cdn.example/AF801/a.pdf"
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

Versicherung: Typklassen

Typklassen für Haftpflicht, Teilkasko und Vollkasko je Fahrzeug (HSN/TSN), dazu die Klasse je Jahr. Fehlt ein Wert, fehlt das Feld; ersetzt oder geschätzt wird nichts. Dieselben Werte liefert ein einzelnes Fahrzeug mit include=insurance.

GET /v2/insurance

Insurance type classes of all vehicles of a brand or model

Call it from your server with your key and secret. One entry per vehicle (HSN/TSN) that has insurance type classes, ordered by HSN and TSN. Needs brand and/or model. Values are the same as /v2/vehicles/{vehicle_id}?include=insurance.

Parameter

NameOrtTypPflichtBeschreibung
brandQuerystring
Länge ≥ 1
neinBrand name (as on the vehicle or in /v2/brands; known spellings of the same brand match, case and accents ignored) or brand id from /v2/brands.
modelQuerystring
Länge ≥ 1
neinModel field of the vehicle contains this text (case and accents ignored).
model_idQuerystring
Muster: ^[a-z0-9-]{1,120}$
neinModel id from /v2/brands/{brand_id}/models; needs brand = the brand id. Matches all vehicles the navigation lists under this model.
limitQueryinteger
min 1
max 100
neinPage size (default 50).
cursorQuerystringneinOpaque cursor from meta.next_cursor.
data_versionQuerystringneinOptional: fail with 409 if the active data release differs.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist eine Liste; die Felder gelten je Eintrag.

NameTypImmer vorhandenBeschreibung
vehicle_idstringja
hsnstringja
tsnstringja
brandstringneinAs on /v2/vehicles/{vehicle_id}.
modelstringneinAs on /v2/vehicles/{vehicle_id}.
insuranceobjectjaInsurance type classes per HSN/TSN (include=insurance and /v2/insurance). All classes are integers; a value that is not a whole number in the data is omitted, never guessed. Empty values are omitted.
insurance.liabilityintegerneinCurrent liability (third-party) type class.
min 0
insurance.partial_comprehensiveintegerneinCurrent partial comprehensive type class.
min 0
insurance.full_comprehensiveintegerneinCurrent full comprehensive type class.
min 0
insurance.yearintegerneinYear of the current type classes: the latest year (YYYY) in history across all lines. Omitted without history.
min 1900
insurance.historyobjectneinType class per line and year (key YYYY).

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Felder in meta

NameTypImmer vorhandenBeschreibung
totalintegernein
engine_codestringnein
facetsobjectnein

Mögliche Fehlerstatus: 400, 401, 403, 404, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/insurance"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/insurance', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": [
    {
      "vehicle_id": "0005-DFY",
      "hsn": "0005",
      "tsn": "DFY",
      "brand": "BMW",
      "model": "3er",
      "insurance": "…"
    }
  ],
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "next_cursor": null,
    "total": 1
  },
  "attribution": [
    {
      "source": "kba",
      "publisher": "Kraftfahrt-Bundesamt (KBA)",
      "license": "…",
      "note": "Daten verändert: eigene Berechnungen auf Grundlage von Daten des Kraftfahrt-B…"
    }
  ]
}

Betrieb

GET /v2/status

Service status and active data release

Ohne Schlüssel erreichbar.

Parameter

NameOrtTypPflichtBeschreibung
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
statusstringjafester Wert: "ok"
data_versionstringja

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Mögliche Fehlerstatus: 400, 503 (Fehlerreferenz)

Anfrage

curl "https://api.api4cars.com/v2/status"
// Ohne Schlüssel erreichbar
const res = await fetch('https://api.api4cars.com/v2/status');
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "status": "ok",
    "data_version": "2026-10-15-1"
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

GET /v2/me

Own API key: monthly quota and usage

Parameter

NameOrtTypPflichtBeschreibung
If-None-MatchHeaderstringneinDo not send If-None-Match or reuse a cached body on /v2/me or /v2/me/usage; always request fresh usage data.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
api_keystringja
labelstring | nullnein
monthstringja
requests_this_monthintegerja
monthly_limitinteger | nullnein
remaininginteger | nullnein
quota_scopestringneinaccount: remaining is the last reported account allowance minus subsequent V2 requests; key: own monthly allowance. Monthly request fields always describe this key.
Werte: account, key
account_counterinteger | nullneinLifetime count of admitted V2 requests across this account, including revoked keys.
quota_reported_atinteger | nullneinUnix seconds of the last account allowance report. Older reports remain valid.
quota_warningstring | nullnein
key_requests_this_monthintegerneinRequests of this key this month.
key_monthly_limitinteger | nullneinOwn monthly limit of this key, if one is set; null = none.

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Mögliche Fehlerstatus: 400, 401, 403, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/me"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/me', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "api_key": "ck_v2_example",
    "label": "Website",
    "month": "2026-10",
    "requests_this_month": 5,
    "monthly_limit": null,
    "remaining": 9988,
    "quota_scope": "account",
    "account_counter": 12,
    "quota_reported_at": 1790812800,
    "quota_warning": null,
    "key_requests_this_month": 5,
    "key_monthly_limit": null
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

GET /v2/me/usage

Own API key: requests per day and endpoint

Request counts of the calling key per UTC day and endpoint (path template, no vehicle ids or parameters). Defaults to the last 30 days; at most 92 days per request. Days without requests are omitted. Counts match the monthly quota counter: every authenticated request that was not stopped by the short-term brake, including this one.

Parameter

NameOrtTypPflichtBeschreibung
fromQuerystring
Format: date
neinFirst day (UTC), YYYY-MM-DD. Default: 29 days before to.
toQuerystring
Format: date
neinLast day (UTC), YYYY-MM-DD. Default: today.
If-None-MatchHeaderstringneinDo not send If-None-Match or reuse a cached body on /v2/me or /v2/me/usage; always request fresh usage data.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
api_keystringja
fromstringjaFormat: date
tostringjaFormat: date
requestsintegerjamin 0
over_quotaintegerneinRequests in the period that were rejected with 429 rate_limited because the monthly quota was used up (part of requests).
min 0
endpointsobject[]jaTotals per endpoint over the period.
endpoints[].endpointstringjaPath template as in this description, e.g. /v2/vehicles/{vehicle_id}/wheels.
endpoints[].requestsintegerjamin 1
daysobject[]ja
days[].daystringjaFormat: date
days[].requestsintegerjamin 0
days[].over_quotaintegerneinmin 1
days[].endpointsobject[]ja

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Mögliche Fehlerstatus: 400, 401, 403, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/me/usage"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/me/usage', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "api_key": "ck_v2_example",
    "from": "2026-10-14",
    "to": "2026-10-15",
    "requests": 5,
    "endpoints": [
      "…",
      "…"
    ],
    "days": [
      "…",
      "…"
    ]
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

GET /v2/openapi.json

This description

Ohne Schlüssel erreichbar.

Parameter

Keine Parameter.

Anfrage

curl "https://api.api4cars.com/v2/openapi.json"
// Ohne Schlüssel erreichbar
const res = await fetch('https://api.api4cars.com/v2/openapi.json');
const body = await res.json();

Weitere Endpunkte

GET /v2/vehicles/{vehicle_id}/images

Configurator image sets for a vehicle (add-on module)

Image groups of the vehicle with all wheels whose image set is published and that are approved for exactly this vehicle. Needs the configurator image module on the API key (403 feature_not_enabled otherwise). body_match tells whether the image shows exactly this body type.

Parameter

NameOrtTypPflichtBeschreibung
vehicle_idPfadstring
Muster: ^[0-9]{4}-[A-Z0-9]{3}$
jaHSN-TSN, e.g. 0005-DFY.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
availablebooleanja
ambiguousbooleanja
matchesobject[]ja
matches[].vehicle_imageobjectja
matches[].matched_bystringjaWerte: vehicle_id, vehicle_image_id
matches[].fitment_checkedbooleanja
matches[].wheelsobject[]ja
matches[].original_wheelsobjectneinThe vehicle with its original wheels in every paint (wheel_code original; no fitment check); renditions include the small sizes.
body_noticeobject | nullja
body_notice.codestringneinWerte: body_image_missing, body_differs, body_unconfirmed
body_notice.messagestringnein

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Mögliche Fehlerstatus: 400, 401, 403, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles/0005-DFY/images"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicles/0005-DFY/images', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "available": true,
    "ambiguous": false,
    "body_notice": null,
    "matches": [
      {
        "vehicle_image": {
          "vehicle_image_id": "bmw-3er-g20",
          "label": "BMW 3er (G20)",
          "brand": "BMW",
          "model": "3er",
          "generation": "G20",
          "body_type": "Limousine",
          "years": "…",
          "body_match": "exact",
          "body_notice": null
        },
        "matched_by": "vehicle_id",
        "fitment_checked": true,
        "wheels": [
          "…"
        ]
      }
    ]
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

GET /v2/vehicles/{vehicle_id}/images/{wheel_code}

Configurator images of one wheel, paint and finish on a vehicle (add-on module)

delivery=render (default): one finished image per view and size, rendered at the edge. delivery=layers: base and overlay layers with placement for client-side composition in render_order (base = the vehicle in the selected paint, then paint_patch where the wheel changes the paint, then wheel). Sizes are limited to the wheel sizes approved for this vehicle (404 wheel_size_not_approved_for_vehicle with the approved wheel_sizes). wheel_code=original: the vehicle with its original wheels in the selected paint (finish and size not needed, no fitment check, also the small renditions from original_wheels). Links are signed, valid at least one hour and identical within the hour (expires_at; meta.urls_expire_at is the earliest).

Parameter

NameOrtTypPflichtBeschreibung
vehicle_idPfadstring
Muster: ^[0-9]{4}-[A-Z0-9]{3}$
jaHSN-TSN, e.g. 0005-DFY.
wheel_codePfadstringjaWheel code from the availability, or original for the original wheels.
paintQuerystringneinPaint id from the availability (required).
finishQuerystringneinFinish id from the availability (required except for wheel_code=original; older finish ids from finish_aliases are accepted).
sizeQueryinteger
min 1
max 30
neinWheel size in inches (default: default_wheel_size).
deliveryQuerystring
Werte: render, layers
neinrender (default) or layers.
vehicle_image_idQuerystringneinImage group, needed when the vehicle belongs to several groups (409 configurator_vehicle_ambiguous).
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
vehicle_imageobjectja
vehicle_image.vehicle_image_idstringja
vehicle_image.labelstringja
vehicle_image.brandstring | nullnein
vehicle_image.modelstring | nullnein
vehicle_image.generationstring | nullnein
vehicle_image.body_typestring | nullnein
vehicle_image.yearsobjectnein
vehicle_image.body_matchstringneinOnly when matched by vehicle: exact body type, unconfirmed (body type of the vehicle not confirmed) or differs.
Werte: exact, unconfirmed, differs
vehicle_image.body_noticeobject | nullnein
matched_bystringneinWerte: vehicle_id, vehicle_image_id
fitment_checkedbooleannein
deliverystringjaWerte: edge_render, layers, full_images
render_orderstring[]nein
selectionobjectja
selection.wheel_codestringja
selection.paintstringja
selection.finishstring | nulljanull for wheel_code original.
selection.sizeinteger | nullnein
selection.requested_finishstringneinThe older finish id sent, when it was mapped to finish.
revisionstringja
viewsobjectjaPer view and rendition: an image (url, expires_at, width, height) or, with delivery=layers, canvas, base and layers.

Felder in meta

NameTypImmer vorhandenBeschreibung
urls_expire_atstring | nullneinEarliest expiry of the signed links in this response (ISO 8601).

Mögliche Fehlerstatus: 400, 401, 403, 404, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicles/0005-DFY/images/{wheel_code}"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicles/0005-DFY/images/{wheel_code}', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "vehicle_image": "…",
    "matched_by": "vehicle_id",
    "fitment_checked": true,
    "delivery": "edge_render",
    "selection": "…",
    "revision": "24cb8a273c5f52a6",
    "views": "…"
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "urls_expire_at": "2026-10-24T02:00:00.000Z"
  }
}

GET /v2/vehicle-images/{vehicle_image_id}

One configurator image group with its published wheels (add-on module)

Like /v2/vehicles/{vehicle_id}/images for one image group, without the per-vehicle wheel approval check (fitment_checked false).

Parameter

NameOrtTypPflichtBeschreibung
vehicle_image_idPfadstring
Muster: ^[a-z0-9_-]{1,80}$
jaImage group id.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
availablebooleanja
ambiguousbooleanja
matchesobject[]ja
matches[].vehicle_imageobjectja
matches[].matched_bystringjaWerte: vehicle_id, vehicle_image_id
matches[].fitment_checkedbooleanja
matches[].wheelsobject[]ja
matches[].original_wheelsobjectneinThe vehicle with its original wheels in every paint (wheel_code original; no fitment check); renditions include the small sizes.
body_noticeobject | nullja
body_notice.codestringneinWerte: body_image_missing, body_differs, body_unconfirmed
body_notice.messagestringnein

Weitere Felder der Antwort

NameTypImmer vorhandenBeschreibung
attributionobject[]neinPresent when the response uses KBA data (dl-de/by-2-0).

Mögliche Fehlerstatus: 400, 401, 403, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicle-images/{vehicle_image_id}"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicle-images/{vehicle_image_id}', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "available": true,
    "ambiguous": false,
    "body_notice": null,
    "matches": [
      {
        "matched_by": "vehicle_image_id",
        "fitment_checked": false,
        "wheels": [
          "…"
        ],
        "vehicle_image": {
          "vehicle_image_id": "bmw-3er-g20",
          "label": "BMW 3er (G20)",
          "brand": "BMW",
          "model": "3er",
          "generation": "G20",
          "body_type": "Limousine",
          "years": "…"
        }
      }
    ]
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1"
  }
}

GET /v2/vehicle-images/{vehicle_image_id}/{wheel_code}

Configurator images of one wheel, paint and finish in an image group (add-on module)

Parameter

NameOrtTypPflichtBeschreibung
vehicle_image_idPfadstring
Muster: ^[a-z0-9_-]{1,80}$
jaImage group id.
wheel_codePfadstringjaWheel code, or original for the original wheels.
paintQuerystringneinPaint id (required).
finishQuerystringneinFinish id (required except for wheel_code=original).
sizeQueryinteger
min 1
max 30
neinWheel size in inches (default: default_wheel_size).
deliveryQuerystring
Werte: render, layers
neinrender (default) or layers.
If-None-MatchHeaderstringneinETag for the same request; unchanged: 304 without a body.

Antwortfelder

data ist ein Objekt.

NameTypImmer vorhandenBeschreibung
vehicle_imageobjectja
vehicle_image.vehicle_image_idstringja
vehicle_image.labelstringja
vehicle_image.brandstring | nullnein
vehicle_image.modelstring | nullnein
vehicle_image.generationstring | nullnein
vehicle_image.body_typestring | nullnein
vehicle_image.yearsobjectnein
vehicle_image.body_matchstringneinOnly when matched by vehicle: exact body type, unconfirmed (body type of the vehicle not confirmed) or differs.
Werte: exact, unconfirmed, differs
vehicle_image.body_noticeobject | nullnein
matched_bystringneinWerte: vehicle_id, vehicle_image_id
fitment_checkedbooleannein
deliverystringjaWerte: edge_render, layers, full_images
render_orderstring[]nein
selectionobjectja
selection.wheel_codestringja
selection.paintstringja
selection.finishstring | nulljanull for wheel_code original.
selection.sizeinteger | nullnein
selection.requested_finishstringneinThe older finish id sent, when it was mapped to finish.
revisionstringja
viewsobjectjaPer view and rendition: an image (url, expires_at, width, height) or, with delivery=layers, canvas, base and layers.

Felder in meta

NameTypImmer vorhandenBeschreibung
urls_expire_atstring | nullneinEarliest expiry of the signed links in this response (ISO 8601).

Mögliche Fehlerstatus: 400, 401, 403, 404, 409, 429, 503 (Fehlerreferenz)

Anfrage

curl -H "X-API-Key: $A4C_KEY" \
     -H "X-API-Secret: $A4C_SECRET" \
     "https://api.api4cars.com/v2/vehicle-images/{vehicle_image_id}/{wheel_code}"
// Auf deinem Server (Node ≥ 18): Schlüssel und Secret aus der Umgebung
const res = await fetch('https://api.api4cars.com/v2/vehicle-images/{vehicle_image_id}/{wheel_code}', {
  headers: { 'X-API-Key': process.env.A4C_KEY, 'X-API-Secret': process.env.A4C_SECRET }
});
const body = await res.json();

Beispielantwort (gekürzt)

{
  "data": {
    "vehicle_image": "…",
    "matched_by": "vehicle_image_id",
    "fitment_checked": false,
    "delivery": "edge_render",
    "selection": "…",
    "revision": "24cb8a273c5f52a6",
    "views": "…"
  },
  "meta": {
    "api_version": 2,
    "data_version": "2026-10-15-1",
    "urls_expire_at": "2026-10-24T02:00:00.000Z"
  }
}

Fehlerreferenz

Fehler tragen einen Statuscode und ein Objekt error mit maschinenlesbarem code. Werte, die in der Anfrage fehlen oder ungültig sind, nennt details. Programme sollten auf error.code prüfen, nicht auf den Text der Meldung.

HTTPBedeutungCodes
400 Ungültige AnfrageInvalid request (unknown_parameter, duplicate_parameter, invalid_…, selection or variant not for the vehicle)unknown_parameter, duplicate_parameter, invalid_include
401 Nicht angemeldetMissing or invalid credentials (unauthorized, invalid_credentials)invalid_credentials, unauthorized
403 Zugriff verweigertKey inactive (subscription_inactive) or add-on module not enabled for the key (feature_not_enabled)subscription_inactive, feature_not_enabled
404 Nicht gefundenNot foundwheel_size_not_approved_for_vehicle, vehicle_not_found
409 KonfliktData release changed (data_version_changed) or no fitment statement for this vehicle or selection (see code)data_version_changed, configurator_vehicle_ambiguous
429 Zu viele AnfragenMonthly quota used up without permitted overage (rate_limited) or too many requests (too_many_requests); see Retry-After. With permitted overage, otherwise valid requests continue with 200 after the monthly quota is used up.rate_limited, too_many_requests
503 Nicht verfügbarNo data release active (data_unavailable), endpoint not in the active data release (not_in_release) or image service not configured (configurator_edge_not_configured)data_unavailable, not_in_release, configurator_edge_not_configured

Aufbau einer Fehlerantwort

NameTypImmer vorhandenBeschreibung
errorobjectja
error.codestringja
error.messagestringja
error.statusintegerja
error.detailsobjectnein

Beispiel

{
  "error": {
    "code": "vehicle_not_found",
    "message": "Vehicle not found.",
    "status": 404,
    "details": {
      "vehicle_id": "9999-ZZZ"
    }
  }
}

Umstieg V1 → V2 und Grenzen

V2 deckt noch nicht alles aus V1 ab. Die Tabelle zeigt Ersatzwege für Konfigurationsprofile und Mehrfahrzeugvergleich. Für fehlende Intelligence-Scores und Zeitraum-/Regionsfilter nutze weiterhin V1.

FunktionV1V2
Fahrzeug / Variante/vehicle?hsn=…&tsn=…&variant_key=…/v2/vehicles/{id}?selection=var_…
EU-Konfigurationen/vehicle-configurations/v2/vehicles/{id}/configurations
Felgen / Passung/fitments, /compatibility/v2/vehicles/{id}/wheels?view=full
Werkstattprofil/workshop-profile/configurations + /technical (Beispiel in der Umstiegsanleitung)
Mehrfahrzeugvergleich/vehicle-compare/v2/vehicles/{id}/technical je Fahrzeug; im Shop zusammenführen
Intelligence je Fahrzeug/intelligence/vehicle?include=market,market_history,safety,environment; ohne Scores, from/to oder region

V2 ist für alle Kunden offen: Server-Schlüssel mit Secret selbst im Konto anlegen. V1 läuft weiter. Änderungen stehen im API-Changelog.


API-Changelog

Datierte Änderungen der API und ihrer Integrationshilfen. Der Datenstand steht getrennt in meta.data_version. Änderungen, die bestehende Integrationen betreffen, kündigen wir vorher per E-Mail an.

· Zugang und Umstieg

  • V2 ist für alle Kunden offen. Server-Schlüssel mit Secret selbst im Konto anlegen; V1 bleibt verfügbar.
  • Der Abschnitt Umstieg V1 → V2 beschreibt Konfigurationsprofile, mehrere Vergleichsabrufe und die Grenzen von Intelligence.
  • Die OpenAPI-Beschreibung nennt Schlüssel und Secret gemeinsam und beschreibt ETag/304 sowie Monatskontingent und kurzzeitige Begrenzung getrennt.
  • SDK: vehicle(id, { selection }) und brands({ withLogo: true }). Ungültige Cursorinhalte ergeben 400 invalid_cursor.

Integration

Fragen zur Integration?

Schick uns deinen Anwendungsfall – wir helfen dir bei der Wahl der Endpunkte.