Hier werden die Unterschiede zwischen zwei Versionen angezeigt.
Nächste Überarbeitung | Vorhergehende Überarbeitung | ||
dokumentation_der_restful_api_version_2 [2017-01-18 16:02] Christian Erstellt, Kopie der Doku der REST v1 |
dokumentation_der_restful_api_version_2 [2022-05-18 14:13] (aktuell) admin [Calculate] |
||
---|---|---|---|
Zeile 1: | Zeile 1: | ||
+ | ====== Dokumentation der RESTful API Version 2 ====== | ||
+ | |||
Eine allgemeine Beschreibung der RESTful API finden Sie unter [[apis]]. | Eine allgemeine Beschreibung der RESTful API finden Sie unter [[apis]]. | ||
- | ====== Authentifizierung und Sicherheit ====== | + | ===== Authentifizierung und Sicherheit ===== |
Die Authentifizierung erfolgt per Basic-HTTP-Auth mit Nutzername und | Die Authentifizierung erfolgt per Basic-HTTP-Auth mit Nutzername und | ||
Zeile 9: | Zeile 12: | ||
Die Schnittstelle ist nur über HTTPS erreichbar. | Die Schnittstelle ist nur über HTTPS erreichbar. | ||
+ | Bei einem Authentifizierungsfehler wird ein Fehler mit Status 401 und Code "UNAUTHORIZED" zurückgegeben. | ||
- | ====== Datentypen, Encoding ====== | ||
+ | ===== Datentypen, Encoding ===== | ||
- | POST-Parameter werden mit dem MIME-Type <code>application/x-www-form-urlencoded</code> | ||
- | formatiert und mit <code>UTF-8</code> kodiert übergeben. | ||
- | Antworten werden als JSON (Mime-Type <code>application/json</code>) formatiert und | + | POST-Parameter werden mit dem MIME-Type ''application/x-www-form-urlencoded'' |
- | mit <code>UTF-8</code> kodiert übertragen. | + | formatiert und mit ''UTF-8'' kodiert übergeben. |
+ | Antworten werden als JSON (Mime-Type ''application/json'') formatiert und | ||
+ | mit ''UTF-8'' kodiert übertragen. | ||
- | ====== Verhalten im Fehlerfall ====== | + | 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 ===== | ||
- | * <code>300 Multiple Choices</code>: Mehrere Versionen der angeforderten Ressource verfügbar | + | ==== Genutzte HTTP-Statuscodes ==== |
- | * <code>301 Moved Permanently</code>: Zugriff ohne SSL mit Weiterleitung auf HTTPS | + | |
- | * <code>401 Unauthorized</code>: Authentifizierungsfehler | + | |
- | * <code>404 Not Found</code>: Resource nicht gefunden | + | |
- | * <code>405 Method Not Allowed</code>: Unzulässige HTTP-Methode | + | |
- | * <code>450 Rate Limit Exceeded</code>: Request-Limit wurde erreicht | + | |
- | * <code>451 Invalid Input</code>: Falsche oder fehlende Parameter | + | |
- | * <code>500 Internal Server Error</code>: Ein serverseitiger Fehler ist aufgetreten | + | |
- | * <code>503 Service Unavailable</code>: API ist auf Grund von Wartungsarbeiten temporär nicht erreichbar | + | |
- | ===== Aufbau einer Antwort ===== | + | 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 | ::: | | ||
- | * Root-Objekt | ||
- | * <code>"error"</code>-Objekt mit folgenden Elementen | ||
- | * <code>"status"</code>: Integer, entspricht HTTP-Status | ||
- | * <code>"code"</code>: Maschinenlesbare Bezeichnung des Fehlers | ||
- | * <code>"message"</code>: Beschreibung des Fehlers | ||
- | * <code>"invalid"</code>: Für 451, optional. Liste ungültiger Eingabeparameter | ||
- | * Beispiel: <code>["mileage", "fuel"]</code> | ||
- | * <code>"missing"</code>: Für 451, optional. Liste fehlender Eingabeparameter | ||
- | * Beispiel: <code>["year", "month"]</code> | ||
- | * <code>"options"</code>: Für 300: Assoziatives Array von Auswahlmöglichkeiten | ||
- | * Beispiel: <code>'model' => ['ModelA', 'ModelB']</code> | ||
- | * <code>"url"</code>: Für 300: URL-Template mit Platzhaltern für die in <code>options</code> gelisteten Möglichkeiten | ||
- | * Beispiel (gekürzt): <code>https://.../calculate/1234/abc?...&model={model}</code> | ||
- | ===== Beispiel ===== | + | ==== Format ==== |
- | <code>GET /brand/42 | + | | ''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 ==== | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET https://autofokus24.de/api/v2/calculate/7909/aak?pretty_print&mileage=1&year=2013&month=5 | ||
</code> | </code> | ||
- | <code>{ | + | |
+ | <code> | ||
+ | { | ||
"error": { | "error": { | ||
- | "status": 404, | + | "status": 300, |
- | "code": "BRAND_NOT_FOUND", | + | "code": "MULTIPLE_CHOICES", |
- | "message": "Marke nicht gefunden" | + | "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}" | ||
} | } | ||
</code> | </code> | ||
- | ====== URLs ====== | + | ===== URLs ===== |
- | ===== Allgemeines ===== | + | ==== Allgemeines ==== |
- | Prefix: <code>/api/v1</code> | + | Prefix: ''/api/v2'' |
Die folgenden URLs werden an den Prefix angehangen. Die zu verwendende HTTP-Methode zum Zugriff ist | Die folgenden URLs werden an den Prefix angehangen. Die zu verwendende HTTP-Methode zum Zugriff ist | ||
Zeile 84: | Zeile 111: | ||
Alle aufgelisteten Parameter müssen, wenn nicht anders angegeben, übergeben werden. | 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 ===== | ||
+ | ==== Übersicht und Abrechnung ==== | ||
- | Funktionen aus SoapServer2: | ||
- | * calcCar: <code>GET /calculate/{hsn}/{tsn}</code> (kostenpflichtig, wird gezählt und abgerechnet) | ||
- | * getColors: <code>GET /colors</code> | ||
- | * getFeatureList: <code>GET /features</code> | ||
- | Funktionen aus autofokus24Tree: | + | ^ Name^ Methode^ URL^ Rückgabe^ Abrechnung ^ |
- | * getMakes: <code>GET /brands</code> | + | | [[#GetAllColors]]| ''GET''| ''/colors''| Mögliche Farbcodes| | |
- | * getModels: <code>GET /brands/{brand_id}/models</code> | + | | [[#GetAllEquipment]]| ''GET''| ''/equipment''| Mögliche Ausstattungs-Kürzel | |
- | * getSubmodels: <code>GET /models/{model_id}/submodels</code> | + | | [[#GetAllBodies]]| ''GET''| ''/bodies''| Mögliche Aufbauvarianten | |
- | * getBuildtypes: <code>GET /submodels/{submodel_id}/bodies</code> | + | | [[#GetBrands]]| ''GET''| ''/brands''| Alle Marken | |
- | * getMotors: <code>GET /submodels/{submodel_id}/bodies/{body_id}/engines</code> (bedingt kostenpflichtig, falls kein Folgeaufruf von getFokusCodes erfolgt) | + | | [[#GetModels]]| ''GET''| ''/brands/{brand_id}/models''| Modelle einer Marke | |
- | * getFokuscodes: <code>GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions</code> (kostenpflichtig, wird gezählt und abgerechnet) | + | | [[#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 | | ||
- | Für eine spätere Version geplante Funktionen: | ||
- | * <code>GET /brands/{brand_id}</code> | ||
- | * <code>GET /models/{model_id}</code> | ||
- | * <code>GET /submodels/{submodel_id}</code> | ||
- | * <code>GET /submodels/{submodel_id}/bodies/{body_id}</code> | ||
- | * <code>GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}</code> | ||
- | * <code>GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions/{edition_id}</code> | ||
- | ===== GET /colors ===== | + | ==== GetAllColors ==== |
+ | === Beschreibung === | ||
- | ==== Beschreibung ==== | ||
+ | Gibt ein Objekt mit Kurzbezeichnung-Farbname-Zuordnungen zurück. Die Kürzel können in [[#Calculate]] verwendet werden. | ||
- | Gibt ein Objekt mit Kurzbezeichnung-Farbname-Zuordnungen zurück. | ||
+ | === Aufruf === | ||
- | ==== Beispiel ==== | ||
+ | * Methode: ''GET'' | ||
+ | * URL: ''…/colors'' | ||
- | <code>GET /api/v1/colors | + | |
+ | === Beispiel === | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET /api/v2/colors | ||
</code> | </code> | ||
- | <code>{ | + | |
+ | <code> | ||
+ | { | ||
"wht": "weiss", | "wht": "weiss", | ||
"red": "rot", | "red": "rot", | ||
Zeile 133: | Zeile 163: | ||
</code> | </code> | ||
- | ===== GET /features ===== | + | ==== GetAllEquipment ==== |
- | ==== Beschreibung ==== | + | === Beschreibung === |
Gibt ein Objekt mit Kurzbezeichnung-Featurename-Zuordnungen zurück. | Gibt ein Objekt mit Kurzbezeichnung-Featurename-Zuordnungen zurück. | ||
+ | Die Kürzel können in [[#Calculate]] verwendet werden. | ||
- | ==== Beispiel ==== | + | === Aufruf === |
- | <code>GET /api/v1/features | + | * Methode: ''GET'' |
+ | * URL: ''…/equipment'' | ||
+ | |||
+ | |||
+ | === Beispiel === | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET /api/v2/equipment | ||
</code> | </code> | ||
- | <code>{ | + | |
+ | <code> | ||
+ | { | ||
"GAS": "Gasantrieb", | "GAS": "Gasantrieb", | ||
"ELE": "Elektromotor", | "ELE": "Elektromotor", | ||
Zeile 156: | Zeile 197: | ||
</code> | </code> | ||
- | ===== GET /brands ===== | + | ==== GetAllBodies ==== |
+ | === Beschreibung === | ||
- | ==== 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 === | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET /api/v2/bodies | ||
+ | </code> | ||
+ | |||
+ | <code> | ||
+ | [ | ||
+ | "BUS", | ||
+ | "CABRIO", | ||
+ | "COUPE", | ||
+ | ... | ||
+ | ] | ||
+ | </code> | ||
+ | |||
+ | ==== GetBrands ==== | ||
+ | |||
+ | |||
+ | === Beschreibung === | ||
Zeile 166: | Zeile 239: | ||
- | ==== Beispiel ==== | + | === Aufruf === |
- | <code>GET /api/v1/brands | + | * 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 === | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET /api/v2/brands | ||
</code> | </code> | ||
- | <code>{ | + | |
+ | <code> | ||
+ | { | ||
"brands": { | "brands": { | ||
"1": "Alfa Romeo", | "1": "Alfa Romeo", | ||
Zeile 182: | Zeile 273: | ||
</code> | </code> | ||
- | ===== GET /brands/{brand_id}/models ===== | + | ==== GetModels ==== |
- | + | === Beschreibung === | |
- | ==== Beschreibung ==== | + | |
Zeile 193: | Zeile 283: | ||
- | ==== Parameter ==== | + | === Aufruf === |
+ | |||
+ | |||
+ | * Methode: ''GET'' | ||
+ | * URL: ''…/brands/{brand_id}/models'' | ||
+ | |||
+ | |||
+ | === Parameter === | ||
In der URL übergeben: | In der URL übergeben: | ||
- | * <code>brand_id</code>: ID der Marke | + | ^ Parameter^ Beschreibung ^ |
+ | | ''brand_id''| ID der Marke | | ||
Im Query-String übergeben: | Im Query-String übergeben: | ||
- | * <code>year</code>: Jahr der Erstzulassung | + | ^ Parameter^ Beschreibung^ Erforderlich? ^ |
- | * <code>month</code>: Monat der Erstzulassung | + | | ''year''| Jahr der Erstzulassung| Ja | |
+ | | ''month''| Monat der Erstzulassung | ::: | | ||
- | ==== Fehler ==== | ||
+ | === Rückgabe === | ||
- | * <code>404 BRAND_NOT_FOUND</code>: Marke nicht gefunden | ||
+ | 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 | ||
- | ==== Beispiel ==== | ||
+ | === Fehler === | ||
- | <code>GET /api/v1/brands/37/models?year=2015&month=5 | + | |
+ | * ''404 NO_DATA'' | ||
+ | |||
+ | [[#Verhalten_im_Fehlerfall|Details siehe oben]]. | ||
+ | |||
+ | |||
+ | === Beispiel === | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET /api/v2/brands/37/models?year=2015&month=5 | ||
</code> | </code> | ||
- | <code>{ | + | |
+ | <code> | ||
+ | { | ||
"models": { | "models": { | ||
"850": "Amarok", | "850": "Amarok", | ||
Zeile 224: | Zeile 338: | ||
... | ... | ||
}, | }, | ||
- | "submodels_url": "https://autofokus24.de/api/v1/models/{model_id}/submodels" | + | "series_url": "https://autofokus24.de/api/v2/models/{model_id}/series" |
} | } | ||
</code> | </code> | ||
- | ===== GET /models/{model_id}/submodels ===== | + | ==== GetSeries ==== |
- | + | === Beschreibung === | |
- | ==== Beschreibung ==== | + | |
Zeile 239: | Zeile 352: | ||
- | ==== Parameter ==== | + | === Aufruf === |
+ | |||
+ | |||
+ | * Methode: ''GET'' | ||
+ | * URL: ''…/models/{model_id}/series'' | ||
+ | |||
+ | |||
+ | === Parameter === | ||
In der URL übergeben: | In der URL übergeben: | ||
- | * <code>model_id</code>: ID des Modells | + | ^ Parameter^ Beschreibung ^ |
+ | | ''model_id''| ID des Modells | | ||
Im Query-String übergeben: | Im Query-String übergeben: | ||
- | * <code>year</code>: Jahr der Erstzulassung | + | ^ Parameter^ Beschreibung^ Erforderlich? ^ |
- | * <code>month</code>: Monat der Erstzulassung | + | | ''year''| Jahr der Erstzulassung| Ja | |
+ | | ''month''| Monat der Erstzulassung | ::: | | ||
- | ==== Fehler ==== | ||
+ | === Rückgabe === | ||
- | * <code>404 MODEL_NOT_FOUND</code>: Modell nicht gefunden | ||
+ | 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 | ||
- | ==== Beispiel ==== | ||
+ | === Fehler === | ||
- | <code>GET /api/v1/models/864/submodels?year=2015&month=5 | + | |
+ | * ''404 NO_DATA'' | ||
+ | |||
+ | [[#Verhalten_im_Fehlerfall|Details siehe oben]]. | ||
+ | |||
+ | |||
+ | === Beispiel === | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET /api/v2/models/864/series?year=2015&month=5 | ||
</code> | </code> | ||
- | <code>{ | + | |
- | "submodels": { | + | <code> |
+ | { | ||
+ | "series": { | ||
"1191": "Modell ab 2010", | "1191": "Modell ab 2010", | ||
"1192": "Modell ab 2008 (CC)", | "1192": "Modell ab 2008 (CC)", | ||
}, | }, | ||
- | "bodies_url": "https://autofokus24.de/api/v1/submodels/{submodel_id}/bodies" | + | "bodies_url": "https://autofokus24.de/api/v2/series/{series_id}/bodies" |
} | } | ||
</code> | </code> | ||
- | ===== GET /submodels/{submodel_id}/bodies ===== | + | ==== GetBodies ==== |
- | + | === Beschreibung === | |
- | ==== Beschreibung ==== | + | |
Zeile 282: | Zeile 418: | ||
- | ==== Parameter ==== | + | === Aufruf === |
+ | |||
+ | |||
+ | * Methode: ''GET'' | ||
+ | * URL: ''…/series/{series_id}/bodies'' | ||
+ | |||
+ | |||
+ | === Parameter === | ||
In der URL übergeben: | In der URL übergeben: | ||
- | * <code>submodel_id</code>: ID der Baureihe | + | ^ Parameter^ Beschreibung ^ |
+ | | ''series_id''| ID der Baureihe | | ||
Im Query-String übergeben: | Im Query-String übergeben: | ||
- | * <code>year</code>: Jahr der Erstzulassung | + | ^ Parameter^ Beschreibung^ Erforderlich? ^ |
- | * <code>month</code>: Monat der Erstzulassung | + | | ''year''| Jahr der Erstzulassung| Ja | |
+ | | ''month''| Monat der Erstzulassung | ::: | | ||
- | ==== Fehler ==== | ||
+ | === Rückgabe === | ||
- | * <code>404 SUBMODEL_NOT_FOUND</code>: Submodell nicht gefunden | ||
+ | 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 | ||
- | ==== Beispiel ==== | + | Die Aufbauobjekte bestehen aus folgenden Feldern: |
+ | ^ Feld^ Typ^ Beschreibung ^ | ||
+ | | ''body''| String| Bezeichnung des Aufbaus | | ||
+ | | ''doors''| Integer| Anzahl Türen | | ||
- | <code>GET /api/v1/submodels/1191/bodies?year=2015&month=5 | + | |
+ | |||
+ | === Fehler === | ||
+ | |||
+ | |||
+ | * ''404 NO_DATA'' | ||
+ | |||
+ | [[#Verhalten_im_Fehlerfall|Details siehe oben]]. | ||
+ | |||
+ | |||
+ | === Beispiel === | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET /api/v2/series/1191/bodies?year=2015&month=5 | ||
</code> | </code> | ||
- | <code>{ | + | |
+ | <code> | ||
+ | { | ||
"bodies": { | "bodies": { | ||
"42": { | "42": { | ||
Zeile 317: | Zeile 484: | ||
} | } | ||
}, | }, | ||
- | "engines_url": "https://autofokus24.de/api/v1/submodels/1191/bodies/{body_id}/engines" | + | "engines_url": "https://autofokus24.de/api/v2/series/1191/bodies/{body_id}/engines" |
} | } | ||
</code> | </code> | ||
- | ===== GET /submodels/{submodel_id}/bodies/{body_id}/engines ===== | + | ==== GetEngines ==== |
- | + | === Beschreibung === | |
- | ==== Beschreibung ==== | + | |
Zeile 332: | Zeile 498: | ||
- | ==== Parameter ==== | + | === Aufruf === |
+ | |||
+ | |||
+ | * Methode: ''GET'' | ||
+ | * URL: ''…/series/{series_id}/bodies/{body_id}/engines'' | ||
+ | |||
+ | |||
+ | === Parameter === | ||
In der URL übergeben: | In der URL übergeben: | ||
- | * <code>submodel_id</code>: ID der Baureihe | + | ^ Parameter^ Beschreibung ^ |
- | * <code>body_id</code>: ID der Aufbauvariante | + | | ''series_id''| ID der Baureihe | |
+ | | ''body_id''| ID der Aufbauvariante | | ||
Im Query-String übergeben: | Im Query-String übergeben: | ||
- | * <code>year</code>: Jahr der Erstzulassung | + | ^ Parameter^ Beschreibung^ Erforderlich? ^ |
- | * <code>month</code>: Monat der Erstzulassung | + | | ''year''| Jahr der Erstzulassung| Ja | |
+ | | ''month''| Monat der Erstzulassung | ::: | | ||
- | ==== Fehler ==== | ||
+ | === Rückgabe === | ||
- | * <code>404 SUBMODEL_NOT_FOUND</code>: Submodell nicht gefunden | ||
- | * <code>404 BODY_NOT_FOUND</code>: Aufbau nicht gefunden | ||
+ | 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 | ||
- | ==== Beispiel ==== | + | 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) | | ||
- | <code>GET /api/v1/submodels/1191/bodies/42/engines?year=2015&month=5 | + | |
+ | |||
+ | === Fehler === | ||
+ | |||
+ | |||
+ | * ''404 NO_DATA'' | ||
+ | |||
+ | [[#Verhalten_im_Fehlerfall|Details siehe oben]]. | ||
+ | |||
+ | |||
+ | === Beispiel === | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET /api/v2/series/1191/bodies/42/engines?year=2015&month=5 | ||
</code> | </code> | ||
- | <code>{ | + | |
+ | <code> | ||
+ | { | ||
"engines": { | "engines": { | ||
"6590": { | "6590": { | ||
"kw": "77", | "kw": "77", | ||
- | "ps": 105, | ||
"fuel": "DIESEL", | "fuel": "DIESEL", | ||
"cylinders": "4", | "cylinders": "4", | ||
Zeile 369: | Zeile 566: | ||
"9050": { | "9050": { | ||
"kw": "90", | "kw": "90", | ||
- | "ps": 122, | ||
"fuel": "BENZIN", | "fuel": "BENZIN", | ||
"cylinders": "4", | "cylinders": "4", | ||
Zeile 376: | Zeile 572: | ||
... | ... | ||
}, | }, | ||
- | "editions_url": "https://autofokus24.de/api/v1/submodels/1191/bodies/42/engines/{engine_id}/editions" | + | "editions_url": "https://autofokus24.de/api/v2/series/1191/bodies/42/engines/{engine_id}/editions" |
} | } | ||
</code> | </code> | ||
- | ===== GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions ===== | + | ==== GetEditions ==== |
+ | === Beschreibung === | ||
- | ==== Beschreibung ==== | ||
- | + | Gibt die Liste der verfügbaren Sondermodelle zu einem Modell in einer Baureihe mit einem | |
- | Gibt die Liste der verfügbaren Ausstattungsvarianten zu einem Modell in einer Baureihe mit einem | + | |
bestimmten Aufbau und Motor zurück. | bestimmten Aufbau und Motor zurück. | ||
- | ==== Parameter ==== | + | === Aufruf === |
+ | |||
+ | |||
+ | * Methode: ''GET'' | ||
+ | * URL: ''…/series/{series_id}/bodies/{body_id}/engines/{engine_id}/editions'' | ||
+ | |||
+ | |||
+ | === Parameter === | ||
In der URL übergeben: | In der URL übergeben: | ||
- | * <code>submodel_id</code>: ID der Baureihe | + | ^ Parameter^ Beschreibung ^ |
- | * <code>body_id</code>: ID der Aufbauvariante | + | | ''series_id''| ID der Baureihe | |
- | * <code>engine_id</code>: ID des Motors | + | | ''body_id''| ID der Aufbauvariante | |
+ | | ''engine_id''| ID des Motors | | ||
Im Query-String übergeben: | Im Query-String übergeben: | ||
- | * <code>year</code>: Jahr der Erstzulassung | + | ^ Parameter^ Beschreibung^ Erforderlich? ^ |
- | * <code>month</code>: Monat der Erstzulassung | + | | ''year''| Jahr der Erstzulassung| Ja | |
+ | | ''month''| Monat der Erstzulassung | ::: | | ||
- | ==== Fehler ==== | ||
+ | === Rückgabe === | ||
- | * <code>404 SUBMODEL_NOT_FOUND</code>: Submodell nicht gefunden | ||
- | * <code>404 BODY_NOT_FOUND</code>: Aufbau nicht gefunden | ||
- | * <code>404 ENGINE_NOT_FOUND</code>: Motor nicht gefunden | ||
+ | Zurückgegeben wird ein Objekt mit einem Element, ''editions'', welches wiederum aus Sondermodell-Objekten besteht, wobei die ID des Sondermodells als Key genutzt wird. | ||
- | ==== Beispiel ==== | + | 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: | ||
- | <code>GET /api/v1/submodels/1191/bodies/42/engines/6590/editions?year=2015&month=5 | + | ^ 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'' | ||
+ | |||
+ | [[#Verhalten_im_Fehlerfall|Details siehe oben]]. | ||
+ | |||
+ | |||
+ | === Beispiel === | ||
+ | |||
+ | |||
+ | <code> | ||
+ | GET /api/v2/series/1212/bodies/27/engines/11730/editions?year=2010&month=5 | ||
</code> | </code> | ||
- | <code>{ | + | |
+ | <code> | ||
+ | { | ||
"editions": { | "editions": { | ||
- | "84795": { | + | "55302": { |
- | "edition": "BlueMotion", | + | "edition": "BlueMotion Comfortline", |
"hsn": "0603", | "hsn": "0603", | ||
- | "tsn": "AQH", | + | "tsn_list": [ |
- | "other_tsns": [] | + | "APW" |
+ | ] | ||
}, | }, | ||
- | "85195": { | + | "55304": { |
- | "edition": "Business Edition", | + | "edition": "Comfortline", |
"hsn": "0603", | "hsn": "0603", | ||
- | "tsn": "AYF", | + | "tsn_list": [ |
- | "other_tsns": [] | + | "APW", |
+ | "ASF" | ||
+ | ] | ||
}, | }, | ||
... | ... | ||
Zeile 438: | Zeile 666: | ||
</code> | </code> | ||
- | ===== GET /calculate/{hsn}/{tsn} ===== | + | ==== Calculate ==== |
- | ==== Beschreibung ==== | + | === Beschreibung === |
Gibt zu einer angegebenen HSN und TSN entsprechende Preisschätzungen, Ausstattung und weitere | Gibt zu einer angegebenen HSN und TSN entsprechende Preisschätzungen, Ausstattung und weitere | ||
- | Grundinformationen zurück. Da der Parameter <code>free_text</code> sehr lang werden kann, darf diese Funktion | + | Grundinformationen zurück. Da der Parameter ''free_text'' sehr lang werden kann, darf diese Funktion |
- | auch per <code>POST</code> abgerufen werden. | + | 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. | ||
- | ==== Parameter ==== | ||
+ | === Aufruf === | ||
+ | |||
+ | |||
+ | * Methode: ''GET'' | ||
+ | * URL: ''…/calculate/{hsn}/{tsn}'' | ||
+ | |||
+ | |||
+ | === Parameter === | ||
- | Eine ausführlichere Beschreibung der Parameter findet sich in der | ||
- | Dokumentation der entsprechenden SOAP-Schnittstelle unter: | ||
- | http://wiki.autofokus24.de/index.php/Dokumentation_der_SOAP_Schnittstelle_Version_2#calcCar | ||
In der URL übergeben: | In der URL übergeben: | ||
- | * <code>hsn</code>: Herstellerschlüsselnummer | + | ^ Parameter^ Beschreibung ^ |
- | * <code>tsn</code>: Typschlüsselnummer | + | | ''hsn''| Herstellerschlüsselnummer | |
+ | | ''tsn''| Typschlüsselnummer | | ||
Im Query-String übergeben: | Im Query-String übergeben: | ||
- | * <code>year</code>: Jahr der Erstzulassung | + | {| |
- | * <code>month</code>: Monat der Erstzulassung | + | |- |
- | * <code>mileage</code>: Laufleistung in km, ehemals <code>miles</code> | + | ! Parameter !! Typ / Wertebereich !! Beschreibung !! Erforderlich? |
- | * Optionale Parameter: | + | |- |
- | * <code>free_text</code>: Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung, ehemals <code>fuzzyText</code> | + | | ''year'' || Integer || Jahr der Erstzulassung ||rowspan="3"| Ja |
- | * <code>model</code>: Modellbezeichnung | + | |- |
- | * <code>edition</code>: Ausstattungsvariante / Sondermodell, ehemals <code>specialModel</code>; die Schreibweise des Sondermodells ist der Funktion <code>.../editions</code> zu entnehmen | + | | ''month'' || Integer || Monat der Erstzulassung |
- | * <code>equipment</code>: Aufzählung der Ausstattungsmerkmale, ehemals <code>featureList</code> | + | |- |
- | * <code>color</code>: Kurzbezeichnung der Farbe | + | | ''mileage'' || Integer || Laufleistung in km |
- | * <code>power</code>: Motorleistung in KW | + | |- |
- | * <code>fuel</code>: Kraftstoff | + | | ''free_text'' || String || Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung ||rowspan="18"| Nein |
- | * <code>body</code>: Aufbau, ehemals <code>buildType</code> | + | |- |
- | * <code>doors</code>: Anzahl Türen, ehemals <code>doorCount</code> | + | | ''model'' || String || Modellbezeichnung wie in [[#GetModels]]. Nur notwendig, wenn mehrere Modelle mit gleicher HSN/TSN gefunden wurden |
- | * <code>dealer_type</code>: Unternehmensart, ehemals <code>dealerSize</code> | + | |- |
- | * <code>price_range</code>: durchschnittliche Preisklasse des Händlers, ehemals <code>priceClass</code> | + | | ''series'' || String || Baureihenbezeichnung nach [[#GetSeries]] |
- | * <code>stock_size</code>: durchschnittlicher Fahrzeugbestand, ehemals <code>carVolume</code> | + | |- |
- | * <code>guarantees</code>: üblicherweise angebotene Garantieleistungen, ehemals <code>garantieValue</code> | + | | ''edition'' || String || Sondermodellbezeichnung; die Schreibweise des Sondermodells ist der Funktion [[#GetEditions]] zu entnehmen |
- | * <code>idle_time</code>: Standzeit zur Berechnung der Verkaufswahrscheinlichkeiten in <code>sales_probability</code>, ehemals <code>monthWaitForSell</code> | + | |- |
- | * <code>yearly_mileage</code>: Jährliche Laufleistung in km zur Berechnung der Restwertprognose in <code>degeneration</code>, ehemals <code>milesPerYear</code> | + | | ''equipment'' || String || Kommagetrennte Aufzählung der Ausstattungsmerkmale als Kürzel nach [[#GetAllEquipment]] |
- | * <code>estimated_life</code>: Geplante Nutzungsdauer in Jahren zur Berechnung der Restwertprognose in <code>degeneration</code>, ehemals <code>usageYearCount</code> | + | |- |
+ | | ''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 | ||
+ | |} | ||
- | ==== Fehler ==== | + | |- |
+ | | ''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. | ||
- | * <code>300 MULTIPLE_MODELS</code>: Mehrere zutreffende Modelle gefunden | + | {| |
- | * <code>404 NOT_FOUND</code>: HSN oder TSN nicht gefunden | + | |- |
- | * <code>404 NOT_FOUND_IN_TIMESPAN</code>: HSN oder TSN im angegebenen Zeitraum nicht gefunden | + | ! 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 | ||
+ | |} | ||
- | Für letzteren Fehler werden ein oder zwei zusätzliche Felder zurückgegeben: | + | |- |
- | <code>build_since</code> und <code>build_until</code>. Beispiel: | + | | ''stock_size'' || -1 – 8 || durchschnittlicher Fahrzeugbestand |
- | <code>{ | + | {| |
- | "error": { | + | |- |
- | "status": 404, | + | ! Wert !! Beschreibung |
- | "code": "NOT_FOUND_IN_TIMESPAN", | + | |- |
- | "message": "HSN\/TSN (1234/ABC) was not build in the given time span." | + | | -1 || Keine Angabe |
- | }, | + | |- |
- | "build_since": "3/2012", | + | | 0 || kein Handel |
- | "build_until": "8/2014" | + | |- |
- | } | + | | 1 || 0 – 5 |
- | </code> | + | |- |
+ | | 2 || 5 – 10 | ||
+ | |- | ||
+ | | 3 || 10 – 20 | ||
+ | |- | ||
+ | | 4 || 20 – 50 | ||
+ | |- | ||
+ | | 5 || 50 – 100 | ||
+ | |- | ||
+ | | 6 || 100 – 250 | ||
+ | |- | ||
+ | | 7 || 250 – 1.000 | ||
+ | |- | ||
+ | | 8 || über 1.000 | ||
+ | |} | ||
- | ==== Beispiel ==== | + | |- |
+ | | ''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 | ||
+ | |- | ||
+ | | ''ignore_missing_estimation'' || 0 / 1 || Default ist 0. Liefert auch Kfz-Daten, wenn keine Schätzung möglich ist, 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. | | ||
+ | | ''optional_equipment''| Array| //Optional//. Mögliche weitere Ausstattungsmerkmale, welche sich gemäß der Autofokus24-Schätzung statistisch relevant auf den Fahrzeugwert auswirken (Analog zu "Weitere Ausstattung" auf der Autofokus24-Website). | | ||
+ | | ''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'' | ||
+ | |||
+ | [[#Verhalten_im_Fehlerfall|Details siehe oben]]. | ||
+ | |||
+ | |||
+ | === Beispiel === | ||
- | <code>GET /api/v1/calculate/0603/aqh?year=2015&month=5&mileage=10000&idle_time=2&color=wht | + | <code> |
+ | GET /api/v2/calculate/0035/afs?pretty_print&mileage=20000&year=2010&month=10&doors=5&dealer_price_range=3 | ||
</code> | </code> | ||
- | <code>[ | + | |
+ | <code> | ||
+ | [ | ||
{ | { | ||
- | "hsn": "0603", | + | "hsn": "0035", |
- | "tsn": "AQH", | + | "tsn": "afs", |
- | "brand": "VW", # Ehemals "make" | + | "brand": "Opel", |
- | "model": "Passat", | + | "model": "Corsa", |
- | "submodel": "Modell ab 2010", # Ehemals "submodelName" | + | "series": "Modell ab 2006 (D)", |
- | "body": "KOMBI", # Ersetzt "buildKind" als Integer | + | "production_start": 2007, |
- | "edition": "BlueMotion", # Ersetzt "specialModel" | + | "edition": null, |
- | "kw": 77, # Ehemals "power" | + | "body": "LIMOUSINE", |
- | "fuel": "DIESEL", # Ersetzt "fuel" als ID | + | "doors": 5, |
- | "color": "wht", | + | "color": null, |
+ | "engine": "4-Zylinder DIESELMOTOR", | ||
+ | "engine_name": null, | ||
+ | "fuel": "DIESEL", | ||
+ | "kw": 55, | ||
+ | "cubic_capacity": 1248, | ||
"equipment_by_date": [ | "equipment_by_date": [ | ||
- | "KLI", | ||
"AIB", | "AIB", | ||
"BAB", | "BAB", | ||
... | ... | ||
- | ], # Ehemals "extrasByDate" | + | ], |
- | "equipment_by_engine": [ | + | "equipment_by_engine": [], |
- | "BC", | + | "equipment_by_edition": [], |
- | "PF", | + | "equipment": [ |
- | "SEG", | + | "AIB", |
- | ... | + | "BAB", |
- | ], # Ehemals "extrasByMotor" | + | |
- | "equipment_by_edition": [ | + | |
- | "BREMSENERGIE" | + | |
- | ], # Ehemals "extrasBySpecialModel" | + | |
- | "optional_equipment": [ | + | |
- | "OGEW", | + | |
- | "BRT", | + | |
- | "LED", | + | |
- | ... | + | |
- | ], # Ehemals "significantExtras" | + | |
- | "selling_price": 19919, # Ehemals "price" | + | |
- | "buying_price": 16508, # Ehemals "priceEK" | + | |
- | "avg_idle_time": 60, # Ehemals "avgSellingTimeAtPrice" | + | |
- | "sales_probability": { | + | |
- | "18750": 77, | + | |
- | "19000": 73, | + | |
- | "19250": 68, | + | |
... | ... | ||
- | }, # Ehemals "avgSellingTimes" | + | ], |
- | "degeneration": [ | + | "selling_price": 2345, |
- | 19655, | + | "buying_price": 1234, |
- | 19343, | + | "dealer_price_range": 3, |
- | 19035, | + | "guarantee": "Mit Gewährleistung", |
- | ... | + | "estimated_standing_time": 40, |
- | ] | + | "sales_probability": null, |
- | }, | + | "degeneration": null |
- | ... | + | } |
- | </code> ] | + | ] |
+ | </code> | ||