- Dokumentation:
Dies ist eine alte Version des Dokuments!
Eine allgemeine Beschreibung der RESTful API finden Sie unter APIs.
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.
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.
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 | |||
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 |
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> |
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}" }
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.
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 |
Gibt ein Objekt mit Kurzbezeichnung-Farbname-Zuordnungen zurück.
GET
…/colors
GET /api/v2/colors
{ "wht": "weiss", "red": "rot", "ora": "orange", ... }
Gibt ein Objekt mit Kurzbezeichnung-Featurename-Zuordnungen zurück.
GET
…/equipment
GET /api/v2/equipment
{ "GAS": "Gasantrieb", "ELE": "Elektromotor", "BHG": "behindertengerecht", ... }
Gibt ein Array aller verfügbaren Aufbauvarianten zurück.
GET
…/bodies
GET /api/v2/bodies
[ "BUS", "CABRIO", "COUPE", ... ]
Gibt die Liste bekannter Marken mit ihrer jeweiligen ID zurück.
GET
…/brands
GET /api/v2/brands
{ "brands": { "1": "Alfa Romeo", "57": "ALPINA", "37": "VW", ... }, "models_url": "https://autofokus24.de/api/v1/brands/{brand_id}/models", }
Gibt die Liste der in einem bestimmten Zeitraum hergestellten Modelle zu einer angegebenen Marke zurück.
GET
…/brands/{brand_id}/models
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 |
404 BRAND_NOT_FOUND
: Marke nicht gefunden
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" }
Gibt die Liste der in einem bestimmten Zeitraum hergestellten Baureihen zu einem angegebenen Modell einer Marke zurück.
GET
…/models/{model_id}/series
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 |
404 MODEL_NOT_FOUND
: Modell nicht gefunden
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" }
Gibt die Liste der verfügbaren Aufbauten zu einem Modell in einer Baureihe zurück.
GET
…/series/{series_id}/bodies
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 |
404 SERIES_NOT_FOUND
: Baureihe nicht gefunden
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" }
Gibt die Liste der verfügbaren Motoren zu einem Modell in einer Baureihe mit einem bestimmten Aufbau zurück.
GET
…/series/{series_id}/bodies/{body_id}/engines
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 |
404 SERIES_NOT_FOUND
: Baureihe nicht gefunden
404 BODY_NOT_FOUND
: Aufbau nicht gefunden
GET /api/v2/series/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/v2/series/1191/bodies/42/engines/{engine_id}/editions" }
Gibt die Liste der verfügbaren Sondermodelle zu einem Modell in einer Baureihe mit einem bestimmten Aufbau und Motor zurück.
GET
…/series/{series_id}/bodies/{body_id}/engines/{engine_id}/editions
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 |
404 SERIES_NOT_FOUND
: Baureihe nicht gefunden
404 BODY_NOT_FOUND
: Aufbau nicht gefunden
404 ENGINE_NOT_FOUND
: Motor nicht gefunden
GET /api/v2/series/1212/bodies/27/engines/11730/editions?year=2010&month=5
{ "55302": { "edition": "BlueMotion Comfortline", "hsn": "0603", "tsn_list": [ "APW" ] }, "55304": { "edition": "Comfortline", "hsn": "0603", "tsn_list": [ "APW", "ASF" ] }, ... }, }
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.
GET
…/calculate/{hsn}/{tsn}
In der URL übergeben:
Parameter | Beschreibung |
---|---|
hsn | Herstellerschlüsselnummer |
tsn | Typschlüsselnummer |
Im Query-String übergeben:
Parameter | Beschreibung | Erforderlich? |
---|---|---|
year | Jahr der Erstzulassung | Ja |
month | Monat der Erstzulassung | |
mileage | Laufleistung in km | |
free_text | Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung | Nein |
model | Modellbezeichnung | |
series | Baureihenbezeichnung | |
edition | Sondermodellbezeichnung; die Schreibweise des Sondermodells ist der Funktion GetEditions zu entnehmen | |
equipment | Aufzählung der Ausstattungsmerkmale | |
color | Kurzbezeichnung der Farbe | |
power | Motorleistung in KW | |
fuel | Kraftstoff | |
body | Aufbau | |
doors | Anzahl Türen | |
dealer_type | Unternehmensart | |
price_range | durchschnittliche Preisklasse des Händlers | |
stock_size | durchschnittlicher Fahrzeugbestand | |
guarantees | üblicherweise angebotene Garantieleistungen | |
idle_time | Standzeit zur Berechnung der Verkaufswahrscheinlichkeiten in sales_probability | |
yearly_mileage | Jährliche Laufleistung in km zur Berechnung der Restwertprognose in degeneration | |
estimated_life | Geplante Nutzungsdauer in Jahren zur Berechnung der Restwertprognose in degeneration |
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" }
GET /api/v2/calculate/0603/aqh?year=2015&month=5&mileage=10000&idle_time=2&color=wht
[ { "hsn": "0603", "tsn": "aqh", "brand": "VW", "model": "Passat", "series": "Modell ab 2010", "production_start": 2010, "body": "KOMBI", "doors": 5, "color": "wht", "engine": "4-Zylinder DIESELMOTOR", "fuel": "DIESEL", "kw": 77, "equipment_by_date": [ "KLI", "AIB", ... ], "equipment_by_engine": [ "BC", "PF", ... ], "equipment": [ "KLI", "AIB", ... ], "selling_price": 16777, "buying_price": 12497, "dealer_price_range": 4, "estimated_standing_time": 33 }
]