Benutzer-Werkzeuge

Webseiten-Werkzeuge


dokumentation_der_restful_api_version_2

Dies ist eine alte Version des Dokuments!


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):

<nowiki>"url": "...\/calculate\/7909\/aak?...&model={model}"</nowiki>

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
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/Yahr
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.1523355288.txt.gz · Zuletzt geändert: 2018-04-10 12:14 von admin