Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- dokumentation_der_restful_api_version_2 [2017-01-19 23:32]
Christian ...
+++ 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]].
-====== Authentifizierung und Sicherheit ======
+===== Authentifizierung und Sicherheit =====
@@ Zeile 13: / Zeile 15: @@
-====== Datentypen, Encoding ======
+===== Datentypen, Encoding =====
-POST-Parameter werden mit dem MIME-Type <code>application/x-www-form-urlencoded</code>
+POST-Parameter werden mit dem MIME-Type ''application/x-www-form-urlencoded''
-formatiert und mit <code>UTF-8</code> kodiert übergeben.
+formatiert und mit ''UTF-8'' kodiert übergeben.
-Antworten werden als JSON (Mime-Type <code>application/json</code>) formatiert und
+Antworten werden als JSON (Mime-Type ''application/json'') formatiert und
-mit <code>UTF-8</code> kodiert übertragen.
+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 ======
+===== Verhalten im Fehlerfall =====
-===== Genutzte HTTP-Statuscodes =====
+==== Genutzte HTTP-Statuscodes ====
-Hinweis: Der <code>code</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 <code>301 Moved Permanently</code> und einer Weiterleitung zu HTTPS beantwortet werden.
-^ HTTP-Status/ <code>status</code>^ HTTP-Status Name^ <code>code</code>^ Beschreibung^ Verwendung |
+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 |
@@ Zeile 38: / Zeile 43: @@
 | 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]] |
+| ::: | ::: | NO_DATA| Keine Modelle gefunden| [[#GetModels]] |
-| Keine Baureihen gefunden| [[#GetSeries]] |
+| ::: | ::: | ::: | Keine Baureihen gefunden| [[#GetSeries]] |
-| Keine Aufbauten gefunden| [[#GetBodies]] |
+| ::: | ::: | ::: | Keine Aufbauten gefunden| [[#GetBodies]] |
-| Keine Motoren gefunden| [[#GetEngines]] |
+| ::: | ::: | ::: | Keine Motoren gefunden| [[#GetEngines]] |
-| Keine Sondermodelle gefunden| [[#GetEditions]] |
+| ::: | ::: | ::: | Keine Sondermodelle gefunden| [[#GetEditions]] |
-| HSN/TSN nicht gefunden| [[#Calculate]] |
+| ::: | ::: | ::: | HSN/TSN nicht gefunden| [[#Calculate]] |
-| MODEL_NOT_FOUND| HSN/TSN gefunden, aber keine Treffer durch Angabe des Modells |
+| ::: | ::: | NO_ESTIMATION_DATA| HSN/TSN kann nicht geschätzt werden | ::: |
-| SERIES_NOT_FOUND| HSN/TSN gefunden, aber keine Treffer durch Angabe der Baureihe |
+| ::: | ::: | MODEL_NOT_FOUND| HSN/TSN gefunden, aber keine Treffer durch Angabe des Modells | ::: |
-| EDITION_NOT_FOUND| HSN/TSN gefunden, aber keine Treffer durch Angabe des Sondermodells |
+| ::: | ::: | SERIES_NOT_FOUND| HSN/TSN gefunden, aber keine Treffer durch Angabe der Baureihe | ::: |
-| NO_MATCHES| HSN/TSN gefunden, aber keine Treffer zum gewünschten Zeitpunkt oder durch Angabe von Aufbau oder Türen |
+| ::: | ::: | 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 |
+| 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 <code>message</code> gegeben |
+| 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 |
+| 503| Service Unavailable| SERVICE_UNAVAILABLE| API ist auf Grund von Wartungsarbeiten o.ä. temporär nicht erreichbar | ::: |
-===== Format =====
+==== Format ====
-| <code>error</code> (Objekt)| <code>status</code>| Integer, entspricht dem HTTP-Status |
+| ''error'' (Objekt)| ''status''| Integer, entspricht dem HTTP-Status |
-| <code>code</code>| Maschinenlesbare Bezeichnung des Fehlers |
+| ::: | ''code''| Maschinenlesbare Bezeichnung des Fehlers |
-| <code>message</code>| Beschreibung des Fehlers. Diese kann sich ohne Ankündigung ändern und sollte nicht zur automatisierten Auswertung herangezogen werden |
+| ::: | ''message''| Beschreibung des Fehlers. Diese kann sich ohne Ankündigung ändern und sollte nicht zur automatisierten Auswertung herangezogen werden |
-| <code>invalid</code>| Für Status 400 (Bad Request): Liste ungültiger Eingabeparameter.Beispiel: <code>"invalid":["year","month"]</code> |
+| ::: | ''invalid''| Für Status 400 (Bad Request): Liste ungültiger Eingabeparameter.Beispiel: ''"invalid":["year","month"]'' |
-| <code>missing</code>| Für Status 400 (Bad Request): Liste fehlender Eingabeparameter.Beispiel: <code>"missing":["year","month"]</code> |
+| ::: | ''missing''| Für Status 400 (Bad Request): Liste fehlender Eingabeparameter.Beispiel: ''"missing":["year","month"]'' |
-| <code>options</code>| Für Status 300 (Multiple Choices): Objekt mit Auswahlmöglichkeiten.Beispiel: <code>"options":{"model":["X5","X6"]}]</code> |
+| ::: | ''options''| Für Status 300 (Multiple Choices): Objekt mit Auswahlmöglichkeiten.Beispiel: ''"options":{"model":["X5","X6"]}]'' |
-| <code>url</code>| Für Status 300 (Multiple Choices): URL-Template mit Platzhaltern für die in <code>options</code> gelisteten Möglichkeiten.Beispiel (gekürzt): <code><nowiki>"url": "...\/calculate\/7909\/aak?...&model={model}"</nowiki></code> |
+| ::: | ''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 ====
-===== Beispiel =====
+<code>
-<code>GET https://autofokus24.de/api/v2/calculate/7909/aak?pretty_print&mileage=1&year=2013&month=5
+GET https://autofokus24.de/api/v2/calculate/7909/aak?pretty_print&mileage=1&year=2013&month=5
 </code>
-<code>{
+<code>
+{
     "error": {
         "status": 300,
@@ Zeile 89: / Zeile 97: @@
 </code>
-====== URLs ======
+===== URLs =====
-===== Allgemeines =====
+==== Allgemeines ====
-Prefix: <code>/api/v2</code>
+Prefix: ''/api/v2''
 Die folgenden URLs werden an den Prefix angehangen. Die zu verwendende HTTP-Methode zum Zugriff ist
@@ Zeile 103: / Zeile 111: @@
 Alle aufgelisteten Parameter müssen, wenn nicht anders angegeben, übergeben werden.
-Zusätzlich existiert für jede URI der Parameter <code>pretty_print</code>. Wird er mit übergeben, wird die Ausgabe serverseitig zur besseren Lesbarkeit formatiert. Der Wert des Parameters wird ignoriert.
+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 =====
+==== Übersicht und Abrechnung ====
-^ Name^ Methode^ URL^ Rückgabe^ Abrechnung |
+^ Name^ Methode^ URL^ Rückgabe^ Abrechnung ^
-| [[#GetAllColors]]| <code>GET</code>| <code>/colors</code>| Mögliche Farbcodes|  |
+| [[#GetAllColors]]| ''GET''| ''/colors''| Mögliche Farbcodes|  |
-| [[#GetAllEquipment]]| <code>GET</code>| <code>/equipment</code>| Mögliche Ausstattungs-Kürzel |
+| [[#GetAllEquipment]]| ''GET''| ''/equipment''| Mögliche Ausstattungs-Kürzel |
-| [[#GetAllBodies]]| <code>GET</code>| <code>/bodies</code>| Mögliche Aufbauvarianten |
+| [[#GetAllBodies]]| ''GET''| ''/bodies''| Mögliche Aufbauvarianten |
-| [[#GetBrands]]| <code>GET</code>| <code>/brands</code>| Alle Marken |
+| [[#GetBrands]]| ''GET''| ''/brands''| Alle Marken |
-| [[#GetModels]]| <code>GET</code>| <code>/brands/{brand_id}/models</code>| Modelle einer Marke |
+| [[#GetModels]]| ''GET''| ''/brands/{brand_id}/models''| Modelle einer Marke |
-| [[#GetSeries]]| <code>GET</code>| <code>/models/{model_id}/series</code>| Baureihen eines Modells |
+| [[#GetSeries]]| ''GET''| ''/models/{model_id}/series''| Baureihen eines Modells |
-| [[#GetBodies]]| <code>GET</code>| <code>/series/{series_id}/bodies</code>| Aufbauten einer Baureihe |
+| [[#GetBodies]]| ''GET''| ''/series/{series_id}/bodies''| Aufbauten einer Baureihe |
-| [[#GetEngines]]| <code>GET</code>| <code>/series/{series_id}/bodies/{body_id}/engines</code>| Motoren zur aktuellen Auswahl| Nur kostenpflichtig, falls kein Folgeaufruf von GetEditions erfolgt |
+| [[#GetEngines]]| ''GET''| ''/series/{series_id}/bodies/{body_id}/engines''| Motoren zur aktuellen Auswahl| Nur kostenpflichtig, falls kein Folgeaufruf von GetEditions erfolgt |
-| [[#GetEditions]]| <code>GET</code>| <code>/series/{series_id}/bodies/{body_id}/engines/{engine_id}/editions</code>| Sondermodelle und HSN/TSNs zur aktuellen Auswahl| Kostenpflichtig, wird gezählt und abgerechnet |
+| [[#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]]| <code>GET</code>, <code>POST</code>| <code>/calculate/{hsn}/{tsn}</code>| Fahrzeugbewertung |
+| [[#Calculate]]| ''GET'', ''POST''| ''/calculate/{hsn}/{tsn}''| Fahrzeugbewertung |
-===== GetAllColors =====
+==== 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 ===
-==== Aufruf ====
+  *  Methode: ''GET''
+  *  URL: ''…/colors''
-  *  Methode: <code>GET</code>
-  *  URL: <code>…/colors</code>
+=== Beispiel ===
-==== Beispiel ====
+<code>
+GET /api/v2/colors
+</code>
-<code>GET /api/v2/colors
+<code>
-</code>
+{
-<code>{
     "wht": "weiss",
     "red": "rot",
@@ Zeile 153: / Zeile 163: @@
 </code>
-===== GetAllEquipment =====
+==== GetAllEquipment ====
-==== Beschreibung ====
+=== Beschreibung ===
 Gibt ein Objekt mit Kurzbezeichnung-Featurename-Zuordnungen zurück.
+Die Kürzel können in [[#Calculate]] verwendet werden.
-==== Aufruf ====
+=== Aufruf ===
-  *  Methode: <code>GET</code>
+  *  Methode: ''GET''
-  *  URL: <code>…/equipment</code>
+  *  URL: ''…/equipment''
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v2/equipment
+<code>
+GET /api/v2/equipment
 </code>
-<code>{
+<code>
+{
     "GAS": "Gasantrieb",
     "ELE": "Elektromotor",
@@ Zeile 183: / Zeile 197: @@
 </code>
-===== GetAllBodies =====
+==== GetAllBodies ====
+=== Beschreibung ===
-==== Beschreibung ====
 Gibt ein Array aller verfügbaren Aufbauvarianten zurück.
+Die Kürzel können in [[#Calculate]] verwendet werden.
-==== Aufruf ====
+=== Aufruf ===
-  *  Methode: <code>GET</code>
+  *  Methode: ''GET''
-  *  URL: <code>…/bodies</code>
+  *  URL: ''…/bodies''
-==== Beispiel ====
+=== Beispiel ===
-<code>GET /api/v2/bodies
+<code>
+GET /api/v2/bodies
 </code>
-<code>[
+<code>
+[
     "BUS",
     "CABRIO",
@@ Zeile 213: / Zeile 230: @@
 </code>
-===== GetBrands =====
+==== GetBrands ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 223: / Zeile 239: @@
-==== Aufruf ====
+=== Aufruf ===
-  *  Methode: <code>GET</code>
+  *  Methode: ''GET''
-  *  URL: <code>…/brands</code>
+  *  URL: ''…/brands''
-==== Beispiel ====
+=== Rückgabe ===
-<code>GET /api/v2/brands
+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>
+{
     "brands": {
         "1": "Alfa Romeo",
@@ Zeile 246: / Zeile 273: @@
 </code>
-===== GetModels =====
+==== GetModels ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 257: / Zeile 283: @@
-==== Aufruf ====
+=== Aufruf ===
-  *  Methode: <code>GET</code>
+  *  Methode: ''GET''
-  *  URL: <code>…/brands/{brand_id}/models</code>
+  *  URL: ''…/brands/{brand_id}/models''
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-^ Parameter^ Beschreibung |
+^ Parameter^ Beschreibung ^
-| <code>brand_id</code>| ID der Marke |
+| ''brand_id''| ID der Marke |
 Im Query-String übergeben:
-^ Parameter^ Beschreibung^ Erforderlich? |
+^ Parameter^ Beschreibung^ Erforderlich? ^
-| <code>year</code>| Jahr der Erstzulassung| Ja |
+| ''year''| Jahr der Erstzulassung| Ja |
-| <code>month</code>| Monat der Erstzulassung |
+| ''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/v2/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>
+{
     "models": {
         "850": "Amarok",
@@ Zeile 303: / Zeile 342: @@
 </code>
-===== GetSeries =====
+==== GetSeries ====
-==== Beschreibung ====
+=== Beschreibung ===
@@ Zeile 314: / Zeile 352: @@
-==== Aufruf ====
+=== Aufruf ===
-  *  Methode: <code>GET</code>
+  *  Methode: ''GET''
-  *  URL: <code>…/models/{model_id}/series</code>
+  *  URL: ''…/models/{model_id}/series''
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-^ Parameter^ Beschreibung |
+^ Parameter^ Beschreibung ^
-| <code>model_id</code>| ID des Modells |
+| ''model_id''| ID des Modells |
 Im Query-String übergeben:
-^ Parameter^ Beschreibung^ Erforderlich? |
+^ Parameter^ Beschreibung^ Erforderlich? ^
-| <code>year</code>| Jahr der Erstzulassung| Ja |
+| ''year''| Jahr der Erstzulassung| Ja |
-| <code>month</code>| Monat der Erstzulassung |
+| ''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/v2/models/864/series?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>
+{
     "series": {
         "1191": "Modell ab 2010",
@@ Zeile 358: / Zeile 409: @@
 </code>
-===== GetBodies =====
+==== GetBodies ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 368: / Zeile 418: @@
-==== Aufruf ====
+=== Aufruf ===
-  *  Methode: <code>GET</code>
+  *  Methode: ''GET''
-  *  URL: <code>…/series/{series_id}/bodies</code>
+  *  URL: ''…/series/{series_id}/bodies''
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-^ Parameter^ Beschreibung |
+^ Parameter^ Beschreibung ^
-| <code>series_id</code>| ID der Baureihe |
+| ''series_id''| ID der Baureihe |
 Im Query-String übergeben:
-^ Parameter^ Beschreibung^ Erforderlich? |
+^ Parameter^ Beschreibung^ Erforderlich? ^
-| <code>year</code>| Jahr der Erstzulassung| Ja |
+| ''year''| Jahr der Erstzulassung| Ja |
-| <code>month</code>| Monat der Erstzulassung |
+| ''month''| Monat der Erstzulassung | ::: |
-==== Fehler ====
+=== Rückgabe ===
-  *  <code>404 SERIES_NOT_FOUND</code>: Baureihe 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
+Die Aufbauobjekte bestehen aus folgenden Feldern:
-==== Beispiel ====
+^ Feld^ Typ^ Beschreibung ^
+| ''body''| String| Bezeichnung des Aufbaus |
+| ''doors''| Integer| Anzahl Türen |
-<code>GET /api/v2/series/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>
+{
     "bodies": {
         "42": {
@@ Zeile 418: / Zeile 488: @@
 </code>
-===== GetEngines =====
+==== GetEngines ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 429: / Zeile 498: @@
-==== Aufruf ====
+=== Aufruf ===
-  *  Methode: <code>GET</code>
+  *  Methode: ''GET''
-  *  URL: <code>…/series/{series_id}/bodies/{body_id}/engines</code>
+  *  URL: ''…/series/{series_id}/bodies/{body_id}/engines''
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-^ Parameter^ Beschreibung |
+^ Parameter^ Beschreibung ^
-| <code>series_id</code>| ID der Baureihe |
+| ''series_id''| ID der Baureihe |
-| <code>body_id</code>| ID der Aufbauvariante |
+| ''body_id''| ID der Aufbauvariante |
 Im Query-String übergeben:
-^ Parameter^ Beschreibung^ Erforderlich? |
+^ Parameter^ Beschreibung^ Erforderlich? ^
-| <code>year</code>| Jahr der Erstzulassung| Ja |
+| ''year''| Jahr der Erstzulassung| Ja |
-| <code>month</code>| Monat der Erstzulassung |
+| ''month''| Monat der Erstzulassung | ::: |
-==== Fehler ====
+=== Rückgabe ===
-  *  <code>404 SERIES_NOT_FOUND</code>: Baureihe nicht gefunden
+Zurückgegeben wird ein Objekt mit zwei Elementen:
-  *  <code>404 BODY_NOT_FOUND</code>: Aufbau nicht gefunden
+  *  ''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:
-==== Beispiel ====
+^ 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/v2/series/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>
+{
     "engines": {
         "6590": {
             "kw": "77",
-            "ps": 105,
             "fuel": "DIESEL",
             "cylinders": "4",
@@ Zeile 477: / Zeile 566: @@
         "9050": {
             "kw": "90",
-            "ps": 122,
             "fuel": "BENZIN",
             "cylinders": "4",
@@ Zeile 488: / Zeile 576: @@
 </code>
-===== GetEditions =====
+==== GetEditions ====
+=== Beschreibung ===
-==== Beschreibung ====
@@ Zeile 499: / Zeile 586: @@
-==== Aufruf ====
+=== Aufruf ===
-  *  Methode: <code>GET</code>
+  *  Methode: ''GET''
-  *  URL: <code>…/series/{series_id}/bodies/{body_id}/engines/{engine_id}/editions</code>
+  *  URL: ''…/series/{series_id}/bodies/{body_id}/engines/{engine_id}/editions''
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-^ Parameter^ Beschreibung |
+^ Parameter^ Beschreibung ^
-| <code>series_id</code>| ID der Baureihe |
+| ''series_id''| ID der Baureihe |
-| <code>body_id</code>| ID der Aufbauvariante |
+| ''body_id''| ID der Aufbauvariante |
-| <code>engine_id</code>| ID des Motors |
+| ''engine_id''| ID des Motors |
 Im Query-String übergeben:
-^ Parameter^ Beschreibung^ Erforderlich? |
+^ Parameter^ Beschreibung^ Erforderlich? ^
-| <code>year</code>| Jahr der Erstzulassung| Ja |
+| ''year''| Jahr der Erstzulassung| Ja |
-| <code>month</code>| Monat der Erstzulassung |
+| ''month''| Monat der Erstzulassung | ::: |
-==== Fehler ====
+=== Rückgabe ===
-  *  <code>404 SERIES_NOT_FOUND</code>: Baureihe 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.
-  *  <code>404 BODY_NOT_FOUND</code>: Aufbau nicht gefunden
-  *  <code>404 ENGINE_NOT_FOUND</code>: Motor nicht gefunden
+Eine Folge-URL wird nicht übergeben, da in der Baumstruktur keine weiteren Schritte notwendig sind, um ein Fahrzeug zu identifizieren.
-==== Beispiel ====
+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 |
-<code>GET /api/v2/series/1212/bodies/27/engines/11730/editions?year=2010&month=5
+=== 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>
+{
+    "editions": {
         "55302": {
             "edition": "BlueMotion Comfortline",
@@ Zeile 559: / Zeile 666: @@
 </code>
-===== Calculate =====
+==== Calculate ====
-==== Beschreibung ====
+=== Beschreibung ===
 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 <code>motor_name</code>, <code>color</code> oder <code>equipment_by_edition</code>, mitunter scheinbar fehlen.
+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 ====
+=== Aufruf ===
-  *  Methode: <code>GET</code>
+  *  Methode: ''GET''
-  *  URL: <code>…/calculate/{hsn}/{tsn}</code>
+  *  URL: ''…/calculate/{hsn}/{tsn}''
-==== Parameter ====
+=== Parameter ===
 In der URL übergeben:
-^ Parameter^ Beschreibung |
+^ Parameter^ Beschreibung ^
-| <code>hsn</code>| Herstellerschlüsselnummer |
+| ''hsn''| Herstellerschlüsselnummer |
-| <code>tsn</code>| Typschlüsselnummer |
+| ''tsn''| Typschlüsselnummer |
 Im Query-String übergeben:
-^ Parameter^ Beschreibung^ Erforderlich? |
+{|
-| <code>year</code>| Jahr der Erstzulassung| Ja |
+|-
-| <code>month</code>| Monat der Erstzulassung |
+! Parameter !! Typ / Wertebereich !! Beschreibung !! Erforderlich?
-| <code>mileage</code>| Laufleistung in km |
+|-
-| <code>free_text</code>| Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung| Nein |
+| ''year''         || Integer || Jahr der Erstzulassung ||rowspan="3"| Ja
-| <code>model</code>| Modellbezeichnung |
+|-
-| <code>series</code>| Baureihenbezeichnung |
+| ''month''        || Integer || Monat der Erstzulassung
-| <code>edition</code>| Sondermodellbezeichnung; die Schreibweise des Sondermodells ist der Funktion [[#GetEditions]] zu entnehmen |
+|-
-| <code>equipment</code>| Aufzählung der Ausstattungsmerkmale |
+| ''mileage''      || Integer || Laufleistung in km
-| <code>color</code>| Kurzbezeichnung der Farbe |
+|-
-| <code>power</code>| Motorleistung in KW |
+| ''free_text''    || String  || Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung ||rowspan="18"| Nein
-| <code>fuel</code>| Kraftstoff |
+|-
-| <code>body</code>| Aufbau |
+| ''model''        || String  || Modellbezeichnung wie in [[#GetModels]]. Nur notwendig, wenn mehrere Modelle mit gleicher HSN/TSN gefunden wurden
-| <code>doors</code>| Anzahl Türen |
+|-
-| <code>dealer_type</code>| Unternehmensart |
+| ''series''       || String  || Baureihenbezeichnung nach [[#GetSeries]]
-| <code>price_range</code>| durchschnittliche Preisklasse des Händlers |
+|-
-| <code>stock_size</code>| durchschnittlicher Fahrzeugbestand |
+| ''edition''      || String  || Sondermodellbezeichnung; die Schreibweise des Sondermodells ist der Funktion [[#GetEditions]] zu entnehmen
-| <code>guarantees</code>| üblicherweise angebotene Garantieleistungen |
+|-
-| <code>idle_time</code>| Standzeit zur Berechnung der Verkaufswahrscheinlichkeiten in <code>sales_probability</code> |
+| ''equipment''    || String  || Kommagetrennte Aufzählung der Ausstattungsmerkmale als Kürzel nach [[#GetAllEquipment]]
-| <code>yearly_mileage</code>| Jährliche Laufleistung in km zur Berechnung der Restwertprognose in <code>degeneration</code> |
+|-
-| <code>estimated_life</code>| Geplante Nutzungsdauer in Jahren zur Berechnung der Restwertprognose in <code>degeneration</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
+|}
+|-
+| ''dealer_price_range'' || -1 – 7 || durchschnittliche Preisklasse des Händlers.
-==== Fehler ====
+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
+|}
-  *  <code>300 MULTIPLE_MODELS</code>: Mehrere zutreffende Modelle gefunden
+|-
-  *  <code>404 NOT_FOUND</code>: HSN oder TSN nicht gefunden
+| ''stock_size''         || -1 – 8 || durchschnittlicher Fahrzeugbestand
-  *  <code>404 NOT_FOUND_IN_TIMESPAN</code>: HSN oder TSN im angegebenen Zeitraum nicht gefunden
-Für letzteren Fehler werden ein oder zwei zusätzliche Felder zurückgegeben:
+{|
-<code>build_since</code> und <code>build_until</code>. Beispiel:
+|-
+! 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
+|}
-<code>{
+|-
-    "error": {
+| ''guarantees''         || -1 – 4 || üblicherweise angebotene Garantieleistungen
-        "status": 404,
-        "code": "NOT_FOUND_IN_TIMESPAN",
-        "message": "HSN\/TSN (1234/ABC) was not build in the given time span."
-    },
-    "build_since": "3/2012",
-    "build_until": "8/2014"
-}
-</code>
-==== Beispiel ====
+{|
+|-
+! 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
+|}
-<code>GET /api/v2/calculate/0603/aqh?year=2015&month=5&mileage=10000&idle_time=2&color=wht
+=== 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/v2/calculate/0035/afs?pretty_print&mileage=20000&year=2010&month=10&doors=5&dealer_price_range=3
 </code>
-<code>[
+<code>
+[
     {
-        "hsn": "0603",
+        "hsn": "0035",
-        "tsn": "aqh",
+        "tsn": "afs",
-        "brand": "VW",
+        "brand": "Opel",
-        "model": "Passat",
+        "model": "Corsa",
-        "series": "Modell ab 2010",
+        "series": "Modell ab 2006 (D)",
-        "production_start": 2010,
+        "production_start": 2007,
-        "body": "KOMBI",
+        "edition": null,
+        "body": "LIMOUSINE",
         "doors": 5,
-        "color": "wht",
+        "color": null,
         "engine": "4-Zylinder DIESELMOTOR",
+        "engine_name": null,
         "fuel": "DIESEL",
-        "kw": 77,
+        "kw": 55,
+        "cubic_capacity": 1248,
         "equipment_by_date": [
-            "KLI",
             "AIB",
+            "BAB",
             ...
         ],
-        "equipment_by_engine": [
+        "equipment_by_engine": [],
-            "BC",
+        "equipment_by_edition": [],
-            "PF",
-            ...
-        ],
         "equipment": [
-            "KLI",
             "AIB",
+            "BAB",
             ...
         ],
-        "selling_price": 16777,
+        "selling_price": 2345,
-        "buying_price": 12497,
+        "buying_price": 1234,
-        "dealer_price_range": 4,
+        "dealer_price_range": 3,
-        "estimated_standing_time": 33
+        "guarantee": "Mit Gewährleistung",
+        "estimated_standing_time": 40,
+        "sales_probability": null,
+        "degeneration": null
     }
-</code> ]
+]
+</code>

Autofokus24 Wiki

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Unterschiede

Seiten-Werkzeuge