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-CarAPI-Warnings genannt (unknown query parameter: name). 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).

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

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=COB

C) 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, lautet das Ergebnis „passt“ mit einem Hinweis in row_hints[], der das betroffene Modell nennt. 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.

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

Wirkung je Endpunkt

Weitere Schlüssel

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

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

Fehler

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

limit und include gibt es bei /fitments nicht; sie werden mit HTTP 400 rest_unknown_param abgelehnt.

Antwortfelder

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

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

Antwortfelder

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", "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 } },
  "total_pdfs": 1
}

Passungsstatus

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.

Ausstattung, die nur am einzelnen Fahrzeug prüfbar ist, ergibt „passt“ mit Hinweis. 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.

{
  "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

Antwortfelder

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

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

Antwortfelder

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

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

Antwortfelder

Fehler

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 }
    }
  }
}

Navigation

Die Navigationsendpunkte führen von der Marke zur Fahrzeugadresse (siehe Wege zur Fahrzeugadresse). Alle Werte unverändert und URL-kodiert an den nächsten Schritt übergeben. onlyWithFitments=1 beschränkt auf Einträge mit mindestens einer Felgenfreigabe; ohne Treffer ist die Liste leer. Fehler: HTTP 400 rest_missing_callback_param bei fehlendem Pflichtparameter, HTTP 503 vehicle_catalog_unavailable, wenn die Daten vorübergehend nicht lesbar sind.

GET /brands

Liste der Fahrzeugmarken.

Antwort: Liste von {brand, count, withFitments, logo_url}. brand ist der Wert für die Folgeschritte.

GET /brands?onlyWithFitments=1
[ { "brand": "Audi", "count": 1826, "withFitments": 842, "logo_url": "https://…/audi.png" } ]

GET /models

Modelle einer Marke, alphabetisch.

Antwort: Liste von {value, label, withFitments}. value ist der Modellschlüssel für /generations; withFitments zählt HSN/TSN-Paare mit Freigaben.

GET /models?brand=BMW
[ { "value": "3er-Reihe", "label": "3er-Reihe", "withFitments": 87 } ]

GET /generations

Generationen eines Modells.

Antwort: Liste von {value, label, years}; mit include=executions zusätzlich executions[] mit value, label, body_type und engine_count. Jede Ausführung entspricht einer belegten Karosserieform der Generation; unspecified fasst Fahrzeuge ohne belegte Karosserieform zusammen. Ausführungsschlüssel sind stabil.

Darstellung: Generation und Ausführung in einer Auswahlliste kombinieren, etwa „A4 B8 Facelift · Avant“, und generation.value sowie executions[].value getrennt speichern. Bei nur einer Ausführung entfällt die Auswahl.

GET /generations?brand=BMW&model=3er-Reihe&include=executions
[ { "value": "3er-Reihe G20/G21/G80", "label": "3er-Reihe G20/G21/G80", "years": "2019 - 2022",
    "executions": [ { "value": "limousine", "label": "Limousine", "body_type": "Limousine", "engine_count": 12 } ] } ]

GET /engines

Motorgruppen einer Generation, optional einer Ausführung. Motorisierungen mit gleicher Leistung, Kraftstoffart und gleichem Antrieb werden zusammengefasst; engine_labels[], periods[] und transmissions[] enthalten die Einzelangaben. Diese nicht wieder in einzelne Motoroptionen aufteilen.

Antwort: Liste von Motorgruppen mit label, kw, ps, fuel, years, transmission, drivetrain, periods[], transmissions[], execution, pairs[], selection_options[] (hsn, tsn, variant_key, selection_required) und selection_required. Fehler: HTTP 400 invalid_execution, wenn execution_key zu dieser Generation nicht existiert. Cache-Schlüssel aus Marke, Modell, Generation und Ausführung bilden; bei Änderung eines übergeordneten Schritts abhängige Auswahl verwerfen.

GET /engines?brand=BMW&model=3er-Reihe&generation=3er-Reihe%20G20%2FG21%2FG80&execution_key=limousine
[ { "label": "320i (184 PS / 135 kW)", "kw": 135, "ps": 184, "fuel": "Benzin", "years": "03/19 - 04/22",
    "pairs": [ { "hsn": "0005", "tsn": "CNA" } ],
    "selection_options": [ { "hsn": "0005", "tsn": "CNA", "variant_key": "beispiel-variante-1", "selection_required": false } ],
    "selection_required": false } ]

GET /series

Baureihen einer Marke.

Antwort: {brand, models: [{series, seriesCode, modelKey, modelFamily, total, withFitments}]}. series ist der Wert für /variants. modelKey ist der Modellschlüssel für /generations (null, wenn keine Generation zugeordnet ist); modelFamily ist nur ein Anzeigefeld.

GET /series?brand=VW&onlyWithFitments=1
{ "brand": "VW", "models": [ { "series": "Touareg (CR) (07/18 - 05/23)", "seriesCode": "CR", "modelKey": "Touareg", "modelFamily": "Touareg", "total": 8, "withFitments": 7 } ] }

GET /variants

HSN/TSN-Paare einer Baureihe.

Antwort: {total, variants: [...]} mit id (HSN_TSN), hsn, tsn, model, series, seriesCode, type, drivetrain, years, hasFitments, vehicle_image und selection_options[] (je Variante ein Eintrag {hsn, tsn, variant_key}). Paare mit Freigaben stehen zuerst.

GET /variants?brand=VW&series=Touareg%20(CR)%20(07%2F18%20-%2005%2F23)
{ "total": 8, "variants": [ { "id": "0603_COB", "hsn": "0603", "tsn": "COB", "model": "Touareg 3.0 V6 TDI SCR", "years": "10/20 – 05/23", "hasFitments": true,
  "selection_options": [ { "hsn": "0603", "tsn": "COB", "variant_key": "beispiel-variante-1" } ] } ] }

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.

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=5

Felgenkatalog mit technischen Varianten, Gutachten und freigestellten Produktbildern. Die Passung für ein Fahrzeug liefern /compatibility und /fitments.

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. Die Antwort enthält ausschließlich die dokumentierten Kundenfelder. Ein fehlendes Bild sagt nichts über die Passung aus. Fehler: HTTP 404 carapi_wheel_not_found bei unbekanntem Felgencode.

GET /wheels?brand=…&status=active&with_images=1
GET /wheels/FF01

Klassifizierung

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.

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.

/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 }
    }
  }
}

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.

Beispiele

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

Fehlercodes

Warnungen in meta.warnings sind keine Fehler: unknown query parameter: … und selection_unavailable_release_mismatch (siehe Grundlagen).