====== Dokumentation der RESTful API Version 1 ======
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.
===== 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.
===== Verhalten im Fehlerfall =====
==== Genutzte HTTP-Statuscodes ====
* ''300 Multiple Choices'': Mehrere Versionen der angeforderten Ressource verfügbar
* ''301 Moved Permanently'': Zugriff ohne SSL mit Weiterleitung auf HTTPS
* ''401 Unauthorized'': Authentifizierungsfehler
* ''404 Not Found'': Resource nicht gefunden
* ''405 Method Not Allowed'': Unzulässige HTTP-Methode
* ''450 Rate Limit Exceeded'': Request-Limit wurde erreicht
* ''451 Invalid Input'': Falsche oder fehlende Parameter
* ''500 Internal Server Error'': Ein serverseitiger Fehler ist aufgetreten
* ''503 Service Unavailable'': API ist auf Grund von Wartungsarbeiten temporär nicht erreichbar
==== Aufbau einer Antwort ====
* Root-Objekt
* ''"error"''-Objekt mit folgenden Elementen
* ''"status"'': Integer, entspricht HTTP-Status
* ''"code"'': Maschinenlesbare Bezeichnung des Fehlers
* ''"message"'': Beschreibung des Fehlers
* ''"invalid"'': Für 451, optional. Liste ungültiger Eingabeparameter
* Beispiel: ''["mileage", "fuel"]''
* ''"missing"'': Für 451, optional. Liste fehlender Eingabeparameter
* Beispiel: ''["year", "month"]''
* ''"options"'': Für 300: Assoziatives Array von Auswahlmöglichkeiten
* Beispiel: '''model' => ['ModelA', 'ModelB']''
* ''"url"'': Für 300: URL-Template mit Platzhaltern für die in ''options'' gelisteten Möglichkeiten
* Beispiel (gekürzt): ''https://.../calculate/1234/abc?...&model={model}''
==== Beispiel ====
GET /brand/42
{
"error": {
"status": 404,
"code": "BRAND_NOT_FOUND",
"message": "Marke nicht gefunden"
}
}
===== URLs =====
==== Allgemeines ====
Prefix: ''/api/v1''
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.
==== Übersicht ====
Funktionen aus SoapServer2:
* calcCar: ''GET /calculate/{hsn}/{tsn}'' (kostenpflichtig, wird gezählt und abgerechnet)
* getColors: ''GET /colors''
* getFeatureList: ''GET /features''
Funktionen aus autofokus24Tree:
* getMakes: ''GET /brands''
* getModels: ''GET /brands/{brand_id}/models''
* getSubmodels: ''GET /models/{model_id}/submodels''
* getBuildtypes: ''GET /submodels/{submodel_id}/bodies''
* getMotors: ''GET /submodels/{submodel_id}/bodies/{body_id}/engines'' (bedingt kostenpflichtig, falls kein Folgeaufruf von getFokusCodes erfolgt)
* getFokuscodes: ''GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions'' (kostenpflichtig, wird gezählt und abgerechnet)
Für eine spätere Version geplante Funktionen:
* ''GET /brands/{brand_id}''
* ''GET /models/{model_id}''
* ''GET /submodels/{submodel_id}''
* ''GET /submodels/{submodel_id}/bodies/{body_id}''
* ''GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}''
* ''GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions/{edition_id}''
==== GET /colors ====
=== Beschreibung ===
Gibt ein Objekt mit Kurzbezeichnung-Farbname-Zuordnungen zurück.
=== Beispiel ===
GET /api/v1/colors
{
"wht": "weiss",
"red": "rot",
"ora": "orange",
...
}
==== GET /features ====
=== Beschreibung ===
Gibt ein Objekt mit Kurzbezeichnung-Featurename-Zuordnungen zurück.
=== Beispiel ===
GET /api/v1/features
{
"GAS": "Gasantrieb",
"ELE": "Elektromotor",
"BHG": "behindertengerecht",
...
}
==== GET /brands ====
=== Beschreibung ===
Gibt die Liste bekannter Marken mit ihrer jeweiligen ID zurück.
=== Beispiel ===
GET /api/v1/brands
{
"brands": {
"1": "Alfa Romeo",
"57": "ALPINA",
"37": "VW",
...
},
"models_url": "https://autofokus24.de/api/v1/brands/{brand_id}/models",
}
==== GET /brands/{brand_id}/models ====
=== Beschreibung ===
Gibt die Liste der in einem bestimmten Zeitraum hergestellten Modelle zu einer angegebenen Marke
zurück.
=== Parameter ===
In der URL übergeben:
* ''brand_id'': ID der Marke
Im Query-String übergeben:
* ''year'': Jahr der Erstzulassung
* ''month'': Monat der Erstzulassung
=== Fehler ===
* ''404 BRAND_NOT_FOUND'': Marke nicht gefunden
=== Beispiel ===
GET /api/v1/brands/37/models?year=2015&month=5
{
"models": {
"850": "Amarok",
"851": "Bora",
"864": "Passat",
...
},
"submodels_url": "https://autofokus24.de/api/v1/models/{model_id}/submodels"
}
==== GET /models/{model_id}/submodels ====
=== Beschreibung ===
Gibt die Liste der in einem bestimmten Zeitraum hergestellten Baureihen zu einem angegebenen Modell
einer Marke zurück.
=== Parameter ===
In der URL übergeben:
* ''model_id'': ID des Modells
Im Query-String übergeben:
* ''year'': Jahr der Erstzulassung
* ''month'': Monat der Erstzulassung
=== Fehler ===
* ''404 MODEL_NOT_FOUND'': Modell nicht gefunden
=== Beispiel ===
GET /api/v1/models/864/submodels?year=2015&month=5
{
"submodels": {
"1191": "Modell ab 2010",
"1192": "Modell ab 2008 (CC)",
},
"bodies_url": "https://autofokus24.de/api/v1/submodels/{submodel_id}/bodies"
}
==== GET /submodels/{submodel_id}/bodies ====
=== Beschreibung ===
Gibt die Liste der verfügbaren Aufbauten zu einem Modell in einer Baureihe zurück.
=== Parameter ===
In der URL übergeben:
* ''submodel_id'': ID der Baureihe
Im Query-String übergeben:
* ''year'': Jahr der Erstzulassung
* ''month'': Monat der Erstzulassung
=== Fehler ===
* ''404 SUBMODEL_NOT_FOUND'': Submodell nicht gefunden
=== Beispiel ===
GET /api/v1/submodels/1191/bodies?year=2015&month=5
{
"bodies": {
"42": {
"body": "KOMBI",
"doors": "5"
},
"45": {
"body": "LIMOUSINE",
"doors": "4"
}
},
"engines_url": "https://autofokus24.de/api/v1/submodels/1191/bodies/{body_id}/engines"
}
==== GET /submodels/{submodel_id}/bodies/{body_id}/engines ====
=== Beschreibung ===
Gibt die Liste der verfügbaren Motoren zu einem Modell in einer Baureihe mit einem bestimmten Aufbau
zurück.
=== Parameter ===
In der URL übergeben:
* ''submodel_id'': ID der Baureihe
* ''body_id'': ID der Aufbauvariante
Im Query-String übergeben:
* ''year'': Jahr der Erstzulassung
* ''month'': Monat der Erstzulassung
=== Fehler ===
* ''404 SUBMODEL_NOT_FOUND'': Submodell nicht gefunden
* ''404 BODY_NOT_FOUND'': Aufbau nicht gefunden
=== Beispiel ===
GET /api/v1/submodels/1191/bodies/42/engines?year=2015&month=5
{
"engines": {
"6590": {
"kw": "77",
"ps": 105,
"fuel": "DIESEL",
"cylinders": "4",
"cubic_capacity": "1.6"
},
"9050": {
"kw": "90",
"ps": 122,
"fuel": "BENZIN",
"cylinders": "4",
"cubic_capacity": "1.4"
},
...
},
"editions_url": "https://autofokus24.de/api/v1/submodels/1191/bodies/42/engines/{engine_id}/editions"
}
==== GET /submodels/{submodel_id}/bodies/{body_id}/engines/{engine_id}/editions ====
=== Beschreibung ===
Gibt die Liste der verfügbaren Ausstattungsvarianten zu einem Modell in einer Baureihe mit einem
bestimmten Aufbau und Motor zurück.
=== Parameter ===
In der URL übergeben:
* ''submodel_id'': ID der Baureihe
* ''body_id'': ID der Aufbauvariante
* ''engine_id'': ID des Motors
Im Query-String übergeben:
* ''year'': Jahr der Erstzulassung
* ''month'': Monat der Erstzulassung
=== Fehler ===
* ''404 SUBMODEL_NOT_FOUND'': Submodell nicht gefunden
* ''404 BODY_NOT_FOUND'': Aufbau nicht gefunden
* ''404 ENGINE_NOT_FOUND'': Motor nicht gefunden
=== Beispiel ===
GET /api/v1/submodels/1191/bodies/42/engines/6590/editions?year=2015&month=5
{
"editions": {
"84795": {
"edition": "BlueMotion",
"hsn": "0603",
"tsn": "AQH",
"other_tsns": []
},
"85195": {
"edition": "Business Edition",
"hsn": "0603",
"tsn": "AYF",
"other_tsns": []
},
...
},
}
==== GET /calculate/{hsn}/{tsn} ====
=== 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.
=== 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:
* ''hsn'': Herstellerschlüsselnummer
* ''tsn'': Typschlüsselnummer
Im Query-String übergeben:
* ''year'': Jahr der Erstzulassung
* ''month'': Monat der Erstzulassung
* ''mileage'': Laufleistung in km, ehemals ''miles''
* Optionale Parameter:
* ''free_text'': Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung, ehemals ''fuzzyText''
* ''model'': Modellbezeichnung
* ''edition'': Ausstattungsvariante / Sondermodell, ehemals ''specialModel''; die Schreibweise des Sondermodells ist der Funktion ''.../editions'' zu entnehmen
* ''equipment'': Aufzählung der Ausstattungsmerkmale, ehemals ''featureList''
* ''color'': Kurzbezeichnung der Farbe
* ''power'': Motorleistung in KW
* ''fuel'': Kraftstoff
* ''body'': Aufbau, ehemals ''buildType''
* ''doors'': Anzahl Türen, ehemals ''doorCount''
* ''dealer_type'': Unternehmensart, ehemals ''dealerSize''
* ''price_range'': durchschnittliche Preisklasse des Händlers, ehemals ''priceClass''
* ''stock_size'': durchschnittlicher Fahrzeugbestand, ehemals ''carVolume''
* ''guarantees'': üblicherweise angebotene Garantieleistungen, ehemals ''garantieValue''
* ''idle_time'': Standzeit zur Berechnung der Verkaufswahrscheinlichkeiten in ''sales_probability'', ehemals ''monthWaitForSell''
* ''yearly_mileage'': Jährliche Laufleistung in km zur Berechnung der Restwertprognose in ''degeneration'', ehemals ''milesPerYear''
* ''estimated_life'': Geplante Nutzungsdauer in Jahren zur Berechnung der Restwertprognose in ''degeneration'', ehemals ''usageYearCount''
=== Fehler ===
* ''300 MULTIPLE_MODELS'': Mehrere zutreffende Modelle gefunden
* ''404 NOT_FOUND'': HSN oder TSN nicht gefunden
* ''404 NOT_FOUND_IN_TIMESPAN'': HSN oder TSN im angegebenen Zeitraum nicht gefunden
Für letzteren Fehler werden ein oder zwei zusätzliche Felder zurückgegeben:
''build_since'' und ''build_until''. Beispiel:
{
"error": {
"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"
}
=== Beispiel ===
GET /api/v1/calculate/0603/aqh?year=2015&month=5&mileage=10000&idle_time=2&color=wht
[
{
"hsn": "0603",
"tsn": "AQH",
"brand": "VW", # Ehemals "make"
"model": "Passat",
"submodel": "Modell ab 2010", # Ehemals "submodelName"
"body": "KOMBI", # Ersetzt "buildKind" als Integer
"edition": "BlueMotion", # Ersetzt "specialModel"
"kw": 77, # Ehemals "power"
"fuel": "DIESEL", # Ersetzt "fuel" als ID
"color": "wht",
"equipment_by_date": [
"KLI",
"AIB",
"BAB",
...
], # Ehemals "extrasByDate"
"equipment_by_engine": [
"BC",
"PF",
"SEG",
...
], # 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": [
19655,
19343,
19035,
...
]
},
...
]