Benutzer-Werkzeuge

Webseiten-Werkzeuge


dokumentation_der_restful_api_version_2

Dokumentation der RESTful API Version 2

Eine allgemeine Beschreibung der RESTful API finden Sie unter APIs.

Authentifizierung und Sicherheit

Die Authentifizierung erfolgt per Basic-HTTP-Auth mit Nutzername und Passwort.

Die Schnittstelle ist nur über HTTPS erreichbar.

Bei einem Authentifizierungsfehler wird ein Fehler mit Status 401 und Code "UNAUTHORIZED" zurückgegeben.

Datentypen, Encoding

POST-Parameter werden mit dem MIME-Type application/x-www-form-urlencoded formatiert und mit UTF-8 kodiert übergeben.

Antworten werden als JSON (Mime-Type application/json) formatiert und mit UTF-8 kodiert übertragen.

Fehlende Werte sowie null sind als gleichwertig zu betrachten. Im Gegensatz dazu bedeutet ein leeres Array oder Objekt, dass das Feld zwar berechnet wurde, jedoch tatsächlich keine Daten enthält.

Verhalten im Fehlerfall

Genutzte HTTP-Statuscodes

Hinweis: Der code wird nur zurückgegeben, wenn die Anfrage die API erreicht. Antworten des Webservers enthalten damit kein JSON. Insbesondere ist dies der Fall für alle Requests über HTTP, die durch den Server mit 301 Moved Permanently und einer Weiterleitung zu HTTPS beantwortet werden.

HTTP-Status/ status HTTP-Status Name code Beschreibung Verwendung
300 Multiple Choices MULTIPLE_MODELS Mehrere zutreffende Modelle gefunden Calculate
301 Moved Permanently MOVED_PERMANENTLY Zugriff ohne SSL mit Weiterleitung auf HTTPS Überall
400 Bad Request INVALID_INPUT Falsche oder fehlende Parameter Überall
401 Unauthorized UNAUTHORIZED Authentifizierungsfehler Überall bei fehlenden oder falschen Anmeldedaten
404 Not found NOT_FOUND Fehlerhafte URL Requests an nicht existierende URIs oder mit falschen Datentypen (z.B. einem String statt Integer) o.ä., die dadurch nicht zugeordnet werden können
NO_DATA Keine Modelle gefunden GetModels
Keine Baureihen gefunden GetSeries
Keine Aufbauten gefunden GetBodies
Keine Motoren gefunden GetEngines
Keine Sondermodelle gefunden GetEditions
HSN/TSN nicht gefunden Calculate
NO_ESTIMATION_DATA HSN/TSN kann nicht geschätzt werden
MODEL_NOT_FOUND HSN/TSN gefunden, aber keine Treffer durch Angabe des Modells
SERIES_NOT_FOUND HSN/TSN gefunden, aber keine Treffer durch Angabe der Baureihe
EDITION_NOT_FOUND HSN/TSN gefunden, aber keine Treffer durch Angabe des Sondermodells
NO_MATCHES HSN/TSN gefunden, aber keine Treffer zum gewünschten Zeitpunkt oder durch Angabe von Aufbau oder Türen
405 Method Not Allowed METHOD_NOT_ALLOWED Unzulässige HTTP-Methode Überall
450 Rate Limit Exceeded RATE_LIMIT_EXCEEDED Request-Limit wurde erreicht
500 Internal Server Error INTERNAL_SERVER_ERROR Ein serverseitiger Fehler ist aufgetreten. Wenn möglich, wird eine kurze Erklärung in message gegeben
503 Service Unavailable SERVICE_UNAVAILABLE API ist auf Grund von Wartungsarbeiten o.ä. temporär nicht erreichbar

Format

error (Objekt) status Integer, entspricht dem HTTP-Status
code Maschinenlesbare Bezeichnung des Fehlers
message Beschreibung des Fehlers. Diese kann sich ohne Ankündigung ändern und sollte nicht zur automatisierten Auswertung herangezogen werden
invalid Für Status 400 (Bad Request): Liste ungültiger Eingabeparameter.Beispiel: "invalid":["year","month"]
missing Für Status 400 (Bad Request): Liste fehlender Eingabeparameter.Beispiel: "missing":["year","month"]
options Für Status 300 (Multiple Choices): Objekt mit Auswahlmöglichkeiten.Beispiel: "options":{"model":["X5","X6"]}]
url Für Status 300 (Multiple Choices): URL-Template mit Platzhaltern für die in options gelisteten Möglichkeiten.Beispiel (gekürzt): "url": "…\/calculate\/7909\/aak?…&model={model}"

Beispiel

GET https://autofokus24.de/api/v2/calculate/7909/aak?pretty_print&mileage=1&year=2013&month=5
{
    "error": {
        "status": 300,
        "code": "MULTIPLE_CHOICES",
        "message": "For HSN=7909 \/ TSN=aak multiple models exist"
    },
    "options": {
        "model": [
            "X5",
            "X6"
        ]
    },
    "url": "https:\/\/autofokus24.de\/api\/v2\/calculate\/7909\/aak?pretty_print&mileage=1&year=2013&month=5&model={model}"
}

URLs

Allgemeines

Prefix: /api/v2

Die folgenden URLs werden an den Prefix angehangen. Die zu verwendende HTTP-Methode zum Zugriff ist vorangestellt.

Alle aufgelisteten Parameter müssen, wenn nicht anders angegeben, übergeben werden.

Zusätzlich existiert für jede URI der Parameter pretty_print. Wird er mit übergeben, wird die Ausgabe serverseitig zur besseren Lesbarkeit formatiert. Der Wert des Parameters wird ignoriert.

Übersicht und Abrechnung

Name Methode URL Rückgabe Abrechnung
GetAllColors GET /colors Mögliche Farbcodes
GetAllEquipment GET /equipment Mögliche Ausstattungs-Kürzel
GetAllBodies GET /bodies Mögliche Aufbauvarianten
GetBrands GET /brands Alle Marken
GetModels GET /brands/{brand_id}/models Modelle einer Marke
GetSeries GET /models/{model_id}/series Baureihen eines Modells
GetBodies GET /series/{series_id}/bodies Aufbauten einer Baureihe
GetEngines GET /series/{series_id}/bodies/{body_id}/engines Motoren zur aktuellen Auswahl Nur kostenpflichtig, falls kein Folgeaufruf von GetEditions erfolgt
GetEditions GET /series/{series_id}/bodies/{body_id}/ ↵
engines/{engine_id}/editions
Sondermodelle und HSN/TSNs zur aktuellen Auswahl Kostenpflichtig, wird gezählt und abgerechnet
Calculate GET, POST /calculate/{hsn}/{tsn} Fahrzeugbewertung

GetAllColors

Beschreibung

Gibt ein Objekt mit Kurzbezeichnung-Farbname-Zuordnungen zurück. Die Kürzel können in Calculate verwendet werden.

Aufruf

  • Methode: GET
  • URL: …/colors

Beispiel

GET /api/v2/colors
{
    "wht": "weiss",
    "red": "rot",
    "ora": "orange",
    ...
}

GetAllEquipment

Beschreibung

Gibt ein Objekt mit Kurzbezeichnung-Featurename-Zuordnungen zurück. Die Kürzel können in Calculate verwendet werden.

Aufruf

  • Methode: GET
  • URL: …/equipment

Beispiel

GET /api/v2/equipment
{
    "GAS": "Gasantrieb",
    "ELE": "Elektromotor",
    "BHG": "behindertengerecht",
    ...
}

GetAllBodies

Beschreibung

Gibt ein Array aller verfügbaren Aufbauvarianten zurück. Die Kürzel können in Calculate verwendet werden.

Aufruf

  • Methode: GET
  • URL: …/bodies

Beispiel

GET /api/v2/bodies
[
    "BUS",
    "CABRIO",
    "COUPE",
    ...
]

GetBrands

Beschreibung

Gibt die Liste bekannter Marken mit ihrer jeweiligen ID zurück.

Aufruf

  • Methode: GET
  • URL: …/brands

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

  • brands, welches wiederum ein Objekt mit ID–Marken-Zuordnungen enthält
  • models_url: Die URL der nächsten möglichen Abfrage

Beispiel

GET /api/v2/brands
{
    "brands": {
        "1": "Alfa Romeo",
        "57": "ALPINA",
        "37": "VW",
        ...
    },
    "models_url": "https://autofokus24.de/api/v1/brands/{brand_id}/models",
}

GetModels

Beschreibung

Gibt die Liste der in einem bestimmten Zeitraum hergestellten Modelle zu einer angegebenen Marke zurück.

Aufruf

  • Methode: GET
  • URL: …/brands/{brand_id}/models

Parameter

In der URL übergeben:

Parameter Beschreibung
brand_id ID der Marke

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year Jahr der Erstzulassung Ja
month Monat der Erstzulassung

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

  • models, welches wiederum ein Objekt mit ID–Modellbezeichnung-Zuordnungen enthält
  • series_url: Die URL der nächsten möglichen Abfrage

Fehler

  • 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/brands/37/models?year=2015&month=5
{
    "models": {
        "850": "Amarok",
        "851": "Bora",
        "864": "Passat",
        ...
    },
    "series_url": "https://autofokus24.de/api/v2/models/{model_id}/series"
}

GetSeries

Beschreibung

Gibt die Liste der in einem bestimmten Zeitraum hergestellten Baureihen zu einem angegebenen Modell einer Marke zurück.

Aufruf

  • Methode: GET
  • URL: …/models/{model_id}/series

Parameter

In der URL übergeben:

Parameter Beschreibung
model_id ID des Modells

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year Jahr der Erstzulassung Ja
month Monat der Erstzulassung

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

  • series, welches wiederum ein Objekt mit ID–Baureihenbezeichnung-Zuordnungen enthält
  • bodies_url: Die URL der nächsten möglichen Abfrage

Fehler

  • 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/models/864/series?year=2015&month=5
{
    "series": {
        "1191": "Modell ab 2010",
        "1192": "Modell ab 2008 (CC)",
    },
    "bodies_url": "https://autofokus24.de/api/v2/series/{series_id}/bodies"
}

GetBodies

Beschreibung

Gibt die Liste der verfügbaren Aufbauten zu einem Modell in einer Baureihe zurück.

Aufruf

  • Methode: GET
  • URL: …/series/{series_id}/bodies

Parameter

In der URL übergeben:

Parameter Beschreibung
series_id ID der Baureihe

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year Jahr der Erstzulassung Ja
month Monat der Erstzulassung

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

  • bodies, welches wiederum aus Aufbau-Objekten besteht, wobei die ID der Aufbauvariante als Key genutzt wird
  • engines_url: Die URL der nächsten möglichen Abfrage

Die Aufbauobjekte bestehen aus folgenden Feldern:

Feld Typ Beschreibung
body String Bezeichnung des Aufbaus
doors Integer Anzahl Türen

Fehler

  • 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/series/1191/bodies?year=2015&month=5
{
    "bodies": {
        "42": {
            "body": "KOMBI",
            "doors": "5"
        },
        "45": {
            "body": "LIMOUSINE",
            "doors": "4"
        }
    },
    "engines_url": "https://autofokus24.de/api/v2/series/1191/bodies/{body_id}/engines"
}

GetEngines

Beschreibung

Gibt die Liste der verfügbaren Motoren zu einem Modell in einer Baureihe mit einem bestimmten Aufbau zurück.

Aufruf

  • Methode: GET
  • URL: …/series/{series_id}/bodies/{body_id}/engines

Parameter

In der URL übergeben:

Parameter Beschreibung
series_id ID der Baureihe
body_id ID der Aufbauvariante

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year Jahr der Erstzulassung Ja
month Monat der Erstzulassung

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

  • engines, welches wiederum aus Motor-Objekten besteht, wobei die ID des Motors als Key genutzt wird
  • editions_url: Die URL der nächsten möglichen Abfrage

Die Motorobjekte bestehen aus folgenden Feldern:

Feld Typ Beschreibung
kw Integer Leistung in Kilowatt (kW)
fuel String Kraftstoff. Mögliche Werte: DIESEL, BENZIN, ELEKTRO, HYBRID-BENZIN, HYBRID-DIESEL
cylinders Integer Zylinderanzahl
cubic_capacity Integer Hubraum in Kubikzentimeter (cm³ / ccm)

Fehler

  • 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/series/1191/bodies/42/engines?year=2015&month=5
{
    "engines": {
        "6590": {
            "kw": "77",
            "fuel": "DIESEL",
            "cylinders": "4",
            "cubic_capacity": "1.6"
        },
        "9050": {
            "kw": "90",
            "fuel": "BENZIN",
            "cylinders": "4",
            "cubic_capacity": "1.4"
        },
        ...
    },
    "editions_url": "https://autofokus24.de/api/v2/series/1191/bodies/42/engines/{engine_id}/editions"
}

GetEditions

Beschreibung

Gibt die Liste der verfügbaren Sondermodelle zu einem Modell in einer Baureihe mit einem bestimmten Aufbau und Motor zurück.

Aufruf

  • Methode: GET
  • URL: …/series/{series_id}/bodies/{body_id}/engines/{engine_id}/editions

Parameter

In der URL übergeben:

Parameter Beschreibung
series_id ID der Baureihe
body_id ID der Aufbauvariante
engine_id ID des Motors

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year Jahr der Erstzulassung Ja
month Monat der Erstzulassung

Rückgabe

Zurückgegeben wird ein Objekt mit einem Element, editions, welches wiederum aus Sondermodell-Objekten besteht, wobei die ID des Sondermodells als Key genutzt wird.

Eine Folge-URL wird nicht übergeben, da in der Baumstruktur keine weiteren Schritte notwendig sind, um ein Fahrzeug zu identifizieren.

Die Sondermodellobjekte bestehen aus folgenden Feldern:

Feld Typ Beschreibung
edition String Bezeichnung des Sondermodells
hsn String Herstellerschlüsselnummer
tsn_list Array Ungeordnetes Array aller Typschlüsselnummern des Sondermodells

Fehler

  • 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/series/1212/bodies/27/engines/11730/editions?year=2010&month=5
{
    "editions": {
        "55302": {
            "edition": "BlueMotion Comfortline",
            "hsn": "0603",
            "tsn_list": [
                "APW"
            ]
        },
        "55304": {
            "edition": "Comfortline",
            "hsn": "0603",
            "tsn_list": [
                "APW",
                "ASF"
            ]
        },
        ...
    },
}

Calculate

Beschreibung

Gibt zu einer angegebenen HSN und TSN entsprechende Preisschätzungen, Ausstattung und weitere Grundinformationen zurück. Da der Parameter free_text sehr lang werden kann, darf diese Funktion auch per POST abgerufen werden.

Leere Werte werden nicht zurückgegeben, damit können einzelne Elemente der Antwort, wie motor_name, color oder equipment_by_edition, mitunter scheinbar fehlen.

Aufruf

  • Methode: GET
  • URL: …/calculate/{hsn}/{tsn}

Parameter

In der URL übergeben:

Parameter Beschreibung
hsn Herstellerschlüsselnummer
tsn Typschlüsselnummer

Im Query-String übergeben:

Parameter Typ / Wertebereich Beschreibung Erforderlich?
year Integer Jahr der Erstzulassung Ja
month Integer Monat der Erstzulassung
mileage Integer Laufleistung in km
free_text String Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung Nein
model String Modellbezeichnung wie in GetModels. Nur notwendig, wenn mehrere Modelle mit gleicher HSN/TSN gefunden wurden
series String Baureihenbezeichnung nach GetSeries
edition String Sondermodellbezeichnung; die Schreibweise des Sondermodells ist der Funktion GetEditions zu entnehmen
equipment String Kommagetrennte Aufzählung der Ausstattungsmerkmale als Kürzel nach GetAllEquipment
color String Kurzbezeichnung der Farbe nach GetAllColors
body String Aufbau nach GetAllBodies
doors Integer Anzahl Türen
dealer_type -1 – 8 Unternehmensart
Wert Beschreibung
-1 Keine Angabe
0 kein Handel
1 Vertrags-Markenhändler
2 Freier Händler der Luxusklasse
3 Neuwagen- und Jahreswagenhändler
4 freier Händler
5 freier Händler, überwiegend Export
6 Gutachter / Makler
7 Steuerberater / Versicherung
8 Werkstatt mit kleinem Handel
dealer_price_range -1 – 7 durchschnittliche Preisklasse des Händlers.

Diese Einstellung ist wichtig, um korrekte spezifische Preise für einen individuellen Geschäftsbetrieb zu berechnen. Bitte geben Sie hier an, welche maximale Preisklasse an Kfz üblicherweise über Ihre Plattform gehandelt wird.

Wert Beschreibung
-1 Keine Angabe
0 kein Handel
1 0 – 5.000 Euro
2 5.000 – 10.000 Euro
3 10.000 – 15.000 Euro
4 15.000 – 20.000 Euro
5 20.000 – 30.000 Euro
6 30.000 – 40.000 Euro
7 über 40.000 Euro
stock_size -1 – 8 durchschnittlicher Fahrzeugbestand
Wert Beschreibung
-1 Keine Angabe
0 kein Handel
1 0 – 5
2 5 – 10
3 10 – 20
4 20 – 50
5 50 – 100
6 100 – 250
7 250 – 1.000
8 über 1.000
guarantees -1 – 4 üblicherweise angebotene Garantieleistungen
Wert Beschreibung
-1 Keine Angabe
0 kein Handel
1 Verkäufe überwiegend ohne Gewährleistung
2 Verkäufe mit Gewährleistung, ohne Garantie
3 Verkäufe mit Garantieversicherung
4 Verkäufe mit Garantieversicherung des Herstellers
average_standing_time 0 – 4 Standzeit in Monaten zur Berechnung der Verkaufswahrscheinlichkeiten in sales_probability
yearly_mileage Integer Jährliche Laufleistung in km zur Berechnung der Restwertprognose in degeneration
planned_usage_time Integer Geplante Nutzungsdauer in Jahren zur Berechnung der Restwertprognose in degeneration
return_all_editions 0 / 1 Default ist 0. Alle gefundenen Sondermodelle zurückgeben, wenn 1, ansonsten wird auf ein Basismodell verallgemeinert
use_production_tolerance 0 / 1 Default ist 0. Toleranzen um Produktionszeiträume beachten, wenn 1
pretty_print Beliebig Setzen, um die Ausgabe für Tests u.ä. zu formatieren

Rückgabe

Zurückgegeben wird eine Liste von Fahrzeug-Objekten, die jeweils aus den in folgender Tabelle erklärten Feldern bestehen.

Feld Typ Beschreibung
hsn String Herstellerschlüsselnummer
tsn String Typschlüsselnummer
brand String Marke
model String Modell
series String Baureihe
production_start String Produktionsstart der Baureihe im Format Monat/Jahr
edition String Sondermodell
body String Aufbauvariante
doors Integer Anzahl Türen
color String Optional. Farbe
engine String Beschreibung des Motors
engine_name String Optional. Herstellerspezifische Bezeichnung des Motors
fuel String Kraftstoff
kw Integer Leistung in Kilowatt (kW)
cubic_capacity Integer Hubraum in Kubikzentimeter (cm³ / ccm)
equipment_by_date Array Optional. Durch den Bauzeitraum definierte Grundausstattung
equipment_by_engine Array Optional. Durch die Motorisierung definierte Ausstattungsmerkmale
equipment_by_edition Array Optional. Durch das Sondermodell definierte Ausstattungsmerkmale
equipment Array Optional. Gesamtausstattung, die zur Preisberechnung beachtet wurde.Neben den Werten aus equipment_by_date, equipment_by_engine und equipment_by_edition werden hier insbesonderedie beachtete Gewährleistung oder Garantie und per equipment übergebene sowie im free_text erkannte Ausstattungen gelistet.
selling_price Integer Händlerverkaufspreis
buying_price Integer Händlereinkaufspreis
dealer_price_range Integer Zur Berechnung verwendete dealer_price_range. Details siehe Parameter
guarantee String Bezeichnung der zur Berechnung verwendeten Gewährleistung oder Garantie
estimated_standing_time Integer Geschätzte durchschnittliche Standzeit in Tagen beim berechneten Verkaufspreis
sales_probability Objekt Optional. Verkaufspreis–Verkaufswahrscheinlichkeit-Zuordnungen.Es werden dabei für Preise in 100€-Schritten um den Marktpreis die jeweiligen Verkaufswahrscheinlichkeiten berechnet.Die Wahrscheinlichkeit bezieht sich dabei auf die als average_standing_time übergebene Wartezeit.Beispiel: Wenn für average_standing_time 2 übergeben wurde, und sales_probability den Eintrag "3900": 66 enthält,liegt die Wahrscheinlichkeit für den Verkauf innerhalb von 2 Monaten bei einem Verkaufspreis von 3900 Euro bei 66%
degeneration Array Optional. Ein Objekt mit planned_usage_time*12 Einträgen, die jeweils den Restwert pro Monat ab dem aktuellen Monat angeben. Datenpunkt 0 entspricht dem Preis in selling_price.Wird berechnet, wenn planned_usage_time und yearly_mileage übergeben wurden

Fehler

  • 300 MULTIPLE_MODELS
  • 404 NO_DATA
  • 404 MODEL_NOT_FOUND
  • 404 SERIES_NOT_FOUND
  • 404 EDITION_NOT_FOUND
  • 404 NO_MATCHES

Details siehe oben.

Beispiel

GET /api/v2/calculate/0035/afs?pretty_print&mileage=20000&year=2010&month=10&doors=5&dealer_price_range=3
[
    {
        "hsn": "0035",
        "tsn": "afs",
        "brand": "Opel",
        "model": "Corsa",
        "series": "Modell ab 2006 (D)",
        "production_start": 2007,
        "edition": null,
        "body": "LIMOUSINE",
        "doors": 5,
        "color": null,
        "engine": "4-Zylinder DIESELMOTOR",
        "engine_name": null,
        "fuel": "DIESEL",
        "kw": 55,
        "cubic_capacity": 1248,
        "equipment_by_date": [
            "AIB",
            "BAB",
            ...
        ],
        "equipment_by_engine": [],
        "equipment_by_edition": [],
        "equipment": [
            "AIB",
            "BAB",
            ...
        ],
        "selling_price": 2345,
        "buying_price": 1234,
        "dealer_price_range": 3,
        "guarantee": "Mit Gewährleistung",
        "estimated_standing_time": 40,
        "sales_probability": null,
        "degeneration": null
    }
]
dokumentation_der_restful_api_version_2.txt · Zuletzt geändert: 2018-11-07 18:03 von admin