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-Secretoder Bearerkey: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 mitRetry-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 Umstiegapi4cars API V2
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
| Begriff | Kennung | Bedeutung |
|---|---|---|
| Fahrzeug | vehicle_id = HSN-TSN | Herstellerschlüsselnummer (4 Ziffern) und Typschlüsselnummer (3 Zeichen), mit Bindestrich, z. B. 0603-COB. |
| Auswahl | selection_id | Eine 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. |
| Angebot | offer_id | Eine Felge (Code, Breite, Durchmesser, ET) mit Passungsstatus für das Fahrzeug. |
| Gutachten | document_id (doc_…) | Teilegutachten oder ABE mit Auflagentexten und Link zur PDF-Datei. |
| Passungsstatus | status | no_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.
| Pfad | Liefert |
|---|---|
/v2/status | Service status and active data release |
/v2/me | Own API key: monthly quota and usage |
/v2/me/usage | Own API key: requests per day and endpoint |
/v2/openapi.json | This description |
/v2/brands | Brands |
/v2/brands/{brand_id}/models | Models of a brand |
/v2/brands/{brand_id}/models/{model_id}/generations | Generations of a model, with executions |
/v2/generations/{generation_id}/engines | Engines of a generation with their vehicles and selections |
/v2/vehicles | Search vehicle variants by name, body, powertrain, dimensions, production year and towing capacity |
/v2/vehicles/{vehicle_id} | Vehicle with selections |
/v2/vehicle-list | Vehicles (HSN/TSN) of a brand, model or bolt pattern |
/v2/insurance | Insurance type classes of all vehicles of a brand or model |
/v2/vehicles/{vehicle_id}/technical | Technical profile per variant: dimensions, weights, towing, powertrain, engines with fluid capacities and axle loads |
/v2/vehicles/{vehicle_id}/configurations | EU configurations of a vehicle |
/v2/vehicles/{vehicle_id}/wheels | Wheel offers for a vehicle |
/v2/vehicles/{vehicle_id}/wheels/{wheel_code} | One wheel on a vehicle (all offsets and documents) |
/v2/engine-codes | Engine codes with power range and number of vehicles |
/v2/engine-codes/{engine_code}/vehicles | Vehicle variants with this engine code |
/v2/wheels | Wheel catalog |
/v2/wheels/{wheel_code} | Catalog wheel with colors, images, variants and documents |
/v2/vehicles/{vehicle_id}/images | Configurator 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/documents | Approval 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ätzlichmeta.next_cursor, Felgenangebote bringenincludedmit (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.
limitlegt die Seitengröße fest (Grenzen und Standard stehen je Endpunkt in der Parametertabelle), die nächste Seite holst du mitcursorausmeta.next_cursor. Istnext_cursornull, bist du am Ende. Eine Gesamtzahl steht nur dort inmeta.total, wo der Endpunkt sie in den Feldern vonmetanennt. - Datenstand festhalten: Gib
data_versionals Parameter mit; weicht der aktive Datenstand ab, antwortet die API mit409. So mischst du beim Blättern keine zwei Datenstände. - Fehlende Werte: Felder ohne Wert fehlen in der Antwort, außer die Feldtabelle nennt
nullals 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
ETagbei derselben Anfrage alsIf-None-Matchsenden: Bei unveränderter Antwort folgt304ohne Body. Verwende dann deinen gespeicherten Body und rufe nichtres.json()auf. Ausnahme Verbrauch:/v2/meund/v2/me/usageimmer frisch ohneIf-None-Matchabrufen; 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:
| Header | Bedeutung |
|---|---|
X-RateLimit-Limit | Monatskontingent deines Kontos (V1 und V2 gemeinsam), keine kurzfristige Ratenbegrenzung |
X-RateLimit-Remaining | Verbleibende Anfragen im Monatskontingent |
Retry-After | Bei 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
with_fitments | Query | string Werte: 0, 1 | nein | Only brands with wheel assignments. |
with_logo | Query | string Werte: 0, 1 | nein | Only brands with a logo. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
id | string | ja | |
name | string | ja | |
vehicle_count | integer | nein | |
with_fitments_count | integer | nein | |
logo_url | string | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
brand_id | Pfad | string | ja | Brand id from /v2/brands. |
with_fitments | Query | string Werte: 0, 1 | nein | Only models with wheel assignments. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
id | string | ja | |
name | string | ja | |
with_fitments_count | integer | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
brand_id | Pfad | string | ja | Brand id. |
model_id | Pfad | string | ja | Model id. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
id | string | ja | |
name | string | ja | |
years | string | nein | |
brand_id | string | nein | |
model_id | string | nein | |
executions | object[] | nein | |
executions[].id | string | ja | |
executions[].label | string | nein | |
executions[].body_type | string | nein | |
executions[].body_type_code | string | nein | Werte: hatchback, estate, sedan, suv, van, coupe, convertible, pickup |
executions[].engine_count | integer | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
generation_id | Pfad | string Muster: ^gen_[a-f0-9]{16}$ | ja | Generation id. |
execution | Query | string | nein | Execution id from the generation. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
name | string | nein | |
label | string | nein | |
engine_names | string[] | nein | |
power_kw | number | nein | |
power_ps | number | nein | |
fuel | string | nein | |
fuel_code | string | nein | Werte: petrol, diesel, electric, hybrid, plugin_hybrid, hydrogen, cng, lpg |
drivetrain | string | nein | |
drivetrain_code | string | nein | Werte: fwd, rwd, awd |
derived_from_variants | string[] | nein | Fields 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 |
transmissions | string[] | nein | |
transmission_codes | string[] | nein | Werte: manual, automatic, dual_clutch, automated_manual, cvt, single_speed |
years | string | nein | Production 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_from | string | nein | Earliest 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_to | string | nein | Latest end in the same granularity. Absent when the end is open or the periods cannot be summarised. |
periods | string[] | nein | All source periods of the engine choice (unchanged). |
execution | object | nein | |
execution.id | string | ja | |
execution.label | string | nein | |
execution.body_type | string | nein | |
execution.body_type_code | string | nein | Werte: hatchback, estate, sedan, suv, van, coupe, convertible, pickup |
execution.engine_count | integer | nein | |
selection_required | boolean | nein | |
vehicles | object[] | nein | |
vehicles[].id | string | ja | |
vehicles[].selections | string[] | nein | |
vehicles[].selection_required | boolean | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
vehicle_id | Pfad | string Muster: ^[0-9]{4}-[A-Z0-9]{3}$ | ja | HSN-TSN, e.g. 0005-DFY. |
selection | Query | string | nein | Selection 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. |
include | Query | string | nein | Comma-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-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist ein Objekt.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
vehicle_id | string | ja | |
hsn | string | ja | |
tsn | string | ja | |
brand | string | nein | |
model | string | nein | |
years | string | nein | |
display | object | nein | |
identity_only | boolean | nein | |
brand_id | string | nein | Brand id as in /v2/brands (only when the brand is unambiguous). |
brand_logo_url | string | nein | Public logo of the brand (same file as logo_url in /v2/brands).Format: uri |
wheels | object | nein | |
wheels.pcd | string | nein | |
wheels.pcd_status | string | nein | Werte: verified, unverified, missing |
wheels.center_bore_mm | number | nein | |
wheels.center_bore_status | string | nein | Werte: verified, unverified, missing |
wheels.thread | string | nein | |
wheels.torque_nm | number | nein | |
wheels.fastener | string | nein | |
wheels.fastener_code | string | nein | Werte: bolts, nuts |
wheels.mounting | object | nein | |
tpms | object | nein | |
oe_tires | object[] | nein | |
factory_wheels | object | nein | Factory wheels from the certificate of conformity: references and wheel/tyre options; staggered = different front/rear size. Empty values are omitted. |
factory_wheels.references | string[] | nein | |
factory_wheels.options | object[] | nein | |
has_wheels | boolean | nein | |
wheels_unavailable | string | nein | |
selections | object[] | nein | |
selections[].selection_id | string | ja | |
selections[].kind | string | ja | Werte: variant, configuration, alias, execution |
selections[].label | string | nein | Variants and executions: display name. |
selections[].variant_selection_ids | string[] | nein | Executions only: the variants (var_…) of this execution on the vehicle. One entry = the execution is applied like that variant. |
selections[].variant_selection_id | string | nein | Configurations only: linked variant selection, when documented. Keep its technical profile separate from the configuration observations. |
selections[].technical_observations | object[] | nein | Configurations 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_observations | object[] | nein | Configurations only: reported withdrawal records of the type approval. |
selections[].approval_validity | string | nein | Werte: not_determined |
selections[].registration_observations | object[] | nein | Configurations only: annual registration statistics (documented counts and measured values). |
configuration_count | integer | nein | |
insurance | object | nein | Insurance 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.liability | integer | nein | Current liability (third-party) type class. min 0 |
insurance.partial_comprehensive | integer | nein | Current partial comprehensive type class. min 0 |
insurance.full_comprehensive | integer | nein | Current full comprehensive type class. min 0 |
insurance.year | integer | nein | Year of the current type classes: the latest year (YYYY) in history across all lines. Omitted without history. min 1900 |
insurance.history | object | nein | Type class per line and year (key YYYY). |
insurance_unavailable | string | nein | Only with include=insurance: no insurance type classes are known for this vehicle.Werte: no_type_classes |
market | object | nein | include=market: newest figure per metric for this vehicle; never brand, region or class aggregates. |
market.latest | object[] | ja | |
market.scope | string | ja | |
market.reason | string | nein | Why latest is empty. |
market_history | object | nein | include=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.available | boolean | ja | |
market_history.scope | string | ja | |
market_history.hsn_tsn_exact | boolean | nein | |
market_history.registration_history | object[] | nein | Registered vehicles of this HSN/TSN per year, oldest first. |
market_history.registration_trend | object | nein | Change of the stock in percent, calculated from registration_history. |
market_history.reason | string | nein | Why nothing is available. |
safety | object | nein | include=safety: recalls of the validated model (up to 200, newest first) and exact safety figures. |
safety.available | boolean | ja | |
safety.scope | string | ja | |
safety.hsn_tsn_exact | boolean | ja | |
safety.recall_count | integer | ja | min 0 |
safety.recalls | object[] | ja | |
safety.facts | object[] | nein | |
safety.reason | string | nein | Why nothing is available. |
environment | object | nein | include=environment: only figures that refer exactly to this HSN/TSN. |
environment.available | boolean | ja | |
environment.scope | string | ja | |
environment.hsn_tsn_exact | boolean | ja | |
environment.latest | object[] | ja | |
environment.reason | string | nein | Why nothing is available. |
intelligence_unavailable | string | nein | Only with include=market, market_history, safety or environment: the active data release has none of the requested sections.Werte: not_in_release |
data_sheet | object | nein | include=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.sheets | object[] | nein | One data sheet per VSN. |
data_sheet.facts | object | nein | Vehicle facts by name (e.g. length_mm, curb_weight_kg, drivetrain). values only when status is confirmed. |
data_sheet_unavailable | string | nein | Only with include=data_sheet: no data sheet is known for this vehicle.Werte: no_data_sheet |
vehicle_image | object | nein | Only with include=vehicle_image. |
vehicle_image.available | boolean | ja | |
vehicle_image.ambiguous | boolean | ja | |
vehicle_image.delivery_ready | boolean | ja | |
vehicle_image.vehicle_image_id | string | null | nein | |
vehicle_image.label | string | null | nein | |
vehicle_image.thumbnail | object | null | nein | |
vehicle_image.body_match | string | null | nein | Werte: exact, unconfirmed, differs, missing, null |
vehicle_image.body_notice | object | null | nein | |
vehicle_image.matches | object[] | nein | |
selected | object | nein | Only with the selection parameter: the applied selection (as in selections). |
available_sections | object | nein | Only with include=sections: which detail sections have content for this vehicle. |
available_sections.workshop | boolean | ja | Fluid capacities in /technical. |
available_sections.market | boolean | ja | Official market figures (include=market). |
available_sections.recalls | boolean | ja | Recalls (include=safety). |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present when the response uses KBA data (dl-de/by-2-0). |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
selection | object | nein | Only 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
brand | Query | string Länge ≥ 1 | nein | Brand name (known spellings of the same brand match, case and accents ignored) or brand id from /v2/brands. |
model | Query | string Länge ≥ 1 | nein | Model field of the vehicle contains this text (case and accents ignored). |
model_id | Query | string Muster: ^[a-z0-9-]{1,120}$ | nein | Model id from /v2/brands/{brand_id}/models; needs brand = the brand id. |
pcd | Query | string Länge ≥ 1 | nein | Bolt pattern, e.g. 5x112. |
limit | Query | integer min 1 max 100 | nein | Page size (default 50). |
cursor | Query | string | nein | Opaque cursor from meta.next_cursor. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
vehicle_id | string | ja | |
hsn | string | ja | |
tsn | string | ja | |
brand | string | nein | |
model | string | nein | |
years | string | nein | |
display | object | nein | |
identity_only | boolean | nein | |
brand_id | string | nein | Brand id as in /v2/brands (only when the brand is unambiguous). |
brand_logo_url | string | nein | Public logo of the brand (same file as logo_url in /v2/brands).Format: uri |
wheels | object | nein | |
wheels.pcd | string | nein | |
wheels.pcd_status | string | nein | Werte: verified, unverified, missing |
wheels.center_bore_mm | number | nein | |
wheels.center_bore_status | string | nein | Werte: verified, unverified, missing |
wheels.thread | string | nein | |
wheels.torque_nm | number | nein | |
wheels.fastener | string | nein | |
wheels.fastener_code | string | nein | Werte: bolts, nuts |
wheels.mounting | object | nein | |
tpms | object | nein | |
oe_tires | object[] | nein | |
factory_wheels | object | nein | Factory wheels from the certificate of conformity: references and wheel/tyre options; staggered = different front/rear size. Empty values are omitted. |
factory_wheels.references | string[] | nein | |
factory_wheels.options | object[] | nein | |
has_wheels | boolean | nein | |
wheels_unavailable | string | nein | |
selections | object[] | nein | |
selections[].selection_id | string | ja | |
selections[].kind | string | ja | Werte: variant, configuration, alias, execution |
selections[].label | string | nein | Variants and executions: display name. |
selections[].variant_selection_ids | string[] | nein | Executions only: the variants (var_…) of this execution on the vehicle. One entry = the execution is applied like that variant. |
selections[].variant_selection_id | string | nein | Configurations only: linked variant selection, when documented. Keep its technical profile separate from the configuration observations. |
selections[].technical_observations | object[] | nein | Configurations 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_observations | object[] | nein | Configurations only: reported withdrawal records of the type approval. |
selections[].approval_validity | string | nein | Werte: not_determined |
selections[].registration_observations | object[] | nein | Configurations only: annual registration statistics (documented counts and measured values). |
configuration_count | integer | nein | |
insurance | object | nein | Insurance 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.liability | integer | nein | Current liability (third-party) type class. min 0 |
insurance.partial_comprehensive | integer | nein | Current partial comprehensive type class. min 0 |
insurance.full_comprehensive | integer | nein | Current full comprehensive type class. min 0 |
insurance.year | integer | nein | Year of the current type classes: the latest year (YYYY) in history across all lines. Omitted without history. min 1900 |
insurance.history | object | nein | Type class per line and year (key YYYY). |
insurance_unavailable | string | nein | Only with include=insurance: no insurance type classes are known for this vehicle.Werte: no_type_classes |
market | object | nein | include=market: newest figure per metric for this vehicle; never brand, region or class aggregates. |
market.latest | object[] | ja | |
market.scope | string | ja | |
market.reason | string | nein | Why latest is empty. |
market_history | object | nein | include=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.available | boolean | ja | |
market_history.scope | string | ja | |
market_history.hsn_tsn_exact | boolean | nein | |
market_history.registration_history | object[] | nein | Registered vehicles of this HSN/TSN per year, oldest first. |
market_history.registration_trend | object | nein | Change of the stock in percent, calculated from registration_history. |
market_history.reason | string | nein | Why nothing is available. |
safety | object | nein | include=safety: recalls of the validated model (up to 200, newest first) and exact safety figures. |
safety.available | boolean | ja | |
safety.scope | string | ja | |
safety.hsn_tsn_exact | boolean | ja | |
safety.recall_count | integer | ja | min 0 |
safety.recalls | object[] | ja | |
safety.facts | object[] | nein | |
safety.reason | string | nein | Why nothing is available. |
environment | object | nein | include=environment: only figures that refer exactly to this HSN/TSN. |
environment.available | boolean | ja | |
environment.scope | string | ja | |
environment.hsn_tsn_exact | boolean | ja | |
environment.latest | object[] | ja | |
environment.reason | string | nein | Why nothing is available. |
intelligence_unavailable | string | nein | Only with include=market, market_history, safety or environment: the active data release has none of the requested sections.Werte: not_in_release |
data_sheet | object | nein | include=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.sheets | object[] | nein | One data sheet per VSN. |
data_sheet.facts | object | nein | Vehicle facts by name (e.g. length_mm, curb_weight_kg, drivetrain). values only when status is confirmed. |
data_sheet_unavailable | string | nein | Only with include=data_sheet: no data sheet is known for this vehicle.Werte: no_data_sheet |
vehicle_image | object | nein | Only with include=vehicle_image. |
vehicle_image.available | boolean | ja | |
vehicle_image.ambiguous | boolean | ja | |
vehicle_image.delivery_ready | boolean | ja | |
vehicle_image.vehicle_image_id | string | null | nein | |
vehicle_image.label | string | null | nein | |
vehicle_image.thumbnail | object | null | nein | |
vehicle_image.body_match | string | null | nein | Werte: exact, unconfirmed, differs, missing, null |
vehicle_image.body_notice | object | null | nein | |
vehicle_image.matches | object[] | nein | |
selected | object | nein | Only with the selection parameter: the applied selection (as in selections). |
available_sections | object | nein | Only with include=sections: which detail sections have content for this vehicle. |
available_sections.workshop | boolean | ja | Fluid capacities in /technical. |
available_sections.market | boolean | ja | Official market figures (include=market). |
available_sections.recalls | boolean | ja | Recalls (include=safety). |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present when the response uses KBA data (dl-de/by-2-0). |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
total | integer | nein | |
engine_code | string | nein | |
facets | object | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
vehicle_id | Pfad | string Muster: ^[0-9]{4}-[A-Z0-9]{3}$ | ja | HSN-TSN, e.g. 0005-DFY. |
selection | Query | string | nein | Variant selection id (var_…) or an execution id (exe_…) that maps to exactly one variant, from the vehicle; configurations are not supported here. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist ein Objekt.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
vehicle_id | string | ja | |
brand | string | nein | |
model | string | nein | |
wheel_mounting | object | nein | Same as wheels on /v2/vehicles/{vehicle_id}. |
safety_note | string | nein | |
engines_unavailable | string | nein | Engine rows (fluid capacities, axle loads) are withheld because the vehicle has several EU configurations without verified assignment. Werte: configuration_evidence_required |
variants | object[] | ja | |
variants[].vehicle_id | string | nein | |
variants[].selection_id | string | nein | Variant selection id when the variant is a selection of the vehicle. |
variants[].brand | string | nein | |
variants[].model | string | nein | |
variants[].label | string | nein | |
variants[].body | object | nein | |
variants[].dimensions | object | nein | |
variants[].powertrain | object | nein | |
variants[].production | object | nein | |
variants[].weights | object | nein | |
variants[].towing | object | nein | |
variants[].engine | object | nein | |
variants[].completeness | integer | ja | Number of documented technical fields. |
variants[].engines | object[] | nein |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present when the response uses KBA data (dl-de/by-2-0). |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
total | integer | nein | Wheel offer list only: number of offers matching the request over all pages. min 0 |
selection | object | nein | |
selection.id | string | null | nein | |
selection.type | string | null | nein | |
selection.status | string | ja | none: 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_id | string | nein | Superseded keys only: the successor that was applied. |
selection.applied_ids | string[] | nein | The 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
vehicle_id | Pfad | string Muster: ^[0-9]{4}-[A-Z0-9]{3}$ | ja | HSN-TSN, e.g. 0005-DFY. |
limit | Query | integer min 1 max 100 | nein | Page size (default 50). |
cursor | Query | string | nein | Opaque cursor from meta.next_cursor. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
include | Query | string Werte: registrations | nein | registrations: annual registration statistics per configuration (registration_observations). Opt-in because a single configuration can carry several megabytes of statistics. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
selection_id | string | ja | |
kind | string | ja | Werte: variant, configuration, alias, execution |
label | string | nein | Variants and executions: display name. |
variant_selection_ids | string[] | nein | Executions only: the variants (var_…) of this execution on the vehicle. One entry = the execution is applied like that variant. |
variant_selection_id | string | nein | Configurations only: linked variant selection, when documented. Keep its technical profile separate from the configuration observations. |
technical_observations | object[] | nein | Configurations 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[].field | string | ja | |
technical_observations[].value | number | string | nein | |
technical_observations[].minimum | number | nein | |
technical_observations[].maximum | number | nein | |
technical_observations[].unit | string | nein | |
technical_observations[].measurement_basis | string | ja | |
technical_observations[].context | object | nein | |
technical_observations[].confirmed | boolean | nein | Present (false) only when the value is not confirmed by further data. fester Wert: false |
approval_observations | object[] | nein | Configurations only: reported withdrawal records of the type approval. |
approval_observations[].kind | string | ja | |
approval_observations[].scope | string | ja | |
approval_observations[].record_position | string | ja | |
approval_observations[].reported_start | string | ja | |
approval_observations[].reported_end | string | nein | |
approval_validity | string | nein | Werte: not_determined |
registration_observations | object[] | nein | Configurations only: annual registration statistics (documented counts and measured values). |
registration_observations[].observation_id | string | ja | Muster: ^[a-f0-9]{64}$ |
registration_observations[].measurement_basis | string | ja | fester Wert: "annual_registration_statistics" |
registration_observations[].context | object | ja | |
registration_observations[].rows | integer | ja | min 0 |
registration_observations[].represented_registrations | integer | ja | min 0 |
registration_observations[].unknown_registration_count_rows | integer | ja | min 0 |
registration_observations[].unknown_registration_date_rows | integer | ja | min 0 |
registration_observations[].earliest_registration_date | string | nein | YYYY-MM-DD; missing when no date is known. |
registration_observations[].latest_registration_date | string | nein | YYYY-MM-DD; missing when no date is known. |
registration_observations[].combinations | object[] | 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
}
}Fahrzeugsuche
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
q | Query | string | nein | Brand, model, label or engine code contains this text. |
brand | Query | string | nein | Brand contains this text. |
model | Query | string | nein | Model or label contains this text. |
body_type | Query | string | nein | Comma-separated: suv, wagon, coupe, convertible, van, pickup, small_car, hatchback, sedan, other. |
fuel | Query | string | nein | Comma-separated: petrol, diesel, electric, hybrid, gas, hydrogen, other, unknown. |
transmission | Query | string | nein | Comma-separated: manual, automatic, other, unknown. |
drive_type | Query | string | nein | Comma-separated: front, rear, awd, other, unknown. |
doors | Query | integer min 0 | nein | Exact doors. |
seats | Query | integer min 0 | nein | Exact seats. |
production_start | Query | integer min 0 | nein | Exact production start. |
production_end | Query | integer min 0 | nein | Exact production end. |
min_length_mm | Query | integer min 0 | nein | Minimum length mm. |
max_length_mm | Query | integer min 0 | nein | Maximum length mm. |
min_width_mm | Query | integer min 0 | nein | Minimum width mm. |
max_width_mm | Query | integer min 0 | nein | Maximum width mm. |
min_height_mm | Query | integer min 0 | nein | Minimum height mm. |
max_height_mm | Query | integer min 0 | nein | Maximum height mm. |
min_power_kw | Query | integer min 0 | nein | Minimum power kw. |
max_power_kw | Query | integer min 0 | nein | Maximum power kw. |
min_braked_kg | Query | integer min 0 | nein | Minimum braked kg. |
max_braked_kg | Query | integer min 0 | nein | Maximum braked kg. |
min_nose_weight_kg | Query | integer min 0 | nein | Minimum nose weight kg. |
max_nose_weight_kg | Query | integer min 0 | nein | Maximum nose weight kg. |
production_year | Query | integer min 0 | nein | Built in this year (documented period; ongoing production counts from its start). |
include | Query | string Werte: facets | nein | facets: counts per brand, body type, fuel, transmission and drive type for the whole result. |
limit | Query | integer min 1 max 100 | nein | Page size (default 50). |
cursor | Query | string | nein | Opaque cursor from meta.next_cursor. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
vehicle_id | string | nein | |
selection_id | string | nein | Variant selection id when the variant is a selection of the vehicle. |
brand | string | nein | |
model | string | nein | |
label | string | nein | |
body | object | nein | |
body.type | string | nein | Werte: suv, wagon, coupe, convertible, van, pickup, small_car, hatchback, sedan, other |
body.label | string | nein | |
body.doors | integer | nein | |
body.seats | integer | nein | |
dimensions | object | nein | |
dimensions.length_mm | integer | nein | |
dimensions.width_mm | integer | nein | |
dimensions.height_mm | integer | nein | |
powertrain | object | nein | |
powertrain.fuel | string | nein | Werte: petrol, diesel, electric, hybrid, gas, hydrogen, other, unknown |
powertrain.fuel_label | string | nein | |
powertrain.transmission | string | nein | Werte: manual, automatic, other, unknown |
powertrain.transmission_label | string | nein | |
powertrain.drive_type | string | nein | Werte: front, rear, awd, other, unknown |
powertrain.drive_type_label | string | nein | |
powertrain.power_kw | integer | nein | |
powertrain.power_ps | integer | nein | |
powertrain.displacement_ccm | integer | nein | |
production | object | nein | |
production.start_year | integer | nein | |
production.end_year | integer | nein | |
production.end_status | string | ja | Werte: documented, ongoing, unknown |
weights | object | nein | |
weights.curb_kg | integer | nein | |
weights.gross_kg | integer | nein | |
towing | object | nein | |
towing.braked_kg | integer | nein | |
towing.unbraked_kg | integer | nein | |
towing.nose_weight_kg | integer | nein | |
engine | object | nein | |
engine.type | string | nein | |
engine.codes | string[] | nein | |
engine.codes_normalized | string[] | nein | |
completeness | integer | ja | Number of documented technical fields. |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present when the response uses KBA data (dl-de/by-2-0). |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
total | integer | nein | |
engine_code | string | nein | |
facets | object | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
q | Query | string | nein | Engine code contains this text. |
brand | Query | string | nein | Brand contains this text. |
fuel | Query | string | nein | Comma-separated: petrol, diesel, electric, hybrid, gas, hydrogen, other, unknown. |
limit | Query | integer min 1 max 100 | nein | Page size (default 50). |
cursor | Query | string | nein | Opaque cursor from meta.next_cursor. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
engine_code | string | ja | |
display_code | string | nein | |
engine_type | string | nein | |
fuel | string | nein | |
displacement_ccm | integer | nein | |
power_kw_min | integer | nein | |
power_kw_max | integer | nein | |
vehicle_count | integer | ja | |
application_count | integer | ja |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present when the response uses KBA data (dl-de/by-2-0). |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
total | integer | nein | |
engine_code | string | nein | |
facets | object | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
engine_code | Pfad | string | ja | Engine code from /v2/engine-codes. |
limit | Query | integer min 1 max 100 | nein | Page size (default 50). |
cursor | Query | string | nein | Opaque cursor from meta.next_cursor. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
vehicle_id | string | nein | |
selection_id | string | nein | Variant selection id when the variant is a selection of the vehicle. |
brand | string | nein | |
model | string | nein | |
label | string | nein | |
body | object | nein | |
body.type | string | nein | Werte: suv, wagon, coupe, convertible, van, pickup, small_car, hatchback, sedan, other |
body.label | string | nein | |
body.doors | integer | nein | |
body.seats | integer | nein | |
dimensions | object | nein | |
dimensions.length_mm | integer | nein | |
dimensions.width_mm | integer | nein | |
dimensions.height_mm | integer | nein | |
powertrain | object | nein | |
powertrain.fuel | string | nein | Werte: petrol, diesel, electric, hybrid, gas, hydrogen, other, unknown |
powertrain.fuel_label | string | nein | |
powertrain.transmission | string | nein | Werte: manual, automatic, other, unknown |
powertrain.transmission_label | string | nein | |
powertrain.drive_type | string | nein | Werte: front, rear, awd, other, unknown |
powertrain.drive_type_label | string | nein | |
powertrain.power_kw | integer | nein | |
powertrain.power_ps | integer | nein | |
powertrain.displacement_ccm | integer | nein | |
production | object | nein | |
production.start_year | integer | nein | |
production.end_year | integer | nein | |
production.end_status | string | ja | Werte: documented, ongoing, unknown |
weights | object | nein | |
weights.curb_kg | integer | nein | |
weights.gross_kg | integer | nein | |
towing | object | nein | |
towing.braked_kg | integer | nein | |
towing.unbraked_kg | integer | nein | |
towing.nose_weight_kg | integer | nein | |
engine | object | nein | |
engine.type | string | nein | |
engine.codes | string[] | nein | |
engine.codes_normalized | string[] | nein | |
completeness | integer | ja | Number of documented technical fields. |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present when the response uses KBA data (dl-de/by-2-0). |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
total | integer | nein | |
engine_code | string | nein | |
facets | object | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
vehicle_id | Pfad | string Muster: ^[0-9]{4}-[A-Z0-9]{3}$ | ja | HSN-TSN, e.g. 0005-DFY. |
selection | Query | string | nein | Selection 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_code | Query | string | nein | Comma-separated, up to 50. |
brand | Query | string Länge ≥ 1 | nein | Wheel 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_inch | Query | number | nein | Rim diameter. |
et_mm | Query | number | nein | Offset (ET) in mm. |
pcd | Query | string Länge ≥ 1 | nein | Bolt pattern, e.g. 5x112 (case-insensitive). |
status | Query | string Werte: no_registration, registration_required, unknown, not_fitting | nein | Offer status. |
tire_size | Query | string | nein | Tire size, e.g. 225/45R18. |
view | Query | string Werte: summary, full | nein | summary (default) or full with tires, tire pairs, sets and obligation texts. |
limit | Query | integer min 1 max 100 | nein | Page size (default 50, with view=full 20). |
cursor | Query | string | nein | Opaque cursor from meta.next_cursor. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
offer_id | string | ja | |
wheel_code | string | ja | |
width_inch | number | nein | |
diameter_inch | number | nein | |
et_mm | number | nein | |
pcd | string | nein | |
center_bore_mm | number | nein | |
axle | string | nein | Werte: front, rear, both |
status | string | ja | Werte: no_registration, registration_required, unknown, not_fitting |
reason | string | nein | |
match | string | nein | Werte: vehicle, geometry_only |
document_ids | string[] | nein | |
centering | object | nein | |
selection_recommended | boolean | nein | |
tire_combination | string | nein | How 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 |
tires | object[] | nein | view=full only |
tires[].size | string | ja | |
tires[].axle | string | ja | Werte: front, rear, both |
tires[].status | string | ja | Werte: no_registration, registration_required, unknown, not_fitting |
tires[].load_index | string | number | nein | |
tires[].obligations | string[] | nein | |
tires[].blocking_obligations | string[] | nein | |
tires[].open_obligations | string[] | nein | |
tires[].reason | string | nein | |
tires[].violated_conditions | any[] | nein | |
tires[].requires_bodywork | boolean | nein | |
tires[].hints | string[] | nein | |
tire_sizes | string[] | nein | view=summary only |
allowed_pairs | object[] | nein | view=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_tire | string | ja | |
allowed_pairs[].rear_tire | string | ja | |
allowed_pairs[].obligation | string | ja |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
included | object | nein | view=full only |
included.sets | object[] | nein | |
included.documents | object | nein | |
attribution | object[] | nein | Present when the response uses KBA data (dl-de/by-2-0). |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
total | integer | nein | Wheel offer list only: number of offers matching the request over all pages. min 0 |
selection | object | nein | |
selection.id | string | null | nein | |
selection.type | string | null | nein | |
selection.status | string | ja | none: 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_id | string | nein | Superseded keys only: the successor that was applied. |
selection.applied_ids | string[] | nein | The 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
vehicle_id | Pfad | string Muster: ^[0-9]{4}-[A-Z0-9]{3}$ | ja | HSN-TSN, e.g. 0005-DFY. |
wheel_code | Pfad | string | ja | Wheel code. |
selection | Query | string | nein | Selection id. |
diameter_inch | Query | number | nein | Rim diameter. |
et_mm | Query | number | nein | Offset (ET) in mm. |
pcd | Query | string Länge ≥ 1 | nein | Bolt pattern, e.g. 5x112 (case-insensitive). |
status | Query | string Werte: no_registration, registration_required, unknown, not_fitting | nein | Offer status. |
tire_size | Query | string | nein | Tire size, e.g. 225/45R18. |
view | Query | string Werte: summary, full | nein | Accepted for symmetry with /wheels; this endpoint always answers like view=full. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
offer_id | string | ja | |
wheel_code | string | ja | |
width_inch | number | nein | |
diameter_inch | number | nein | |
et_mm | number | nein | |
pcd | string | nein | |
center_bore_mm | number | nein | |
axle | string | nein | Werte: front, rear, both |
status | string | ja | Werte: no_registration, registration_required, unknown, not_fitting |
reason | string | nein | |
match | string | nein | Werte: vehicle, geometry_only |
document_ids | string[] | nein | |
centering | object | nein | |
selection_recommended | boolean | nein | |
tire_combination | string | nein | How 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 |
tires | object[] | nein | view=full only |
tires[].size | string | ja | |
tires[].axle | string | ja | Werte: front, rear, both |
tires[].status | string | ja | Werte: no_registration, registration_required, unknown, not_fitting |
tires[].load_index | string | number | nein | |
tires[].obligations | string[] | nein | |
tires[].blocking_obligations | string[] | nein | |
tires[].open_obligations | string[] | nein | |
tires[].reason | string | nein | |
tires[].violated_conditions | any[] | nein | |
tires[].requires_bodywork | boolean | nein | |
tires[].hints | string[] | nein | |
tire_sizes | string[] | nein | view=summary only |
allowed_pairs | object[] | nein | view=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_tire | string | ja | |
allowed_pairs[].rear_tire | string | ja | |
allowed_pairs[].obligation | string | ja |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
included | object | nein | view=full only |
included.sets | object[] | nein | |
included.documents | object | nein | |
attribution | object[] | nein | Present when the response uses KBA data (dl-de/by-2-0). |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
total | integer | nein | Wheel offer list only: number of offers matching the request over all pages. min 0 |
selection | object | nein | |
selection.id | string | null | nein | |
selection.type | string | null | nein | |
selection.status | string | ja | none: 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_id | string | nein | Superseded keys only: the successor that was applied. |
selection.applied_ids | string[] | nein | The 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
brand | Query | string | nein | Wheel brand, case-insensitive. Other names of the same brand match too (MM-Concepts = MM-Wheels). |
q | Query | string Länge 2–50 | nein | Search code, model or brand. |
diameter_inch | Query | number | nein | Available diameter. |
include | Query | string Werte: colors | nein | colors: colors with all image views per wheel in the list (saves one detail request per wheel). |
limit | Query | integer min 1 max 100 | nein | Page size (default 50). |
cursor | Query | string | nein | Opaque cursor from meta.next_cursor. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
wheel_code | string | ja | |
brand | string | nein | |
model_name | string | nein | |
design | string | nein | |
classification | object | nein | |
diameters_inch | number[] | nein | |
vehicle_count | integer | nein | |
variant_count | integer | nein | |
color_count | integer | nein | |
document_count | integer | nein | |
preview | object | nein | |
updated_at | string | nein | |
colors | object[] | nein | Only with include=colors. |
colors[].name | string | ja | |
colors[].classification | object | nein | |
colors[].views | object | ja |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
total | integer | nein | |
engine_code | string | nein | |
facets | object | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
wheel_code | Pfad | string | ja | Wheel code. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist ein Objekt.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
wheel_code | string | ja | |
brand | string | nein | |
model_name | string | nein | |
design | string | nein | |
classification | object | nein | |
diameters_inch | number[] | nein | |
vehicle_count | integer | nein | |
variant_count | integer | nein | |
color_count | integer | nein | |
document_count | integer | nein | |
preview | object | nein | |
updated_at | string | nein | |
description | string | nein | |
showcase | object | nein | |
colors | object[] | nein | |
colors[].name | string | ja | |
colors[].classification | object | nein | |
colors[].views | object | ja | |
variants | object[] | nein | |
variants[].sku | string | nein | |
variants[].size | string | nein | |
variants[].width_inch | number | nein | |
variants[].diameter_inch | number | nein | |
variants[].et_mm | number | nein | |
variants[].pcd | string | nein | |
variants[].center_bore_mm | number | nein | |
variants[].color | string | nein | |
variants[].classification | object | nein | |
documents | object[] | nein | |
documents[].document_id | string | ja | |
documents[].approval_type | string | nein | |
documents[].approval_number | string | nein |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
wheel_code | Query | string | nein | Comma-separated wheel codes, up to 50. |
brand | Query | string Länge ≥ 1 | nein | Wheel brand as in the wheel catalog (/v2/wheels), case-insensitive. Other names of the same brand match too (MM-Concepts = MM-Wheels). |
limit | Query | integer min 1 max 100 | nein | Page size (default 50). |
cursor | Query | string | nein | Opaque cursor from meta.next_cursor. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
document_id | string | ja | |
wheel_code | string | ja | |
approval_type | string | nein | |
approval_number | string | nein | |
kba_number | string | nein | |
entries | object[] | nein | Wheel geometries covered by the document. |
entries[].pcd | string | nein | |
entries[].center_bore_mm | number | nein | |
entries[].et_mm | number | nein | |
entries[].width_inch | number | nein | |
entries[].diameter_inch | number | nein | |
entries[].approvals | object[] | nein | |
obligation_codes | string[] | nein | |
fasteners | object[] | nein | Bolts or nuts named by the document (code S01, S02 …). |
fasteners[].code | string | ja | |
fasteners[].type | string | nein | |
fasteners[].thread | string | nein | |
fasteners[].seat | string | nein | |
fasteners[].seat_diameter_mm | number | nein | |
fasteners[].seat_angle_deg | number | nein | |
fasteners[].torque_nm | number | nein | |
fasteners[].shaft_length_mm | number | nein | |
fasteners[].shaft_length_status | string | nein | |
fasteners[].row_status | string | nein | |
fasteners[].missing_fields | string[] | nein | |
fastener_status | string | nein | |
url | string | null | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
document_id | Pfad | string Muster: ^doc_[a-f0-9]{24}$ | ja | Document id. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist ein Objekt.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
document_id | string | ja | |
approval_type | string | nein | |
approval_number | string | nein | |
kba_number | string | nein | |
obligations | object | nein | |
url | string | null | nein |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
brand | Query | string Länge ≥ 1 | nein | Brand 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. |
model | Query | string Länge ≥ 1 | nein | Model field of the vehicle contains this text (case and accents ignored). |
model_id | Query | string Muster: ^[a-z0-9-]{1,120}$ | nein | Model id from /v2/brands/{brand_id}/models; needs brand = the brand id. Matches all vehicles the navigation lists under this model. |
limit | Query | integer min 1 max 100 | nein | Page size (default 50). |
cursor | Query | string | nein | Opaque cursor from meta.next_cursor. |
data_version | Query | string | nein | Optional: fail with 409 if the active data release differs. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist eine Liste; die Felder gelten je Eintrag.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
vehicle_id | string | ja | |
hsn | string | ja | |
tsn | string | ja | |
brand | string | nein | As on /v2/vehicles/{vehicle_id}. |
model | string | nein | As on /v2/vehicles/{vehicle_id}. |
insurance | object | ja | Insurance 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.liability | integer | nein | Current liability (third-party) type class. min 0 |
insurance.partial_comprehensive | integer | nein | Current partial comprehensive type class. min 0 |
insurance.full_comprehensive | integer | nein | Current full comprehensive type class. min 0 |
insurance.year | integer | nein | Year of the current type classes: the latest year (YYYY) in history across all lines. Omitted without history. min 1900 |
insurance.history | object | nein | Type class per line and year (key YYYY). |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present when the response uses KBA data (dl-de/by-2-0). |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
total | integer | nein | |
engine_code | string | nein | |
facets | object | nein |
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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist ein Objekt.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
status | string | ja | fester Wert: "ok" |
data_version | string | ja |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
If-None-Match | Header | string | nein | Do 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.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
api_key | string | ja | |
label | string | null | nein | |
month | string | ja | |
requests_this_month | integer | ja | |
monthly_limit | integer | null | nein | |
remaining | integer | null | nein | |
quota_scope | string | nein | account: 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_counter | integer | null | nein | Lifetime count of admitted V2 requests across this account, including revoked keys. |
quota_reported_at | integer | null | nein | Unix seconds of the last account allowance report. Older reports remain valid. |
quota_warning | string | null | nein | |
key_requests_this_month | integer | nein | Requests of this key this month. |
key_monthly_limit | integer | null | nein | Own monthly limit of this key, if one is set; null = none. |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
from | Query | string Format: date | nein | First day (UTC), YYYY-MM-DD. Default: 29 days before to. |
to | Query | string Format: date | nein | Last day (UTC), YYYY-MM-DD. Default: today. |
If-None-Match | Header | string | nein | Do 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.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
api_key | string | ja | |
from | string | ja | Format: date |
to | string | ja | Format: date |
requests | integer | ja | min 0 |
over_quota | integer | nein | Requests in the period that were rejected with 429 rate_limited because the monthly quota was used up (part of requests).min 0 |
endpoints | object[] | ja | Totals per endpoint over the period. |
endpoints[].endpoint | string | ja | Path template as in this description, e.g. /v2/vehicles/{vehicle_id}/wheels. |
endpoints[].requests | integer | ja | min 1 |
days | object[] | ja | |
days[].day | string | ja | Format: date |
days[].requests | integer | ja | min 0 |
days[].over_quota | integer | nein | min 1 |
days[].endpoints | object[] | ja |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
vehicle_id | Pfad | string Muster: ^[0-9]{4}-[A-Z0-9]{3}$ | ja | HSN-TSN, e.g. 0005-DFY. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist ein Objekt.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
available | boolean | ja | |
ambiguous | boolean | ja | |
matches | object[] | ja | |
matches[].vehicle_image | object | ja | |
matches[].matched_by | string | ja | Werte: vehicle_id, vehicle_image_id |
matches[].fitment_checked | boolean | ja | |
matches[].wheels | object[] | ja | |
matches[].original_wheels | object | nein | The vehicle with its original wheels in every paint (wheel_code original; no fitment check); renditions include the small sizes. |
body_notice | object | null | ja | |
body_notice.code | string | nein | Werte: body_image_missing, body_differs, body_unconfirmed |
body_notice.message | string | nein |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
vehicle_id | Pfad | string Muster: ^[0-9]{4}-[A-Z0-9]{3}$ | ja | HSN-TSN, e.g. 0005-DFY. |
wheel_code | Pfad | string | ja | Wheel code from the availability, or original for the original wheels. |
paint | Query | string | nein | Paint id from the availability (required). |
finish | Query | string | nein | Finish id from the availability (required except for wheel_code=original; older finish ids from finish_aliases are accepted). |
size | Query | integer min 1 max 30 | nein | Wheel size in inches (default: default_wheel_size). |
delivery | Query | string Werte: render, layers | nein | render (default) or layers. |
vehicle_image_id | Query | string | nein | Image group, needed when the vehicle belongs to several groups (409 configurator_vehicle_ambiguous). |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist ein Objekt.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
vehicle_image | object | ja | |
vehicle_image.vehicle_image_id | string | ja | |
vehicle_image.label | string | ja | |
vehicle_image.brand | string | null | nein | |
vehicle_image.model | string | null | nein | |
vehicle_image.generation | string | null | nein | |
vehicle_image.body_type | string | null | nein | |
vehicle_image.years | object | nein | |
vehicle_image.body_match | string | nein | Only when matched by vehicle: exact body type, unconfirmed (body type of the vehicle not confirmed) or differs. Werte: exact, unconfirmed, differs |
vehicle_image.body_notice | object | null | nein | |
matched_by | string | nein | Werte: vehicle_id, vehicle_image_id |
fitment_checked | boolean | nein | |
delivery | string | ja | Werte: edge_render, layers, full_images |
render_order | string[] | nein | |
selection | object | ja | |
selection.wheel_code | string | ja | |
selection.paint | string | ja | |
selection.finish | string | null | ja | null for wheel_code original. |
selection.size | integer | null | nein | |
selection.requested_finish | string | nein | The older finish id sent, when it was mapped to finish. |
revision | string | ja | |
views | object | ja | Per view and rendition: an image (url, expires_at, width, height) or, with delivery=layers, canvas, base and layers. |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
urls_expire_at | string | null | nein | Earliest 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
vehicle_image_id | Pfad | string Muster: ^[a-z0-9_-]{1,80}$ | ja | Image group id. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist ein Objekt.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
available | boolean | ja | |
ambiguous | boolean | ja | |
matches | object[] | ja | |
matches[].vehicle_image | object | ja | |
matches[].matched_by | string | ja | Werte: vehicle_id, vehicle_image_id |
matches[].fitment_checked | boolean | ja | |
matches[].wheels | object[] | ja | |
matches[].original_wheels | object | nein | The vehicle with its original wheels in every paint (wheel_code original; no fitment check); renditions include the small sizes. |
body_notice | object | null | ja | |
body_notice.code | string | nein | Werte: body_image_missing, body_differs, body_unconfirmed |
body_notice.message | string | nein |
Weitere Felder der Antwort
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
attribution | object[] | nein | Present 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
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
vehicle_image_id | Pfad | string Muster: ^[a-z0-9_-]{1,80}$ | ja | Image group id. |
wheel_code | Pfad | string | ja | Wheel code, or original for the original wheels. |
paint | Query | string | nein | Paint id (required). |
finish | Query | string | nein | Finish id (required except for wheel_code=original). |
size | Query | integer min 1 max 30 | nein | Wheel size in inches (default: default_wheel_size). |
delivery | Query | string Werte: render, layers | nein | render (default) or layers. |
If-None-Match | Header | string | nein | ETag for the same request; unchanged: 304 without a body. |
Antwortfelder
data ist ein Objekt.
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
vehicle_image | object | ja | |
vehicle_image.vehicle_image_id | string | ja | |
vehicle_image.label | string | ja | |
vehicle_image.brand | string | null | nein | |
vehicle_image.model | string | null | nein | |
vehicle_image.generation | string | null | nein | |
vehicle_image.body_type | string | null | nein | |
vehicle_image.years | object | nein | |
vehicle_image.body_match | string | nein | Only when matched by vehicle: exact body type, unconfirmed (body type of the vehicle not confirmed) or differs. Werte: exact, unconfirmed, differs |
vehicle_image.body_notice | object | null | nein | |
matched_by | string | nein | Werte: vehicle_id, vehicle_image_id |
fitment_checked | boolean | nein | |
delivery | string | ja | Werte: edge_render, layers, full_images |
render_order | string[] | nein | |
selection | object | ja | |
selection.wheel_code | string | ja | |
selection.paint | string | ja | |
selection.finish | string | null | ja | null for wheel_code original. |
selection.size | integer | null | nein | |
selection.requested_finish | string | nein | The older finish id sent, when it was mapped to finish. |
revision | string | ja | |
views | object | ja | Per view and rendition: an image (url, expires_at, width, height) or, with delivery=layers, canvas, base and layers. |
Felder in meta
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
urls_expire_at | string | null | nein | Earliest 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.
| HTTP | Bedeutung | Codes |
|---|---|---|
400 Ungültige Anfrage | Invalid request (unknown_parameter, duplicate_parameter, invalid_…, selection or variant not for the vehicle) | unknown_parameter, duplicate_parameter, invalid_include |
401 Nicht angemeldet | Missing or invalid credentials (unauthorized, invalid_credentials) | invalid_credentials, unauthorized |
403 Zugriff verweigert | Key inactive (subscription_inactive) or add-on module not enabled for the key (feature_not_enabled) | subscription_inactive, feature_not_enabled |
404 Nicht gefunden | Not found | wheel_size_not_approved_for_vehicle, vehicle_not_found |
409 Konflikt | Data 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 Anfragen | Monthly 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ügbar | No 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
| Name | Typ | Immer vorhanden | Beschreibung |
|---|---|---|---|
error | object | ja | |
error.code | string | ja | |
error.message | string | ja | |
error.status | integer | ja | |
error.details | object | nein |
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.
| Funktion | V1 | V2 |
|---|---|---|
| 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 })undbrands({ withLogo: true }). Ungültige Cursorinhalte ergeben 400invalid_cursor.
Bisherige API – läuft weiter. Für neue Integrationen nimm API V2.
Umstieg auf V2api4cars Integration
Einführung
Die api4cars API liefert Fahrzeugdaten zu deutschen HSN/TSN-Schlüsselnummern sowie darauf aufbauend Felgen- und Reifenfreigaben aus Teilegutachten und ABE. Alle Endpunkte sind GET-Anfragen und antworten mit JSON.
Basis-URL: https://api4cars.com/wp-json/carapi/v1/
Endpunkte ohne Kennzeichnung sind stabil. Endpunkte mit Alpha sind nutzbar; ihr Umfang und zusätzliche Antwortfelder können sich vor der stabilen Freigabe erweitern.
Begriffe
| Begriff | Parameter | Bedeutung |
|---|---|---|
| Fahrzeug | hsn + tsn | Herstellerschlüsselnummer (4 Ziffern) und Typschlüsselnummer (3 Zeichen) aus der Zulassungsbescheinigung Teil I (Felder 2.1 und 2.2). Jede fahrzeugbezogene Anfrage adressiert ein Fahrzeug über dieses Paar. |
| Variante | variant_key | Eine Fahrzeugvariante innerhalb eines HSN/TSN-Paars, z. B. eine bestimmte Motorisierung, Karosserie oder Radgeometrie. Die Varianten eines Fahrzeugs stehen in variants[]. |
| Konfiguration | configuration_id | Eine Genehmigungskonfiguration: Typgenehmigung einschließlich Nachtrag sowie Typ, Variante und Version. Sie beschreibt nicht die individuelle Ausstattung eines einzelnen Fahrzeugs. Die Konfigurationen eines Fahrzeugs liefert /vehicle-configurations. |
| Genehmigungsweg | – | Eine Fahrzeugzeile eines Gutachtens, die eine Felgen-/Reifenkombination für ein Fahrzeug freigibt. Mehrere Genehmigungswege für dieselbe Kombination sind Alternativen. |
| Ausführung | execution_key | Karosserieform einer Generation (z. B. Limousine, Avant). Dient ausschließlich der Navigation in /engines. |
| Passungsstatus | – | Ergebnis der Prüfung einer Felgen-/Reifenkombination: eintragungsfrei, mit_eintragung, nicht_passend oder unknown (siehe Passungsstatus). |
Authentifizierung
Alle Kundenanfragen erfordern einen gültigen API Key, das zugehörige API Secret und ein aktives Abonnement. Die Zugangsdaten stehen nach der Registrierung auf der Account-Seite. Zugangsdaten nur serverseitig verwenden und nie im Browser ausliefern.
Methode 1: Eigene Header
curl -H "X-API-Key: carapi_live_xxxx" \
-H "X-API-Secret: IHR_SECRET" \
"https://api4cars.com/wp-json/carapi/v1/compatibility?hsn=0603&tsn=COB"Methode 2: Bearer Token
curl -H "Authorization: Bearer carapi_live_xxxx:IHR_SECRET" \
"https://api4cars.com/wp-json/carapi/v1/compatibility?hsn=0603&tsn=COB"| HTTP | Code | Bedeutung |
|---|---|---|
401 | rest_unauthorized | Keine Zugangsdaten gesendet |
401 | rest_invalid_api_key | API Key unbekannt oder widerrufen |
401 | rest_invalid_api_secret | API Secret passt nicht zum API Key |
403 | rest_subscription_inactive | Abonnement nicht aktiv |
429 | – | Anfragekontingent des Tarifs ausgeschöpft |
Grundlagen
Antwortformat
Erfolgreiche Antworten sind JSON-Objekte oder JSON-Listen mit HTTP 200. Nicht belegte Werte sind null oder fehlen; leere Treffermengen sind leere Listen. Fehlerantworten haben die Form {"code", "message", "data": {"status"}} (siehe Fehlerreferenz).
Antwortprofile mit include
include gilt je Endpunkt: /compatibility wählt damit Antwortbereiche, /vehicle ergänzt Zusatzbereiche, /gutachten wählt den Umfang der Dokumentangaben, /generations ergänzt Ausführungen und /vehicle-search ergänzt Facetten. /fitments kennt include nicht und steuert den Umfang über compact.
Paginierung
Listenendpunkte mit großen Treffermengen nehmen page (ab 1) und per_page an. Grenzen und Standardwerte stehen beim jeweiligen Endpunkt. /fitments paginiert im Profil compact=1 vollständige Felgenserien und sichert Folgeseiten mit data_version ab.
Caching und ETag
Erfolgreiche Antworten tragen einen ETag, der Route, vollständige Query und Antwortdaten berücksichtigt, sowie Cache-Control: private, max-age=…, must-revalidate. /compatibility ist fünf Minuten gültig, andere Endpunkte eine Stunde; /intelligence/* und /configurator/* nennen ihre Gültigkeit beim Endpunkt. Eine identische Anfrage mit passendem If-None-Match erhält HTTP 304 ohne Inhalt. Fehlerantworten werden nicht zwischengespeichert. Einen eigenen Cache immer über die vollständige Query einschließlich variant_key und configuration_id bilden.
Unbekannte Parameter und Warnungen
Unbekannte Query-Parameter werden nicht abgewiesen, sondern in meta.warnings und im Header X-API4Cars-Warnings genannt (übergangsweise zusätzlich X-CarAPI-Warnings) (unknown query parameter: name). Beide Header sind für Browser-Integrationen per CORS lesbar. Gemeldete Parameter aus der Integration entfernen; künftig können sie mit HTTP 400 abgelehnt werden, eine solche Umstellung wird vorab angekündigt. Bereits heute mit HTTP 400 rest_unknown_param abgelehnt werden limit und include bei /fitments sowie unbekannte Parameter bei /intelligence/* und bei /vehicle mit include=market, safety oder environment. meta.warnings meldet außerdem selection_unavailable_release_mismatch (siehe Auswahlstatus).
Quellenangabe (Kraftfahrt-Bundesamt)
Nutzen die gelieferten Fahrzeugdaten Daten des Kraftfahrt-Bundesamtes, trägt die Antwort einmal das Feld attribution: eine Liste mit einem Eintrag je Quelle (heute nur das KBA) mit publisher (Bereitsteller), license (name, id = dl-de/by-2-0, url), datasets[] (name, url) und note (Hinweis auf veränderte Daten). Abrufe zu einem Fahrzeug tragen es nur, wenn dessen Daten KBA-Daten nutzen; Katalog- und Suchabrufe tragen es immer. Antworten, die eine Liste sind, nennen die Quelle im Header X-API4Cars-Attribution (per CORS lesbar). Wer diese Daten weitergibt oder anzeigt, übernimmt die Quellenangabe.
Anfragekontingent
Jede erfolgreich authentifizierte Anfrage zählt auf das Kontingent des gebuchten Tarifs. Ist es ausgeschöpft, antwortet die API mit HTTP 429. Antworten im eigenen Cache halten und mit If-None-Match revalidieren.
Markennamen
Markenparameter akzeptieren gleichwertige Schreibweisen, z. B. VW und Volkswagen.
Fahrzeugauswahl
Jede fahrzeugbezogene Anfrage adressiert ein Fahrzeug über hsn und tsn. Optional wird das Fahrzeug weiter eingegrenzt: entweder mit variant_key (Variante) oder mit configuration_id (Genehmigungskonfiguration). Beide Wege sind gleichwertig; höchstens einen der beiden Parameter senden. Ohne Eingrenzung wertet die API alle Varianten des HSN/TSN-Paars aus.
Fahrzeugadresse
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
hsn | String (4) | ja | Herstellerschlüsselnummer, z. B. 0603 |
tsn | String (3) | ja | Typschlüsselnummer, z. B. COB; Groß-/Kleinschreibung egal |
variant_key | String | nein | Schlüssel aus variants[].variant_key desselben Fahrzeugs. Groß-/Kleinschreibung egal; höchstens 160 Zeichen aus A–Z a–z 0–9 . _ -. |
vsn | String | nein | Variante/Version aus dem Fahrzeugschein, Feld 2.2, Stellen 4–8 (fünf Zeichen, z. B. 00011; eine angehängte Prüfziffer wird angenommen, aber nicht geprüft). Führt genau eine Variante diese VSN, ist sie vorgewählt wie mit variant_key. Die Antwort trägt dann zusätzlich vsn_selection (vsn, status = matched, ambiguous, unknown, not_determinable oder matched_not_applied, variant_key, hint). 00000, unbekannte oder mehrdeutige VSN: Antwort wie ohne vsn, mit Hinweis „Ausführung nicht bestimmbar“. Ein angegebener variant_key oder configuration_id hat Vorrang. Auch bei /compatibility, /fitments und /workshop-profile. Andere Schreibweise: HTTP 400 invalid_vsn. |
configuration_id | String | nein | Schlüssel aus /vehicle-configurations, Format cfg_ + 64 Hexadezimalzeichen. |
variant_key und configuration_id sind undurchsichtige Schlüssel. Die Werte unverändert aus der API übernehmen und weder zerlegen noch selbst bilden.
Wege zur Fahrzeugadresse
A) Modell, Generation, Motorisierung – für vier Auswahlstufen Marke → Modell → Generation/Ausführung → Motorisierung:
GET /brands
GET /models?brand=BMW
GET /generations?brand=BMW&model=3er-Reihe&include=executions
GET /engines?brand=BMW&model=3er-Reihe&generation=3er-Reihe%20G20%2FG21%2FG80&execution_key=…B) Baureihe – Marke → Baureihe → HSN/TSN:
GET /brands?onlyWithFitments=1
GET /series?brand=VW&onlyWithFitments=1
GET /variants?brand=VW&series=Touareg%20(CR)%20(07%2F18%20-%2005%2F23)
GET /compatibility?hsn=0603&tsn=COBC) Direkte Eingabe – HSN und TSN aus der Zulassungsbescheinigung.
Wege A und B enden in selection_options[] mit hsn, tsn und variant_key (null, wenn kein einzelner Schlüssel zugeordnet ist). Diese drei Werte als Fahrzeugadresse weitergeben. /engines nennt zusätzlich selection_required: true bedeutet, dass die Motorgruppe mehrere Varianten umfasst und die Variante über variants[] von /vehicle oder /compatibility bestätigt werden sollte. pairs[] und execution_key dienen nur der Navigation.
Variante bestätigen
/vehicle, /compatibility und /fitments liefern variants[]. Bei mehr als einer Variante ist model_selection_available=true. Je Eintrag eine Auswahloption anzeigen: headline als Titel, engine_line und years als Zusatz. variant_selection.selection_required=true zeigt an, dass sich die Varianten in technisch relevanten Angaben unterscheiden (Karosserie, Antrieb, Leistung, Hubraum, Kraftstoff, Radgeometrie oder Handelsname). Eine Auswahl ist nie Pflicht: Ohne Auswahl bleiben alle Ergebnisse gültig, die für alle Varianten gelten.
Ohne Auswahl bewertet die API Modellbedingungen eines Gutachtens (z. B. „nur für Modell X“) anhand der Handelsnamen aller Varianten des Fahrzeugs. Trifft die Bedingung auf alle Varianten zu, ist sie entschieden (bei „nur für Modell X“ erfüllt, bei „nicht für Modell X“ ausgeschlossen). Trifft sie nur auf einen Teil der Varianten zu, ist die Reifenzeile ohne Auswahl offen, nie „passt“: Status unknown mit verification_status=requires_configuration_evidence und der Begründung „Gilt je nach Variante dieses Fahrzeugs unterschiedlich – Variante wählen“ in condition_evaluation.reason. configuration_selection.recommended=true empfiehlt die Auswahl; ist der Weg ohne Auswahl nicht positiv, nennt configuration_selection.fits_variants[] die Varianten, für die er passt. „Offen – Variante wählen“ ist kein eigener Status, sondern unknown mit dieser Begründung. Mit variant_key wird die Bedingung für die gewählte Variante entschieden.
Genehmigungskonfiguration
/vehicle-configurations listet die Genehmigungskonfigurationen eines Fahrzeugs; jeder Eintrag nennt seine Variante in variant_key (null, wenn die Konfiguration keiner einzelnen Variante zugeordnet ist). Mit configuration_id bewerten /fitments und /compatibility genau diese Konfiguration, auch wenn sie keiner einzelnen Variante zugeordnet ist. /vehicle und /workshop-profile liefern mit configuration_id die Daten dieser Konfiguration. Ausstattung, die nur am einzelnen Fahrzeug prüfbar ist (z. B. Bremsscheibendurchmesser), bleibt auch mit Konfiguration ein Hinweis.
Auswahlstatus variant_selection
/vehicle, /compatibility und /fitments beschreiben die angewendete Auswahl in variant_selection und selected_variant.
status | Bedeutung | selected_variant |
|---|---|---|
not_requested | Keine Auswahl gesendet. Die Antwort gilt für alle Varianten. | null |
selected | Variante angewendet: aus variant_key, aus einem ersetzten Schlüssel mit genau einem Nachfolger oder aus einer configuration_id mit eindeutig zugeordneter Variante. | die Variante |
configuration_without_variant | configuration_id angewendet; die Konfiguration ist keiner einzelnen Variante zugeordnet. | null |
superseded | Früher ausgegebener Schlüssel mit mehreren oder keinem Nachfolger. Mehrere Nachfolger: Auswertung für genau diese Nachfolger. Kein Nachfolger: Auswertung ohne Auswahl. | null |
not_found | Nur /vehicle: Schlüssel ist diesem Fahrzeug unbekannt. Die Fahrzeugdaten werden ohne Auswahl geliefert. | null |
| Feld | Typ | Beschreibung |
|---|---|---|
requested_key | String|null | Angewendeter Schlüssel. Bei selected der aktuelle variant_key, bei superseded und not_found der gesendete Schlüssel (kleingeschrieben). |
superseded_key | String | Nur bei ersetztem Schlüssel mit genau einem Nachfolger: der gesendete frühere Schlüssel. requested_key enthält dann den Nachfolger. |
candidate_keys | String[] | Nur bei superseded: aktuelle Nachfolger des gesendeten Schlüssels; leer, wenn es keinen gibt. |
applied_keys | String[] | Nur /compatibility und /fitments bei mehreren Nachfolgern: Varianten, für die die Passung ausgewertet wurde. |
evaluation_scope | String | configuration, wenn eine configuration_id angewendet wurde; candidate_variants, wenn für die Nachfolger eines ersetzten Schlüssels ausgewertet wurde. |
configuration_id, configuration_applied | String, Boolean | Bei angewendeter Konfiguration: ihre ID und true. |
selection_required | Boolean | true, wenn sich die Varianten technisch unterscheiden und noch keine Variante angewendet ist. |
Während einer Datenaktualisierung können Fahrzeug- und Passungsdaten kurzzeitig aus unterschiedlichen Datenständen stammen. /compatibility und /fitments werten eine Auswahl dann wie eine Anfrage ohne Auswahl aus und nennen selection_unavailable_release_mismatch in meta.warnings. Die gespeicherte Auswahl bleibt gültig; dieselbe Anfrage später wiederholen.
curl -H "X-API-Key: carapi_live_xxxx" -H "X-API-Secret: IHR_SECRET" \
"https://api4cars.com/wp-json/carapi/v1/compatibility?hsn=0603&tsn=COB&variant_key=beispiel-variante-1"
{
"model_selection_available": true,
"selected_variant": { "variant_key": "beispiel-variante-1", "headline": "Touareg 3.0 V6 TDI", "engine_line": "170 kW · Diesel · Allrad", "years": "2018 - 2023" },
"variant_selection": { "status": "selected", "requested_key": "beispiel-variante-1", "selection_required": false },
"allowed_wheels": [ … ]
}"variant_selection": {
"status": "superseded",
"requested_key": "fruehere-variante",
"selection_required": true,
"candidate_keys": ["beispiel-variante-1", "beispiel-variante-2"],
"applied_keys": ["beispiel-variante-1", "beispiel-variante-2"],
"evaluation_scope": "candidate_variants"
}Schlüssel speichern
Die gewählte Fahrzeugadresse (hsn, tsn und variant_key oder configuration_id) vollständig in Garage, Warenkorb, Links und Cache speichern und bei Folgeanfragen unverändert mitsenden. Ein ausgegebener variant_key bezeichnet dauerhaft dieselbe Variante. Wird eine Variante neu gegliedert, bleibt der frühere Schlüssel gültig: mit einem Nachfolger wählt er diesen, mit mehreren grenzt er auf die Nachfolger ein, ohne Nachfolger liefert er die Auswertung ohne Auswahl. Nach superseded_key den gespeicherten Schlüssel durch requested_key ersetzen; nach status=superseded die Varianten aus candidate_keys zur Auswahl anbieten.
Reaktion auf Antworten
| Antwort | Reaktion |
|---|---|
HTTP 400 variant_not_for_vehicle oder HTTP 200 mit variant_selection.status=not_found | Nur die abgelehnte Auswahl entfernen, dasselbe Fahrzeug einmal ohne Auswahl laden und die aktuellen variants[] anbieten. Keine Variante automatisch wählen. |
HTTP 400 configuration_not_for_vehicle | Die configuration_id entfernen und die Konfiguration über /vehicle-configurations neu wählen. |
HTTP 400 conflicting_vehicle_selections | Nur einen der beiden Parameter senden. |
HTTP 200 mit status=superseded | Ergebnis anzeigen; Auswahl aus candidate_keys anbieten. |
| HTTP 409, HTTP 5xx, Zeitüberschreitung | Auswahl behalten und später erneut anfragen. |
Wirkung je Endpunkt
| Endpunkt | variant_key | configuration_id |
|---|---|---|
/compatibility, /fitments | Passung für diese Variante; Anzeige, Serienbereifung und Bauzeit der Variante. Unbekannter Schlüssel: HTTP 400. | Passung für genau diese Konfiguration. Beide Parameter zusammen: HTTP 400 conflicting_vehicle_selections. |
/vehicle | Anzeige, Bauzeit, Serienbereifung, Radgeometrie (wheels.pcd, wheels.bore) und zuordenbare Datenblätter der Variante. Unbekannter Schlüssel: HTTP 200 mit status=not_found. | Ergänzt das Objekt configuration mit den Daten der Konfiguration. |
/vehicle-configurations | – | Liefert die wählbaren Konfigurationen. |
/workshop-profile Alpha | Grenzt auf die passenden technischen Datensätze ein; nimmt auch den Suchschlüssel aus /vehicle-search an. | Daten dieser Konfiguration. Zusammen mit variant_key: HTTP 409 display_configuration_link_unverified. |
/vehicle-compare Alpha | Über variant_keys je HSN/TSN-Paar. | – |
/configurator/* Alpha | Wählt die Bildgruppe, wenn Karosserie und Bauzeitraum der Variante genau eine Bildgruppe treffen. | – |
Weitere Schlüssel
| Schlüssel | Herkunft | Verwendung |
|---|---|---|
execution_key | /generations?include=executions | Filter für /engines. Keine Fahrzeugadresse. |
vehicle_image_id | /configurator/availability, vehicle_image | Bildgruppe im Konfigurator. Keine Fahrzeugadresse. |
Suchschlüssel variant_key | /vehicle-search | Technischer Datensatz der Suche; für /workshop-profile und /vehicle-compare. Für /compatibility und /fitments den vehicle_variant_key desselben Treffers verwenden. |
wheel_id | /compatibility?include=wheel_overview | Eine physische Felgenvariante für /fitments?wheel_id=…. |
Liefert für ein Fahrzeug die freigegebenen Felgen mit Reifengrößen, Passungsstatus, Auflagen und Gutachten-Links, dazu Fahrzeugkontext, Varianten und Serienbereifung. Empfohlener Endpunkt für Shop-Integrationen.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
hsn | String | ja | Herstellerschlüsselnummer |
tsn | String | ja | Typschlüsselnummer |
variant_key | String | nein | Variante (siehe Fahrzeugauswahl). Nicht zusammen mit configuration_id. |
configuration_id | String | nein | Genehmigungskonfiguration aus /vehicle-configurations. Nicht zusammen mit variant_key. |
wheel_codes | String/Liste | nein | Felgenmodelle, kommagetrennt oder wiederholt, höchstens 50, z. B. FF01,FF02. Begrenzt allowed_wheels, wheel_groups und rules. |
brand | String | nein | Felgenhersteller. Mit wheel_codes gilt die Schnittmenge; ein Hersteller ohne zugeordnete Felgenmodelle ergibt eine leere Auswahl. |
include | String | nein | Kommagetrennte Antwortbereiche: vehicle, allowed_wheels, wheel_overview, wheel_groups, rules, staggered, status_detail, wheel_sets oder all (ohne wheel_sets). Standard: vehicle,allowed_wheels. |
compact | 0|1 | nein | Kurzform für das Profil: 1 = kompakt (Standard), 0 = vollständig. include hat Vorrang. |
Antwortprofile
Das Standardprofil kompakt enthält Fahrzeugkontext (vehicle, display_vehicle, variants, model_selection_available, selected_variant, variant_selection, tpms, oem_tires) und allowed_wheels mit den Auswahlfeldern selection_tires, selection_tire_sizes und best_fitment_status. Das Profil vollständig (include=all oder compact=0) liefert alle Antwortbereiche einschließlich wheel_groups, rules, staggered und der Statusdetails. meta.response_profile (slim, custom, all), meta.included, meta.omitted und meta.omitted_fields beschreiben die gelieferte Antwort.
Felgenübersicht: include=vehicle,wheel_overview liefert je physischer Felgenvariante Geometrie, wheel_id und den zusammengefassten Status ohne Reifen- und Auflagentexte. Die Details der gewählten Felge anschließend mit /fitments?hsn=…&tsn=…&wheel_id=… und derselben Fahrzeugauswahl abrufen. Für Reifenauswahl, Auflagen und Achspaare gelten die Details.
Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
vehicle | Object | Fahrzeugdaten wie bei /vehicle |
vehicle_known, fitment_known | Boolean | Fahrzeug bekannt; Felgenfreigaben vorhanden |
match_scope | String | pair_exact (Freigaben für genau dieses HSN/TSN-Paar), pcd_bore_fallback (Zuordnung über Lochkreis und Mittenloch) oder no_fitment |
display_vehicle | Object | Anzeigeangaben: Marke, Modell, Ausstattungslinie, Baureihe, Bauzeit, Antrieb |
display_variants | Array | Anzeigevarianten im Kompatibilitätsformat. Für neue Auswahloberflächen nicht verwenden; stattdessen variants. |
variants | Array | Varianten des Fahrzeugs (siehe /vehicle) |
model_selection_available | Boolean | true bei mehr als einer Variante |
selected_variant, variant_selection | Object | Angewendete Auswahl (siehe Auswahlstatus) |
tpms | Object | Reifendruckkontrolle: type (active, passive, unknown), requires_sensor, label |
oem_tires | Object | Serienbereifung: front, rear, is_staggered; optional references und achsweise gekoppelte options. Enthalten sind nur gesicherte Seriengrößen: Größen aus der CoC-Reifenliste des Fahrzeugs oder Größen, die mindestens zwei unabhängige Quellen bestätigen. Liegt keine gesicherte Größe vor, bleiben front und rear leer. is_staggered ist nur true, wenn Mischbereifung für dieses Fahrzeug Serienstandard ist; optionale Mischbereifungs-Pakete erscheinen nicht als Serienbereifung. |
factory_wheels | Object|null | Serienfelgen als references; options hält Reifen und Felgen einer Serienkonfiguration zusammen |
vehicle_bore_mm, wheel_specs | Number|null, Object | Mittenlochdurchmesser (Nabenbohrung) des Fahrzeugs in mm; Lochkreis und Mittenloch des Fahrzeugs |
allowed_wheels[] | Array | Felgenkandidaten je Felgencode, Größe, Lochkreis, Mittenloch und ET mit best_fitment_status, gutachten_url, selection_mode, selection_tire_sizes, selection_tires, is_recommended_et, et_rank sowie Zentrierung (centering_status, bore_compatible). Die Liste kann positive (eintragungsfrei, mit_eintragung), offene (unknown) und negative (nicht_passend) Bewertungen enthalten; sie ist keine Positivliste. |
allowed_wheels[].selection_tire_sizes | String[] | Wählbare Reifengrößen für diese Felge und ET |
allowed_wheels[].selection_tires[] | Array | Je Reifengröße und Achse: size, axle (both, front, rear), fitment_status, codes, requires_registration, requires_bodywork, condition_requirements, installation_requirements; mit status_detail zusätzlich status_options und status_conflict |
allowed_wheels[].selection_tires[].source_gutachten, gutachten_url, approval_path_id, document_approval | String|Object (optional) | Nur wenn mehrere Freigabewege derselben Felge (Größe, Lochkreis, Mittenloch, ET) gleichrangig sind (gleicher bester Status, gleich viele positive Reifen): Der Eintrag zeigt dann die Reifen aller dieser Wege, jede Reifengröße und Achse aus genau einem Weg (bester Status, bei Gleichheit weniger Auflagen), und jeder Reifen nennt hier sein eigenes Gutachten, dessen Link, seinen Freigabeweg und – falls belegt – die Zulassung. Status, Codes und Hinweise des Reifens stammen aus diesem Weg. Die Felder des Eintrags (source_gutachten, approval_path_id …) nennen den Weg mit den meisten eintragungsfreien Reifen. Ohne Gleichstand fehlen die Felder; dann gelten die Angaben des Eintrags. Auch in wheel_groups[].ets[].selection_tires[] und tires[]. |
allowed_wheels[].wheel_axle_scope | String | Achsumfang des Felgenkandidaten aus den zugeordneten Reifenoptionen. Bei der Auswahl berücksichtigen; der Reifenmodus allein bestimmt ihn nicht. Nennt ein Gutachten unterschiedliche Felgen für Vorder- und Hinterachse, erscheint derselbe wheel_code mit zwei Einträgen (front und rear), je mit eigener Breite, Einpresstiefe, approval_path_id und eigenen Reifen (in wheel_overview zusätzlich je eigene wheel_id; /fitments trennt genauso); ein solcher Eintrag ist keine Rundum-Felge. Der Wert folgt aus den Reifen: Auch eine Rundum-Felge trägt rear, wenn das Gutachten für dieses Fahrzeug nur Hinterachsreifen nennt. Achsgebundene Felgen eines Kombi-Gutachtens erkennt man daran, dass derselbe wheel_code aus demselben Gutachten mit abweichender Breite oder Einpresstiefe für die andere Achse vorkommt. |
allowed_wheels[].wheel_component_axle | String|null | Achse der Felge laut Gutachten: front bzw. rear bei Felgen, die ein Kombi-Gutachten nur für eine Achse freigibt, both bei Felgen ohne Achsbindung. Anders als wheel_axle_scope hängt der Wert nicht von den Reifen ab. Vorder- und Hinterachs-Felge desselben Kombi-Gutachtens haben denselben wheel_code und dieselbe source_gutachten. Auch in /fitments, wheel_groups[].ets[], rules[] und wheel_overview[]. null, solange der Datenstand die Angabe noch nicht trägt. |
wheel_sets[] | Array | Nur mit include=wheel_sets: belegte Mischsätze eines Kombi-Gutachtens für dieses Fahrzeug. Ein Satz entsteht nur, wenn das Gutachten das Reifenpaar ausdrücklich nennt (Reifenpaar-Tabelle) oder eine Breitenregel für Vorder- und Hinterachse festlegt; Felgen und Reifen werden nie frei kombiniert. Felder: id (stabil), kind (accessory), source_gutachten, gutachten_url, front/rear (wheel_code, width_inch, diameter_inch, et, pcd, bore, tire, status), status (eintragungsfrei nur, wenn beide Achsen eintragungsfrei sind) und pair_codes (Auflagen, die das Paar belegen). Der Status folgt aus den Achs-Einträgen derselben Antwort und damit aus derselben Fahrzeugauswahl. Die Achs-Einträge in allowed_wheels nennen ihre Sätze in wheel_set_ids. Liegt der Abschnitt im Datenstand noch nicht vor, ist die Liste leer und meta.warnings nennt wheel_sets_unavailable. |
allowed_wheels[].selection_mode | String | single, mixed_optional, mixed_required oder restricted_pairs (nur Achspaare aus staggered.allowed_pairs). single beschreibt die Reifenwahl und bedeutet nicht, dass die Felge auf beiden Achsen verwendet werden darf. Achsumfang der Felge und Achszuordnung jeder Reifenoption beachten; eingeschränkte Mischpaare nur aus staggered.allowed_pairs übernehmen. |
allowed_wheels[].centering_status | String | direct_nominal, centering_ring_required, wheel_bore_too_small oder unknown |
wheel_overview[] | Array | Nur mit include=wheel_overview: wheel_id, wheel_code, Größe, ET, Lochkreis, Mittenloch, best_fitment_status |
wheel_groups[] | Array | Felgen je Modell und Größe mit allen ET-Varianten in ets[] und recommended_et. Für Konfiguratoren wheel_groups[].ets[] verwenden. |
rules[] | Array | Alle Freigaben einschließlich Auflagencodes und Klartext |
status_summary | Object | Mit status_detail: Anzahl der Reifenoptionen je Status |
staggered | Object | Mischbereifung (siehe Mischbereifung) |
meta | Object | Zähler, Profilangaben und warnings |
Fehler
| HTTP | Code | Ursache |
|---|---|---|
| 400 | rest_invalid_param | Ungültiger Wert für variant_key, configuration_id, wheel_codes, include oder compact |
| 400 | variant_not_for_vehicle | variant_key gehört nicht zu diesem Fahrzeug |
| 400 | conflicting_vehicle_selections | variant_key und configuration_id gemeinsam gesendet |
| 400 | invalid_configuration_id, configuration_not_for_vehicle | Konfiguration ungültig oder gehört nicht zu diesem Fahrzeug |
| 404 | vehicle_not_found | HSN/TSN unbekannt |
| 409 | variant_facts_unavailable, configuration_evidence_required, fitment_evidence_required | Für die gewählte Auswahl oder das Fahrzeug liegen nicht genug Daten für eine Passungsaussage vor |
| 503 | fitment_data_invalid, fitment_data_unavailable | Passungsdaten vorübergehend nicht lesbar |
Beispiel
curl -H "X-API-Key: carapi_live_xxxx" -H "X-API-Secret: IHR_SECRET" \
"https://api4cars.com/wp-json/carapi/v1/compatibility?hsn=0603&tsn=COB&wheel_codes=FF01"{
"vehicle": { "hsn": "0603", "tsn": "COB", "brand": "Volkswagen", "model": "Touareg", "years": "2018 - 2023" },
"variants": [ { "variant_key": "beispiel-variante-1", "headline": "Touareg 3.0 V6 TDI", "engine_line": "170 kW · Diesel · Allrad", "years": "2018 - 2023", "geometry": { "pcd": "5x112", "bore": 66.6 } } ],
"model_selection_available": false,
"selected_variant": null,
"variant_selection": { "status": "not_requested", "requested_key": null, "selection_required": false },
"tpms": { "type": "active", "requires_sensor": true, "label": "direktes System" },
"oem_tires": { "front": "235/55R18V", "rear": null, "is_staggered": false },
"allowed_wheels": [
{
"wheel_code": "FF01",
"pcd": "5x112",
"bore": "66.6",
"et": "35",
"width_inch": 8.5,
"diameter_inch": 19,
"is_recommended_et": true,
"et_rank": 1,
"selection_mode": "single",
"selection_tire_sizes": ["235/55R19", "255/50R19"],
"best_fitment_status": "eintragungsfrei",
"gutachten_url": "https://cdn.api4cars.com/gutachten/FF01/example.pdf",
"selection_tires": [
{ "size": "235/55R19", "axle": "both", "fitment_status": "eintragungsfrei" },
{ "size": "255/50R19", "axle": "both", "fitment_status": "eintragungsfrei" }
]
}
],
"meta": { "response_profile": "slim", "included": ["vehicle", "allowed_wheels"] }
}Liefert die einzelnen Felgenfreigaben eines Fahrzeugs je Gutachten mit allen Genehmigungswegen, Reifen und Auflagen. Geeignet, wenn Gruppierung und Darstellung selbst umgesetzt werden oder die Details einer Felge aus der Felgenübersicht benötigt werden.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
hsn | String | ja | Herstellerschlüsselnummer |
tsn | String | ja | Typschlüsselnummer |
variant_key | String | nein | Variante. Nicht zusammen mit configuration_id. |
configuration_id | String | nein | Genehmigungskonfiguration. Nicht zusammen mit variant_key. |
wheel_code | String | nein | Felgenmodell, z. B. FF01; kommagetrennt bis zu 50 Codes |
wheel_id | String | nein | Physische Felgenvariante aus wheel_overview (wheel_ + 64 Hexadezimalzeichen). Alle Genehmigungswege dieser Felge sind enthalten; ohne Treffer ist die Liste leer. |
et | String | nein | Einpresstiefe |
pcd | String | nein | Lochkreis, z. B. 5x112 |
tire_size | String | nein | Reifengröße, z. B. 235/55R19 |
min_confidence | Integer | nein | Mindestwert für confidence (Standard 0). Zuordnungen tragen 1; 0 und 1 liefern dieselbe Menge. Kein Filter für den Passungsstatus. |
compact | 0|1 | nein | 1 fasst wiederholte Auflagentexte in dictionaries.obligations zusammen und ermöglicht Paginierung |
page | Integer | nein | Nur mit compact=1: Seite, ab 1 |
per_page | Integer | nein | Nur mit compact=1: Felgenserien je Seite, 1–100 (Standard 20) |
data_version | String | nein | Für Folgeseiten: meta.dataset_generation der ersten Seite |
limit und include gibt es bei /fitments nicht; sie werden mit HTTP 400 rest_unknown_param abgelehnt.
Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
hsn, tsn, count | String, Integer | Fahrzeug und Anzahl der Freigaben |
variants, selected_variant, variant_selection | Array, Object | Varianten und angewendete Auswahl |
fitments[].wheel_code, et, pcd, bore, width_inch, diameter_inch | String, Number | Felgengeometrie |
fitments[].best_fitment_status | String | Status dieses Genehmigungswegs (siehe Passungsstatus) |
fitments[].tires[] | Array | Reifen dieses Wegs mit size, axle, status, codes, condition_requirements, installation_requirements, fastener_codes, fastener_resolution und optional tire_spec |
fitments[].approved_tires | Array | Reifengrößen mit positivem Status |
fitments[].auflagen | Object | Auflagentext je Code, z. B. F24; mit compact=1 ersetzt durch obligation_refs |
fitments[].configuration_selection | Object | recommended: true, wenn Reifenzeilen dieser Felge von Variante oder Konfiguration abhängen und ohne Auswahl unknown bleiben; unresolved_configuration_dependent_tires zählt sie. Ist der Weg ohne Auswahl nicht positiv, für einzelne Varianten aber schon, folgen variant_dependent: true und fits_variants[] (variant_key, label). Schließt eine Variante eine Reifenzeile aus, die für das Fahrzeug ohne Auswahl passen würde, ist sie ohne Auswahl unknown („Gilt je nach Variante dieses Fahrzeugs unterschiedlich – Variante wählen“). |
fitments[].vehicle_bore_mm, wheel_bore_mm, centering_status, requires_centering_ring | Number, String, Boolean | Zentrierung von Felge und Nabe |
fitments[].gutachten_url, source_gutachten | String|null | Link zum Gutachten-PDF und sein Dateipfad |
meta.total_groups, meta.total_pages, meta.dataset_generation | Integer | Mit compact=1: Umfang der Paginierung und Datenstand |
tire_spec enthält die Reifenkennzeichnung der Gutachtenzeile: width_mm, aspect_ratio, rim_inch sowie, falls angegeben, load_index (String, auch Doppelangaben wie 100/98), speed_symbol und tire_description.
Fehler
| HTTP | Code | Ursache |
|---|---|---|
| 400 | rest_invalid_param | Ungültiger Parameterwert; page/per_page ohne compact=1 |
| 400 | rest_unknown_param | limit oder include gesendet |
| 400 | variant_not_for_vehicle, conflicting_vehicle_selections, invalid_configuration_id, configuration_not_for_vehicle | Siehe Fahrzeugauswahl |
| 404 | vehicle_not_found | HSN/TSN unbekannt |
| 409 | fitment_dataset_changed | Datenstand seit der ersten Seite geändert; Paginierung ab Seite 1 neu beginnen |
| 409 | variant_facts_unavailable, configuration_evidence_required, fitment_evidence_required | Nicht genug Daten für eine Passungsaussage zur gewählten Auswahl oder zum Fahrzeug |
| 503 | fitment_data_invalid, fitment_data_unavailable | Passungsdaten vorübergehend nicht lesbar |
Beispiel
curl -H "X-API-Key: carapi_live_xxxx" -H "X-API-Secret: IHR_SECRET" \
"https://api4cars.com/wp-json/carapi/v1/fitments?hsn=1313&tsn=ABK&wheel_code=AF18"{
"hsn": "1313",
"tsn": "ABK",
"count": 1,
"variant_selection": { "status": "not_requested", "requested_key": null, "selection_required": false },
"fitments": [
{
"wheel_code": "AF18",
"et": "21",
"pcd": "5x112",
"bore": "66.6",
"width_inch": 10,
"diameter_inch": 22,
"best_fitment_status": "eintragungsfrei",
"approved_tires": ["255/40R22"],
"tires": [ { "size": "255/40R22", "axle": "both", "status": "eintragungsfrei", "codes": ["F24", "S01"], "fastener_codes": ["S01"], "fastener_resolution": "exact" } ],
"auflagen": { "F24": "Radschrauben M14x1,5x38 verwenden. Anzugsdrehmoment 120 Nm." },
"configuration_selection": { "recommended": false, "unresolved_configuration_dependent_tires": 0 },
"gutachten_url": "https://cdn.api4cars.com/gutachten/AF18/example.pdf"
}
]
}Liefert den fahrzeugunabhängigen Gutachten-Katalog, gruppiert nach Felgencode. Ohne Filter liefert der Endpunkt den vollständigen Katalog.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
wheel_code / wheel_codes | String/Liste | nein | Felgencodes, kommagetrennt oder wiederholt, höchstens 50 |
brand | String | nein | Felgenmarke wie im Felgenkatalog (/wheels), Groß-/Kleinschreibung, Leer- und Bindestriche egal (FF Wheels = FF-Wheels), weitere Namen derselben Marke ebenso (MM-Concepts = MM-Wheels); eine Marke ohne Felgencodes ergibt eine leere Auswahl. Zusammen mit wheel_codes gilt die Schnittmenge. |
include | String | nein | fasteners (Standard), obligations (zusätzlich die Auflagenlegende je Dokument) oder all |
Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
models.{wheel_code}[] | Array | Je Gutachten: source_gutachten, gutachten_url, pcd, bore, bore_document, et, width_inch, diameter_inch, approval, fasteners, fastener_status. Baugleiche Felgen unter eigenem Code liefern dasselbe Gutachten unter ihrem eigenen Pfad (z. B. FF04/…). |
models.{wheel_code}[].bore_document | String|null | Mittenloch-Durchmesser in mm, wie ihn dieses Gutachten nennt (z. B. 66.7). bore nennt dagegen die gemeinsame Nabenbohrung für Passung und Gruppierung (z. B. 66.6 für 66,5/66,6/66,7) und ist in allen Antworten gleich geschrieben. Zwei Gutachten mit gleichem bore unterscheiden sich über bore_document bzw. source_gutachten. null, solange der Datenstand die Angabe noch nicht trägt. |
model_statuses.{wheel_code} | Object | model_status, is_legacy, is_discontinued |
model_brands.{wheel_code} | String|null | Felgenmarke des Codes laut Felgenkatalog; baugleiche Felgen tragen ihre eigene Marke. null, wenn keine Marke hinterlegt ist. |
fasteners | Object | Befestigungsalternativen des Dokuments je S-Code; type ist serienschraube, schraube, serienmutter oder mutter |
fastener_status | String | parsed_complete, parsed_partial, parse_error oder not_documented; bei Teilangaben nennen row_status und missing_fields die fehlenden Werte |
total_pdfs | Integer | Anzahl der Dokumente |
Für ein konkretes Fahrzeug gelten ausschließlich die S-Codes der passenden Reifenzeile aus /fitments bzw. /compatibility. Bleiben mehrere reifengrößenabhängige Alternativen, ist fastener_resolution=ambiguous, bis die Reifengröße gewählt ist. Bei gewöhnlichen Muttern kennzeichnet shaft_length_status=not_applicable einen im Dokument ausdrücklich gesetzten Strich in der Schaftlängenspalte.
Fehler
HTTP 400 rest_invalid_param bei ungültigen Felgencodes oder include-Werten.
Beispiel
curl -H "X-API-Key: carapi_live_xxxx" -H "X-API-Secret: IHR_SECRET" \
"https://api4cars.com/wp-json/carapi/v1/gutachten?wheel_codes=DM08"
{
"models": {
"DM08": [ { "source_gutachten": "DM08/DM08 8,5x19 5x112 ET35.pdf", "gutachten_url": "https://cdn.api4cars.com/gutachten/DM08/example.pdf", "pcd": "5x112", "bore": "66,6", "bore_document": "66.7", "et": "35", "width_inch": 8.5, "diameter_inch": 19, "fastener_status": "parsed_complete" } ]
},
"model_statuses": { "DM08": { "model_status": "active", "is_legacy": false, "is_discontinued": false } },
"model_brands": { "DM08": "Damina" },
"total_pdfs": 1
}Passungsstatus
| Wert | Bedeutung |
|---|---|
eintragungsfrei | Die Freigabe deckt die Kombination ohne Eintragung ab. Mitgelieferte Auflagen und Hinweise gelten. |
mit_eintragung | Eintragung durch eine Prüforganisation (z. B. TÜV) oder Arbeiten am Fahrzeug erforderlich. |
nicht_passend | Die Kombination ist für dieses Fahrzeug ausgeschlossen: Ein Fahrzeugmerkmal, die Geometrie oder die Gutachtenzeile schließt sie aus. Nicht auswählbar anzeigen. Eine Felge ohne Freigabe erscheint dagegen gar nicht. |
unknown | Offen: Die Voraussetzungen lassen sich mit den vorhandenen Fahrzeugdaten nicht entscheiden; manuelle Prüfung erforderlich. condition_requirements[].missing_fields nennt die fehlenden Angaben, verification_status den Grund (siehe unten). unknown nie als passend anzeigen. |
verification_status bei unknown (Grund des offenen Status; die Begründung im Klartext steht in condition_evaluation.reason):
| Wert | Bedeutung |
|---|---|
requires_configuration_evidence | Das Ergebnis hängt von Variante oder Konfiguration ab, z. B. „Gilt je nach Variante dieses Fahrzeugs unterschiedlich – Variante wählen“, oder eine Fahrzeugbedingung der Gutachtenzeile ist nicht belegt. Mit variant_key bzw. configuration_id erneut abfragen; configuration_selection.recommended=true zeigt das an. |
requires_configuration_power_evidence | Der Leistungsbereich der Gutachtenzeile ist mit den vorhandenen Fahrzeugwerten nicht eindeutig belegt; eine Variantenauswahl kann ihn entscheiden. |
requires_configuration_document_evidence | Der Genehmigungsbezug der gewählten Konfiguration ist nicht belegt. |
requires_geometry_evidence | Lochkreis oder Nabenbohrung des Fahrzeugs ist für diese Felge nicht belegt. |
requires_manual_review | Sonstige offene Prüfung oder Reifenzeilen mit unterschiedlichen Gründen. |
„Offen – Variante wählen“ ist kein eigener Status, sondern unknown mit Begründung. Shops zeigen unknown nie als passend an, sondern als „offen“ mit dem Grund und, wenn configuration_selection.recommended=true, mit der Variantenauswahl.
best_fitment_status in allowed_wheels, wheel_groups[].ets[] und wheel_overview fasst alle zutreffenden Gutachten derselben Felge (Größe, Lochkreis, Mittenloch, ET) zusammen; ebenso selection_tires[].fitment_status je Reifengröße und Achse. Es gilt der strengste Wert: nicht_passend vor mit_eintragung vor unknown vor eintragungsfrei. Innerhalb eines Gutachtens sind mehrere Zeilen für dieselbe Reifengröße alternative Genehmigungswege; dort zählt der beste belegte Weg. status_options nennt alle vorkommenden Werte, status_conflict=true zeigt abweichende Gutachten an. Positive Statuswerte gelten unter den mitgelieferten Auflagen; verification_status kennzeichnet sie mit equipment_conditions_apply bzw. installation_conditions_apply.
Auflagen und Hinweise
Jede Reifenoption trägt die Auflagen ihres Gutachtens. Die Auflagen bei der Auswahl anzeigen und vor der Montage erfüllen.
| Feld | Bedeutung |
|---|---|
codes | Auflagencodes des Gutachtens, z. B. F24; Klartext in auflagen bzw. rules |
installation_requirements[].kind | registration: Abnahme erforderlich. paperwork: Berichtigung der Fahrzeugpapiere mit den genannten Ausnahmen; allein keine Abnahmepflicht. installation: Montage- oder Nutzungshinweis. modification: Arbeiten am Fahrzeug erforderlich. speedometer: Tachonachweis; liegt der Abrollumfang außerhalb der Toleranz aller Serienreifengrößen, ist der Status mit_eintragung, sonst bleibt es ein Hinweis (condition_evaluation.requirement_evidence nennt das Ergebnis). vehicle_condition: Achslastgrenzen einschließlich Hinweis zum Anhängerbetrieb. |
condition_requirements[] | Originaltext und Zustand jeder Fahrzeugbedingung. kind=equipment_condition mit state=not_verified bedeutet „passt, sofern das Fahrzeug diese Ausstattung hat“ (z. B. Bremsscheibendurchmesser). missing_fields nennt fehlende Fahrzeugangaben wie is_plugin_hybrid, is_five_door_hatchback oder national_axle_loads; das sind Antwortfelder, keine Eingabeparameter. |
row_hints[] | Hinweise der Gutachtenzeile, die am Fahrzeug zu prüfen sind (z. B. Modell oder Ausführung, Genehmigungsnachtrag), mit type, condition_type, values und text. Ein Hinweis macht einen offenen Status nie zu „passt“. Einschränkungen im Fahrzeugfeld (type=vehicle_restriction, op): ausschließende Form „NICHT für Fahrzeuge mit X“ (op=exclude, z. B. Radhaus-Verbreiterung, Hinterachslenkung, Ausstattungspaket) ohne Beleg des Merkmals – der Status bleibt, der Hinweis ist am Fahrzeug zu prüfen; einschließende Form „nur für Fahrzeuge MIT X“ (op=require) ohne Beleg – Status unknown mit Hinweis. |
condition_evaluation | blocking_codes: belegte Ausschlüsse. unresolved_codes: offene Prüfungen. pending_codes: Ausstattungsbedingungen, die bei positivem Status am Fahrzeug zu prüfen sind. violated_conditions[] (nur bei nicht_passend): Fahrzeugbedingung der Gutachtenzeile, die dieses Fahrzeug ausschließt, mit type (z. B. body, drivetrain, powertrain, model, series) und document_values (Werte der Gutachtenzeile, z. B. Coupe; die Werte des Fahrzeugs nennt /vehicle). Bei gleicher Felge und gleichem Reifen gilt der beste Status über alle Einträge. |
Ausstattung, die nur am einzelnen Fahrzeug prüfbar ist, ergibt „passt“ mit Hinweis. Winterräder: Lässt die Gutachtenzeile die Reifengröße nur als M+S-Bereifung zu und sind die belegten Serienräder größer als das Sonderrad, ergibt das „passt“ mit Hinweis in condition_requirements[].evidence.note (kind=equipment_condition): „Nur als M+S-Winterbereifung: die belegten Serienräder sind größer als … – zulässig, wenn der Fahrzeughersteller diese Winterradgröße freigibt (Betriebsanleitung/COC prüfen)“. Achslastgrenzen prüft die API je Achse über alle betroffenen Konfigurationen. Plug-in- und Mildhybrid-Bedingungen wertet die API anhand der spezifischen Antriebsangaben aus. Eine Bestätigung durch den Kunden wird nicht abgefragt.
Mischbereifung (staggered)
staggered ist kein eigener REST-Endpunkt, sondern ein Antwortbereich von GET /compatibility, abrufbar mit include=staggered oder include=all. Bei Mischbereifung Vorder- und Hinterachse nicht aus flachen Reifenlisten kombinieren: Ist staggered.allowed_pairs gefüllt, sind nur diese Paare zulässig. source_code nennt den Gutachten-Code, z. B. V19.
| Feld | Typ | Beschreibung |
|---|---|---|
staggered_oe | Boolean | Serienbereifung mit unterschiedlichen Größen vorne und hinten |
oe_front_tire, oe_rear_tire | String|null | Serienreifen vorne und hinten |
front_allowed_tires, rear_allowed_tires, both_axle_tires | String[] | Freigegebene Größen je Achse bzw. für beide Achsen |
allowed_pairs[] | Array | Zulässige Achspaare {front, rear, source_code}, z. B. aus V18–V22 |
gutachten_coverage | String | not_applicable, restricted_pairs, full, partial, unknown oder none; gutachten_coverage_detail beschreibt den Wert |
{
"staggered": {
"gutachten_coverage": "restricted_pairs",
"allowed_pairs": [
{ "front": "225/35R19", "rear": "255/30R19", "source_code": "V19" },
{ "front": "235/35R19", "rear": "255/30R19", "source_code": "V19" }
]
}
}Einen Achsreifen-Konfigurator gegen allowed_pairs prüfen. Für die normale Reifenauswahl selection_tires bzw. selection_tire_sizes der gewählten Felge verwenden.
Liefert die Fahrzeugdaten zu einem HSN/TSN-Paar: Anzeige, Varianten, Radanschluss, Serienbereifung, Reifendruckkontrolle und technische Datenblätter.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
hsn | String | ja | Herstellerschlüsselnummer |
tsn | String | ja | Typschlüsselnummer |
variant_key | String | nein | Variante: Anzeige, Bauzeit, Serienbereifung, Radgeometrie und zuordenbare Datenblätter dieser Variante |
configuration_id | String | nein | Ergänzt das Objekt configuration mit den Daten dieser Konfiguration |
include | String | nein | Alpha optional market,safety,environment: kompakte Markt-, Rückruf- und Umweltangaben. safety liefert Modell-Rückrufe mit hsn_tsn_exact=false und nennt fehlende Treffer über reason (z. B. no_validated_model_recall_match). environment liefert nur exakt auf HSN/TSN bezogene Werte; Aggregate werden nicht auf Einzeltypen verteilt und mit scope=no_safe_hsn_tsn_projection und reason (no_exact_hsn_tsn_environment_fact oder aggregate_environment_fact_not_projectable_to_hsn_tsn) erklärt. |
Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
hsn, tsn, brand, model, years | String | Fahrzeug und Bauzeit; mit Variante deren Bauzeit |
kba_identity_only | Boolean | true, wenn die Fahrzeugidentität bestätigt ist, technische Daten, Radgeometrie und Freigaben aber noch fehlen |
display_vehicle | Object|null | Anzeigeangaben: Ausstattungslinie, Baureihe, Bauzeit, Antrieb, Getriebe |
display_variants | Array | Anzeigevarianten im Kompatibilitätsformat. Für neue Auswahloberflächen nicht verwenden; stattdessen variants. |
variants[] | Array | Varianten mit variant_key, headline, engine_line, years, series_code, series_start_year, optional production_start_year, kw, ps, displacement_ccm, fuel, optional hybrid_type, drivetrain, body_type, oe_tires, optional staggered_standard, trade_identity und technical_data. oe_tires enthält nur gesicherte Seriengrößen (CoC-Reifenliste der Variante oder Bestätigung durch mindestens zwei unabhängige Quellen) und kann leer sein. staggered_standard (Boolean) ist true, wenn alle zugelassenen Serienkombinationen der Variante unterschiedliche Größen vorne und hinten haben; dann enthält oe_tires nur Mischbereifungs-Paare, sonst nur Paare mit gleicher Größe auf beiden Achsen. Optional executions[]: Angaben je Ausführung der Variante (eine Variante kann mehrere Ausführungen zusammenfassen), je Eintrag body_code (sedan, hatchback, fastback, estate, coupe, convertible, suv, van, pickup, panel_van) mit deutschem Namen body_label, fuel_code (petrol, diesel, gas, petrol_gas, ethanol, petrol_ethanol, hydrogen, electric), hybrid_type (mild_hybrid, full_hybrid, plugin_hybrid), displacement_ccm, power_kw, length_mm und height_mm; nicht belegte Angaben sind null, gleiche Einträge erscheinen einmal. Die Variantenfelder (body_type, fuel, displacement_ccm …) beschreiben weiter die Variante insgesamt. hybrid_type der Variante nennt mild_hybrid, full_hybrid oder plugin_hybrid, wenn alle Ausführungen dieselbe Hybridart haben. Optional same_engine_as[]: variant_key anderer Varianten mit demselben Motor (Mild-Hybrid- und Verbrenner-Eintrag desselben Motors). |
variants[].geometry | Object | Radgeometrie der Variante: pcd (Lochkreis) und bore (Mittenloch in mm), jeweils null, wenn für die Variante nicht belegt. Varianten mit unterschiedlicher Radgeometrie werden immer getrennt geführt. |
model_selection_available | Boolean | true bei mehr als einer Variante |
selected_variant, variant_selection | Object | Angewendete Auswahl (siehe Auswahlstatus) |
wheels | Object | Radanschluss: pcd, bore, fastening, thread, torque |
wheels.pcd_status, wheels.bore_status | String | verified, unverified oder missing. Sicherheitsrelevante Entscheidungen nur auf verified stützen. |
wheels.mounting | Object | Serienrad-Befestigung: seat (ball, cone, flat), Radius oder Winkel, shaft_length_mm; nicht belegte Werte null |
vehicle_facts | Object|null | Abgeglichene Fahrzeugwerte über alle Quellen: length_mm, width_mm, height_mm, wheelbase_mm, curb_weight_kg, gross_weight_kg, axle_load_front_kg, axle_load_rear_kg (zulässige Werte), drivetrain (FWD, RWD, AWD, 2WD). Je Feld status (confirmed, unresolved = Quellen uneins, unknown) und values (Liste, mehrere Werte bei verschiedenen Ausführungen; sonst null). Ergänzt vehicle_data, ersetzt es nicht. |
tpms, oem_tires | Object | Reifendruckkontrolle und Serienbereifung |
vehicle_data | Array|null | Technische Datenblätter, immer als Liste. Messwerte tragen ihre Bezugsgröße im Namen, z. B. CO2-Ausstoß (NEFZ); NEFZ, WLTP und WLTP bei leerer Plug-in-Batterie sind getrennte Werte. 0 g/km ist ein Messwert. |
configuration | Object | Nur mit configuration_id: Konfiguration wie in /vehicle-configurations |
vehicle_image | Object | Alpha Bildverfügbarkeit und neutrales Vorschaubild (320 px), sofern ein freigegebenes Bildset existiert; bei mehreren Bildgruppen ambiguous=true mit matches |
series_start_year bezeichnet den Beginn der Baureihe, production_start_year den Beginn der konkreten Motorisierung. hybrid_type=mild_hybrid ergänzt die Antriebsangabe und kann zusammen mit fuel=diesel auftreten.
Fehler
| HTTP | Code | Ursache |
|---|---|---|
| 400 | rest_invalid_param | Ungültiges Format von variant_key, configuration_id oder include |
| 400 | invalid_configuration_id, configuration_not_for_vehicle | Konfiguration ungültig oder gehört nicht zu diesem Fahrzeug |
| 400 | rest_unknown_param | Unbekannter Parameter zusammen mit include=market|safety|environment |
| 404 | – | HSN/TSN unbekannt; Antwort {"error": "Vehicle not found", "hsn", "tsn"} (mit configuration_id: vehicle_not_found) |
Ein unbekannter variant_key ist kein Fehler: Die Antwort ist HTTP 200 mit variant_selection.status=not_found und selected_variant=null.
Beispiel
curl -H "X-API-Key: carapi_live_xxxx" -H "X-API-Secret: IHR_SECRET" \
"https://api4cars.com/wp-json/carapi/v1/vehicle?hsn=0603&tsn=COB"{
"hsn": "0603",
"tsn": "COB",
"brand": "Volkswagen",
"model": "Touareg",
"years": "2018 - 2023",
"kba_identity_only": false,
"display_vehicle": { "brand": "Volkswagen", "model": "Touareg", "trim": "3.0 V6 TDI", "series_code": "CR", "years": "2018 - 2023", "drivetrain": "Allradantrieb" },
"variants": [
{ "variant_key": "beispiel-variante-1", "headline": "Touareg 3.0 V6 TDI", "engine_line": "170 kW · Diesel · Allrad", "years": "2018 - 2023", "kw": 170, "fuel": "Diesel", "geometry": { "pcd": "5x112", "bore": 66.6 } }
],
"model_selection_available": false,
"selected_variant": null,
"variant_selection": { "status": "not_requested", "requested_key": null, "selection_required": false },
"wheels": { "pcd": "5x112", "pcd_status": "verified", "bore": "66.6", "bore_status": "verified", "fastening": "Schraube", "thread": "M14x1,5", "torque": "180 Nm" },
"tpms": { "type": "active", "requires_sensor": true, "label": "direktes System" },
"oem_tires": { "front": "235/55R18V", "rear": null, "is_staggered": false },
"vehicle_data": [ { "Leistung": "170 kW / 231 PS", "Kraftstoff": "Diesel" } ]
}Listet die Genehmigungskonfigurationen eines Fahrzeugs. Eine configuration_id daraus grenzt /compatibility, /fitments, /vehicle und /workshop-profile auf genau diese Konfiguration ein.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
hsn | String (4 Ziffern) | ja | Herstellerschlüsselnummer |
tsn | String (3 Zeichen) | ja | Typschlüsselnummer |
page | Integer | nein | Seite, ab 1 (Standard 1) |
per_page | Integer | nein | Einträge je Seite, höchstens 100 (Standard 50) |
Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
configurations[].configuration_id | String | Schlüssel der Konfiguration |
configurations[].type_approval, approval_base, approval_extension | String | Vollständige Typgenehmigung, ihre Basis und der Nachtrag |
configurations[].type, variant, version | String | Typ, Variante und Version laut Genehmigung |
configurations[].variant_key | String|null | Zugeordnete Fahrzeugvariante; null, wenn die Konfiguration keiner einzelnen Variante zugeordnet ist |
configurations[].technical_observations[] | Array | Technische Werte der Konfiguration (z. B. Hubraum, Leistung, Massen, Achslasten) mit field, value, unit und Messbezug. Eine nicht angegebene Einheit ist null mit unit_status: not_documented. Werte, die unser Datenabgleich nicht bestätigt, tragen zusätzlich akte_confirmed: false. |
configurations[].approval_observations[], approval_validity | Array, String | Rücknahmeeinträge zur Genehmigung mit reported_start, reported_end (ohne Zeitzone; fehlendes Ende null) und record_position (Kennung, keine Reihenfolge). Liegen Einträge vor, ist approval_validity=not_determined. |
configurations[].registration_observations[] | Array | Jährliche Zulassungsstatistik (siehe unten) |
meta.page, per_page, total | Integer | Paginierung |
meta.status | String | verified_identity_links oder, bei leerer Liste, configuration_links_not_verified |
meta.selection_required | Boolean | true bei mehr als einer Konfiguration |
Zulassungsstatistik: registration_observations[].context nennt Jahr, Land und mit provisional den vorläufigen Stand. Jede Gruppe enthält in combinations gemeinsam beobachtete Messwertkombinationen; Werte verschiedener Kombinationen nicht zu einer neuen Kombination zusammensetzen. rows zählt die Datensätze, represented_registrations summiert deren bekannte Zulassungen, unknown_registration_count_rows zählt Datensätze ohne Anzahl. earliest_registration_date und latest_registration_date begrenzen die bekannten Zulassungsdaten (null, wenn keine bekannt sind); unknown_registration_date_rows zählt fehlende Daten. Eine leere Kombination kennzeichnet Datensätze ohne Messwerte. observation_id und combination_id kennzeichnen Statistikeinträge und sind keine configuration_id. Die Statistik beschreibt Zulassungen, nicht ein einzelnes Fahrzeug.
Fehler
| HTTP | Code | Ursache |
|---|---|---|
| 400 | invalid_vehicle_key | HSN oder TSN im falschen Format |
| 400 | rest_invalid_param | page oder per_page ungültig |
| 404 | vehicle_not_found | HSN/TSN unbekannt |
Beispiel
curl -H "X-API-Key: carapi_live_xxxx" -H "X-API-Secret: IHR_SECRET" \
"https://api4cars.com/wp-json/carapi/v1/vehicle-configurations?hsn=0603&tsn=COB&per_page=10"
{
"hsn": "0603",
"tsn": "COB",
"configurations": [
{ "configuration_id": "cfg_9b2e…d41a", "type_approval": "e1*2007/46*1234*05", "approval_base": "e1*2007/46*1234", "approval_extension": "05", "type": "CR", "variant": "CRCCMA", "version": "FD6FD6E1", "variant_key": "beispiel-variante-1" }
],
"meta": { "page": 1, "per_page": 10, "total": 1, "status": "verified_identity_links", "selection_required": false }
}Liefert die Versicherungs-Typklassen (Haftpflicht, Teilkasko, Vollkasko) mit Jahreswerten, für ein HSN/TSN-Paar oder für alle Fahrzeuge einer Marke bzw. eines Modells.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
hsn, tsn | String | bedingt | Ein Fahrzeug; immer beide zusammen senden |
brand, model | String | bedingt | Suche nach Marke und/oder Modell (Teiltreffer im Modellnamen), wenn kein HSN/TSN gesendet wird |
page | Integer | nein | Nur Marken-/Modellsuche: Seite, 1–1000000 |
per_page | Integer | nein | Nur Marken-/Modellsuche: 1–100 (Standard 50) |
Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
insurance.kh, tk, vk | String|Integer | Aktuelle Typklassen Haftpflicht, Teilkasko, Vollkasko |
insurance.typklassen_history | Object | Typklasse je Sparte und Jahr |
insurance.typklassen_year | String | Jahrgang der aktuellen Typklassen: höchstes Jahr in typklassen_history über alle Sparten; fehlt ohne Jahreswerte |
results[] | Array | Marken-/Modellsuche: {hsn, tsn, insurance} je Fahrzeug, sortiert nach HSN/TSN |
meta | Object | Mit page oder per_page: page, per_page, total, total_pages. Ohne diese Parameter enthält results alle Treffer. |
Fehler
| HTTP | Code | Ursache |
|---|---|---|
| 400 | invalid_vehicle_key | Unvollständiges oder ungültiges HSN/TSN-Paar |
| 400 | invalid_pagination, invalid_insurance_query | Ungültige Seitenangaben oder Parametertypen |
| 400 | – | Weder HSN/TSN noch Marke/Modell; Antwort {"error": "Provide hsn/tsn OR brand/model"} |
| 404 | – | HSN/TSN unbekannt; Antwort {"error": "Vehicle not found", "hsn", "tsn"} |
| 500 | insurance_query_failed | Daten vorübergehend nicht lesbar |
Beispiel
curl -H "X-API-Key: carapi_live_xxxx" -H "X-API-Secret: IHR_SECRET" \
"https://api4cars.com/wp-json/carapi/v1/insurance?hsn=0603&tsn=COB"
{
"hsn": "0603",
"tsn": "COB",
"insurance": {
"kh": "19",
"tk": "18",
"vk": "17",
"typklassen_history": {
"Haftpflicht": { "2025": 19, "2026": 19 },
"Teilkasko": { "2025": 18, "2026": 18 },
"Vollkasko": { "2025": 18, "2026": 17 }
},
"typklassen_year": "2026"
}
}Markenübergreifende Suche und technische Daten auf Ebene technischer Datensätze. Jeder Treffer nennt seinen Suchschlüssel variant_key und, falls zugeordnet, die Fahrzeugvariante vehicle_variant_key (sonst null). Für /compatibility und /fitments den vehicle_variant_key verwenden. Gemeinsamer Fehler: HTTP 503 vehicle_discovery_dataset_not_ready, wenn der Suchindex nicht verfügbar ist; HTTP 400 rest_invalid_param bei ungültigen Filterwerten.
/vehicle-search
Sucht Fahrzeugvarianten nach technischen Merkmalen.
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
q, brand, model | String | nein | Freitext, Marke, Modell |
body_type, fuel, transmission, drive_type | String/Liste | nein | Karosserie, Kraftstoff, Getriebe, Antrieb; kommagetrennt |
doors, seats | Integer | nein | Türen, Sitzplätze |
min_/max_length_mm, min_/max_width_mm, min_/max_height_mm | Integer | nein | Maße in mm |
min_power_kw, max_power_kw | Integer | nein | Leistung in kW |
production_year, production_start, production_end | Integer | nein | Bauzeit |
min_/max_braked_kg, min_/max_nose_weight_kg | Integer | nein | Anhängelast gebremst, Stützlast |
include | String | nein | facets: Trefferzahlen je Hersteller, Karosserie, Kraftstoff, Getriebe, Antrieb |
page, per_page | Integer | nein | Seite (ab 1), Treffer je Seite (Standard 25) |
Produktionszeiträume beschreiben die dokumentierte Bauzeit. Sie sind keine Zusage, dass ein Modell aktuell in Deutschland bestellbar ist. production.end_status: documented (belegtes Ende; der Jahresfilter prüft das Intervall), ongoing (laufende Produktion; der Jahresfilter gilt ab dem Startjahr) oder unknown (der Jahresfilter bestätigt nur das Startjahr).
GET /vehicle-search?body_type=suv&fuel=hybrid,electric&transmission=automatic&seats=5&max_length_mm=4700&include=facets/engine-search und /engine-applications
/engine-search durchsucht Motorcodes (q, brand, fuel, page, per_page). /engine-applications liefert zu einem exakten Code (code, Pflicht) die Fahrzeugvarianten und HSN/TSN-Paare.
GET /engine-search?q=M271
GET /engine-applications?code=M271.820/vehicle-compare
Vergleicht zwei bis fünf HSN/TSN-Paare. vehicles (Pflicht) ist eine kommagetrennte Liste HSN/TSN. variant_keys (optional) ist ein URL-kodiertes JSON-Objekt, das einzelnen Paaren einen Suchschlüssel oder vehicle_variant_key zuordnet. Mehrere Datensätze einer Variante bleiben getrennt. Marke und Modell stehen an jeder Variante; auf Ebene des HSN/TSN-Paars sind sie null, wenn sich die Varianten darin unterscheiden. Fehler: HTTP 400 variant_not_for_vehicle, wenn ein Schlüssel nicht zum Paar gehört.
GET /vehicle-compare?vehicles=0588/AXM,1313/ABK&variant_keys=%7B%220588%2FAXM%22%3A%22beispiel-variante-1%22%7D/workshop-profile
Liefert Füllmengen, Achslasten und Radbefestigung. Parameter: hsn, tsn (Pflicht), variant_key (Suchschlüssel oder Fahrzeugvariante) oder configuration_id. Unterschiedliche technische Angaben bleiben als getrennte profiles[] erhalten. Nicht dokumentierte Werte bleiben null, ebenso Wertebereiche und widersprüchliche Angaben. Vor Wartungsarbeiten die Herstellerunterlagen heranziehen. Fehler: HTTP 404 vehicle_not_found bei unbekanntem Fahrzeug, HTTP 404 {"error": "Vehicle or variant not found"} bei unbekannter Variante; HTTP 409 display_configuration_link_unverified bei variant_key zusammen mit configuration_id; HTTP 409 configuration_evidence_required, wenn für die Auswahl keine technischen Daten vorliegen.
GET /workshop-profile?hsn=1313&tsn=ABK/towing-search
Findet Varianten nach Anhängelast. min_braked_kg ist Pflicht; alle Filter von /vehicle-search außer include sind zusätzlich möglich. Maßgeblich bleibt die Zulassungsbescheinigung.
GET /towing-search?min_braked_kg=1800&seats=5Felgenkatalog mit technischen Varianten, Gutachten und freigestellten Produktbildern. Die Passung für ein Fahrzeug liefern /compatibility und /fitments.
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
brand, q | String | nein | Felgenhersteller (weitere Namen derselben Marke finden dieselben Felgen: MM-Concepts = MM-Wheels), Suchtext |
status | String | nein | Modellstatus; ohne Angabe nur active, Entwürfe mit draft |
with_images | Boolean | nein | Bildangaben je Felge ergänzen |
page, per_page | Integer | nein | Seite (ab 1), Einträge je Seite (1–100, Standard 50) |
GET /wheels liefert {total, page, per_page, wheels: [{wheel_code, brand, model_name, design, classification, status, counts, preview}]}. GET /wheels/{wheel_code} liefert Details mit classification, Varianten, Gutachten, colors, showcase und images; für Bildintegrationen colors[].views verwenden. colors[].views_transparent enthält dieselben vier Ansichten und Größenstufen freigestellt mit transparentem Hintergrund und ohne Bodenschatten (WebP mit Alphakanal); das Feld fehlt bei einer Farbe, solange nicht alle vier Ansichten freigestellt vorliegen. colors[].complete_wheel (optional) zeigt dieselbe Felge als Komplettrad mit einem neutralen Symbolreifen ohne Marke, als summer (Sommerprofil) und winter (Winterprofil) mit je views in denselben Ansichten und Größenstufen, weißer Hintergrund mit Bodenschatten. Der Reifen ist für alle Felgen gleich und nur eine Darstellung; er sagt nichts über zulässige Reifengrößen (die stehen im Gutachten). Fehlt das Feld oder ein Profil, gibt es dafür noch kein Komplettradbild. Die Antwort enthält ausschließlich die dokumentierten Kundenfelder. Ein fehlendes Bild sagt nichts über die Passung aus. Jeder Felgencode, zu dem /fitments Passungen liefert, hat eine aktive Katalogzeile mit Marke und Modell; Bilder können noch fehlen (preview null, colors leer). Fehler: HTTP 404 carapi_wheel_not_found bei unbekanntem Felgencode.
GET /wheels?brand=…&status=active&with_images=1
GET /wheels/FF01Klassifizierung
Jeder Listeneintrag, die Detailantwort sowie jeder Eintrag in colors[] und variants[] enthält das Objekt classification mit Oberfläche, Speichenform und Wintereignung. Die Werte sind Katalogangaben aus beobachteten Produktausführungen (basis=catalog_reference, scope=observed_samples) und dienen der Anzeige und Filterung. Sie sind keine technische Freigabe und beeinflussen weder Passung noch Fitment-Status; maßgeblich für ein Fahrzeug sind /compatibility und /fitments.
| Feld | Typ | Beschreibung |
|---|---|---|
classification.status | String | available: mindestens ein Merkmal ist angegeben; unknown: keine Angabe für diese Felge bzw. Farbe |
classification.observed_sizes_inch | Integer[] | Zollgrößen, in denen die Angaben beobachtet wurden; leer bei unknown |
classification.finish | Object | Oberfläche: glossy (glänzend) oder matte (matt) |
classification.spoke_style | Object | Speichenform: five_spoke, y_spoke, v_spoke, double_spoke, cross_spoke oder multi_spoke (Viel- bzw. Mehrspeiche) |
classification.winter_suitable | Object | Wintereignung laut Katalogangabe: true (wintergeeignet) oder false (ausdrücklich nicht wintergeeignet) |
{merkmal}.status | String | Je Merkmal (finish, spoke_style, winter_suitable): known (genau ein Wert), mixed (unterschiedliche Werte über Farben oder Größen) oder unknown (keine Angabe) |
{merkmal}.value | String|Boolean|null | Der Wert bei known, sonst null |
{merkmal}.values | Array | Alle angegebenen Werte: einer bei known, mehrere bei mixed, leer bei unknown |
Die Angabe auf Modellebene fasst alle beobachteten Farben und Größen zusammen. colors[].classification und variants[].classification gelten für die jeweilige Farbe; eine Farbe ohne eigene Angabe liefert status=unknown und übernimmt keine Werte des Modells. winter_suitable.value=false ist eine ausdrückliche Negativangabe, eine fehlende Angabe ist null mit status=unknown. Für den Wintereinsatz am Fahrzeug gelten die Herstellerangaben und die Fahrzeugpapiere.
"classification": {
"basis": "catalog_reference",
"scope": "observed_samples",
"status": "available",
"observed_sizes_inch": [18, 19],
"finish": { "status": "mixed", "value": null, "values": ["glossy", "matte"] },
"spoke_style": { "status": "known", "value": "multi_spoke", "values": ["multi_spoke"] },
"winter_suitable": { "status": "known", "value": false, "values": [false] }
}Kostenpflichtiges Zusatzmodul für fahrzeug- und felgenspezifische Konfiguratorbilder. Es erfordert zusätzlich zur API-Berechtigung die Freischaltung configurator_images. Der Endpunkt ordnet HSN/TSN einer Bildgruppe zu und gibt nur Felgen aus, die für das HSN/TSN-Paar freigegeben sind. Antworten sind fünf Minuten gültig.
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
hsn, tsn | String | bedingt | Fahrzeug; alternativ vehicle_image_id |
vehicle_image_id | String | bedingt | Bildgruppe; wählt bei mehreren Treffern eine Gruppe |
variant_key | String | nein | Wählt die Bildgruppe, wenn Karosserie und gesamter Bauzeitraum der Variante genau eine Bildgruppe treffen |
wheel, paint, finish | String | ja* | *Nur images und layers: Felgencode, Lack, Felgenfinish |
size | Integer | nein | Felgengröße in Zoll |
/configurator/availability liefert verfügbare Felgen, Lacke, Finishes, Ansichten und Größen. Trifft das Fahrzeug mehrere Bildgruppen, antwortet der Endpunkt mit HTTP 200, ambiguous=true und den wählbaren vehicle_image_id-Werten in matches; /configurator/images und /configurator/layers antworten dann mit HTTP 409 configurator_vehicle_ambiguous.
GET /configurator/images?hsn=0603&tsn=ABC&wheel=FF01&paint=pure_white&finish=anthrazit
GET /configurator/layers?hsn=0603&tsn=ABC&wheel=FF01&paint=pure_white&finish=anthrazit&size=19/configurator/layers liefert je Ansicht eine verlustfreie WebP-Basis mit positionierten Rad- und Lack-Ebenen in large (1400 px Breite) und medium (800 px). Der Client zeichnet base → wheel → paint; Basis und Lack-Ebenen gelten für alle Felgen desselben Fahrzeugs. Die Antworten enthalten die Ansichten front_three_quarter, rear_three_quarter, side und wheel_focus. delivery gibt das Format an: full_images (Vollbilder full in nativer Auflösung und small mit 800 px) oder edge_render (kurzzeitig signierte URLs large mit 1400 px und medium mit 800 px).
{
"vehicle": { "vehicle_image_id": "vw-golf-viii", "label": "VW Golf VIII" },
"delivery": "full_images",
"selection": { "wheel": "FF01", "paint": "pure_white", "finish": "anthrazit" },
"revision": "a1b2c3d4e5f6a7b8",
"views": {
"front_three_quarter": {
"full": { "url": "https://cdn.api4cars.com/.../front_three_quarter-full.webp", "format": "webp", "width": 2747, "height": 1531 },
"small": { "url": "https://cdn.api4cars.com/.../front_three_quarter-small.webp", "format": "webp", "width": 800, "height": 446 }
}
}
}| HTTP | Code | Ursache |
|---|---|---|
| 400 | rest_missing_vehicle, rest_missing_selection | Fahrzeug oder wheel/paint/finish fehlt |
| 403 | feature_not_enabled | Zusatzmodul nicht freigeschaltet |
| 404 | configurator_not_found, wheel_not_approved_for_vehicle, configurator_wheel_not_published, configurator_size_not_found, configurator_selection_not_found | Kein Bildset, Felge nicht freigegeben oder Kombination nicht veröffentlicht |
| 409 | configurator_vehicle_ambiguous | Mehrere Bildgruppen; vehicle_image_id senden |
| 409 | configurator_layers_unavailable | Bildset ohne Ebenen; /configurator/images verwenden |
Amtlich gestützte Pkw-Markt-, Regional-, Umwelt-, Sicherheits- und Infrastrukturdaten für Deutschland. Die Antworten sind je nach Endpunkt 1 bis 24 Stunden gültig, paginiert und nennen meta.included, meta.omitted, Evidenzkategorie, Geltungsbereich und Qualitätsstatus. Unbekannte Parameter werden mit HTTP 400 rest_unknown_param abgelehnt.
| Endpunkt | Zweck | Wichtige Parameter |
|---|---|---|
/intelligence/vehicle | HSN/TSN-Historie und zugeordnete Bereiche | hsn, tsn (Pflicht), include, from, to, region |
/intelligence/market | Bestand, Marktbewegungen, Umwelt-, Sicherheits- und Verkehrsaggregate | metric, brand, model_series, segment, fuel, from, to und weitere Filter |
/intelligence/regions | Pkw-Zeitreihen nach Bundesland, Zulassungsbezirk oder veröffentlichter Gebietsebene | ags, nuts, metric, Filter wie bei market |
/intelligence/recalls | Rückrufe mit geprüfter Marken-/Modellzuordnung | hsn+tsn, brand, model, status, from, to |
/intelligence/charging | Ladeinfrastruktur | profile=statistics oder sites, region, metric; Orts-/Radiusfilter nur mit sites |
/intelligence/opportunity | Potenziale für Fahrzeug, Modellreihe, Marke oder Felge | entity_type, key (Pflicht), region |
/intelligence/sources | Evidenzkategorie, Berichtszeitraum, Granularität und Qualitätsstatus | family_key, status |
Geltungsbereich: HSN/TSN-Werte sind exakt, wenn die amtliche Statistik diese Granularität veröffentlicht; jede Metrik nennt scope.hsn_tsn_exact und eine stabile source_family. Handelsnamen-, Typgenehmigungs-, Regional-, Sicherheits- und Verkehrsaggregate werden nur auf ihrer veröffentlichten Ebene ausgegeben. Rückrufe sind geprüfte Modellzuordnungen. Unterdrückte Werte sind suppressed, nicht 0. Eigene Auswertungen tragen is_estimate=true und eine method_version. Halterdaten beschreiben Halter, nicht Fahrer.
Beispiele
Regionaler Bestand
/intelligence/regions?ags=08115&metric=registered_stock&from=2019-01-01geography.code enthält den amtlichen Gebietsschlüssel (AGS).
Markt nach Marke
/intelligence/market?brand=BMW&metric=new_registrations&holder_group=private&from=2019-01-01
/intelligence/regions?ags=09&brand=BMW&metric=new_registrations
Weitere Filter: trade_name, tsn, age_band, gender.
Regionale Bewegung
/intelligence/regions?ags=08111&metric=ownership_transfers&from=2019-01-01Weitere Metriken: new_registrations, deregistrations; economic_sector filtert die veröffentlichte Haltergruppe.
Modellreihe / Segment
/intelligence/market?model_series=VW%20GOLF&metric=new_registrations&from=2019-01-01
/intelligence/market?segment=SUVs&metric=market_share_pct
/intelligence/market?all_wheel=1&metric=new_registrations
Aggregate ohne HSN/TSN-Granularität: dimensions.hsn_tsn_exact=false. Weitere Filter: fuel, body_type=cabriolet; weitere Metriken: segment_share_pct, registered_stock, registered_stock_yoy_pct.
Typgenehmigung
/intelligence/market?type_approval=e1*2007/46*2014&metric=avg_co2_wltp_g_km&from=2020-01-01Weitere Metriken: new_registrations, avg_co2_nedc_g_km, avg_empty_mass_kg. Vorläufige Berichtsstände sind im Qualitätsstatus erkennbar.
Verkehrssicherheit / Infrastruktur
/intelligence/market?metric=road_safety_unfaelle_personenschaden&accident_category=Unfall%20mit%20Personenschaden
/intelligence/market?metric=annual_vehicle_km&road_class=federal_motorway
Filter: vehicle_scope, injury_severity, location. Die Zeitreihen beschreiben Deutschland bzw. Bundesfernstraßen.
Umwelt / Antrieb
/intelligence/market?model_series=VW%20GOLF&metric=avg_co2_g_km&from=2022-01-01
/intelligence/market?fuel=bev&motor_power_kw_band=81_100&metric=new_registrations
/intelligence/market?co2_class=A&metric=new_registrations
Teilmengen tragen dimensions.is_subset=true; nicht zusätzlich zur Obergruppe summieren.
Monatswerte
/intelligence/market?drive_type=bev&metric=new_registrations&from=2025-01-01
/intelligence/regions?drive_type=plug_in_hybrid&metric=new_registrations&from=2025-01-01
Veröffentlichte Ranglisten tragen ranking_scope und rank; sie sind keine vollständige Modellrangliste. Weitere Filter: color, co2_emission_band, fuel_consumption_band, gross_vehicle_mass_band.
Halter / Flotte
/intelligence/market?metric=registered_stock&economic_sector=rental_carsharing&from=2019-01-01Weitere Filter: engine_displacement_band, vehicle_age_band (Fahrzeugalter). age_band und gender bezeichnen veröffentlichte Haltermerkmale.
Ladeinfrastruktur
/intelligence/charging?profile=statistics&metric=charging_points_total®ion=DE:federal_state:09&from=2019-01-01Ohne Standortdaten im Statistikstand ist site_level_available=false.
Fehlerreferenz
Fehlerantworten haben diese Form:
{
"code": "variant_not_for_vehicle",
"message": "Select a current variant returned for this vehicle.",
"data": { "status": 400, "variant_key": "unbekannter-schluessel" }
}Ausnahmen: Ein unbekanntes HSN/TSN-Paar bei /vehicle (ohne configuration_id) und /insurance sowie eine unbekannte Variante bei /workshop-profile liefern HTTP 404 mit {"error", "hsn", "tsn"}; vehicle_discovery_dataset_not_ready liefert {"code", "message"}. Für die Reaktion den code auswerten, nicht den Text von message.
HTTP-Status
| HTTP | Bedeutung |
|---|---|
200 | Erfolg |
304 | Unverändert (If-None-Match) |
400 | Fehlender, ungültiger oder unzulässiger Parameter; Auswahl passt nicht zum Fahrzeug |
401 | Zugangsdaten fehlen oder sind ungültig |
403 | Abonnement nicht aktiv oder Zusatzmodul nicht freigeschaltet |
404 | Fahrzeug, Felge oder Bildset nicht gefunden |
409 | Anfrage gültig, aber für die gewählte Auswahl liegen nicht genug Daten vor, der Datenstand hat sich während der Paginierung geändert oder die Bildauswahl ist mehrdeutig. Eine gespeicherte Auswahl bleibt gültig. |
429 | Anfragekontingent ausgeschöpft |
500 | Interner Fehler |
503 | Daten vorübergehend nicht verfügbar; später erneut anfragen |
Fehlercodes
| Code | HTTP | Endpunkte | Bedeutung | Reaktion |
|---|---|---|---|---|
rest_unauthorized | 401 | alle | Keine Zugangsdaten gesendet | Header X-API-Key/X-API-Secret oder Bearer Token senden |
rest_invalid_api_key | 401 | alle | API Key unbekannt oder widerrufen | Zugangsdaten im Account prüfen |
rest_invalid_api_secret | 401 | alle | Secret passt nicht zum Key | Zugangsdaten im Account prüfen |
rest_subscription_inactive | 403 | alle | Abonnement nicht aktiv | Tarif aktivieren |
feature_not_enabled | 403 | /configurator/* | Zusatzmodul nicht freigeschaltet | Modul buchen |
| – | 429 | alle | Anfragekontingent ausgeschöpft | Tarif erweitern oder später erneut anfragen |
rest_missing_callback_param | 400 | alle | Pflichtparameter fehlt | Parameter ergänzen |
rest_invalid_param | 400 | alle | Parameterwert hat ein ungültiges Format oder liegt außerhalb des Wertebereichs | Wert korrigieren; data.params nennt den Parameter |
rest_unknown_param | 400 | /fitments, /intelligence/*, /vehicle mit Intelligence-include | Unzulässiger Parameter | Parameter entfernen |
invalid_vehicle_key | 400 | /vehicle-configurations, /insurance | HSN/TSN im falschen Format oder unvollständig | Eingabe korrigieren |
invalid_pagination | 400 | /insurance | Ungültige Seitenangabe | Wert korrigieren |
invalid_insurance_query | 400 | /insurance | Parameter mehrfach oder als Liste gesendet | Einzelwerte senden |
invalid_execution | 400 | /engines | execution_key gehört nicht zu dieser Generation | /generations?include=executions neu laden |
variant_not_for_vehicle | 400 | /compatibility, /fitments, /vehicle-compare | Schlüssel gehört nicht zu diesem Fahrzeug | Auswahl entfernen, Fahrzeug ohne Auswahl laden, variants[] anbieten |
conflicting_vehicle_selections | 400 | /compatibility, /fitments | variant_key und configuration_id gemeinsam gesendet | Nur einen Parameter senden |
invalid_configuration_id | 400 | /vehicle, /compatibility, /fitments, /workshop-profile | configuration_id hat ein ungültiges Format | ID aus /vehicle-configurations verwenden |
configuration_not_for_vehicle | 400 | /vehicle, /compatibility, /fitments, /workshop-profile | Konfiguration gehört nicht zu diesem Fahrzeug | Konfiguration neu wählen |
rest_missing_vehicle, rest_missing_selection | 400 | /configurator/* | Fahrzeug bzw. Felge, Lack oder Finish fehlt | Parameter ergänzen |
vehicle_not_found | 404 | /compatibility, /fitments, /vehicle-configurations, /workshop-profile, /vehicle mit configuration_id | HSN/TSN unbekannt | Eingabe prüfen |
carapi_wheel_not_found | 404 | /wheels/{wheel_code} | Felgencode unbekannt | Code aus /wheels verwenden |
configurator_not_found, wheel_not_approved_for_vehicle, configurator_wheel_not_published, configurator_size_not_found, configurator_selection_not_found | 404 | /configurator/images, /configurator/layers | Kein Bildset für Fahrzeug, Felge, Größe oder Kombination | Verfügbarkeit über /configurator/availability prüfen |
variant_facts_unavailable | 409 | /compatibility, /fitments | Für die gewählte Variante fehlen technische Daten | Auswahl behalten; Ergebnis ohne Auswahl anzeigen |
configuration_evidence_required | 409 | /compatibility, /fitments, /workshop-profile | Für die Konfiguration fehlen belegte Fahrzeugdaten (z. B. Radgeometrie) | Auswahl behalten; ohne Konfiguration oder mit variant_key anfragen |
fitment_evidence_required | 409 | /compatibility, /fitments | Für das Fahrzeug liegen keine belegten Anwendungsdaten vor | Keine Passungsaussage anzeigen |
display_configuration_link_unverified | 409 | /workshop-profile | variant_key zusammen mit configuration_id | Nur einen Parameter senden |
fitment_dataset_changed | 409 | /fitments | Datenstand seit der ersten Seite geändert | Paginierung ab Seite 1 ohne data_version neu beginnen |
configurator_vehicle_ambiguous | 409 | /configurator/images, /configurator/layers | Mehrere Bildgruppen | vehicle_image_id aus data.matches senden |
configurator_layers_unavailable | 409 | /configurator/layers | Bildset ohne Ebenen | /configurator/images verwenden |
taxonomy_unavailable | 503 | /taxonomy | Taxonomie vorübergehend nicht lesbar (wird nicht als leere Liste ausgeliefert oder zwischengespeichert) | Später erneut anfragen |
insurance_query_failed | 500 | /insurance | Daten nicht lesbar | Später erneut anfragen |
fitment_data_invalid, fitment_data_unavailable | 503 | /compatibility, /fitments | Passungsdaten vorübergehend nicht lesbar | Später erneut anfragen; Auswahl behalten |
vehicle_catalog_unavailable | 503 | Navigationsendpunkte | Fahrzeugkatalog vorübergehend nicht lesbar | Später erneut anfragen |
vehicle_discovery_dataset_not_ready | 503 | Alpha Fahrzeugsuche und Technik | Suchindex nicht verfügbar | Später erneut anfragen |
Warnungen in meta.warnings sind keine Fehler: unknown query parameter: … und selection_unavailable_release_mismatch (siehe Grundlagen).
Integration
Fragen zur Integration?
Schick uns deinen Anwendungsfall – wir helfen dir bei der Wahl der Endpunkte.