Dokumentation der RESTful API Version 2

Eine allgemeine Beschreibung der RESTful API finden Sie unter APIs.

Authentifizierung und Sicherheit

Die Authentifizierung erfolgt per Basic-HTTP-Auth mit Nutzername und Passwort.

Die Schnittstelle ist nur über HTTPS erreichbar.

Bei einem Authentifizierungsfehler wird ein Fehler mit Status 401 und Code "UNAUTHORIZED" zurückgegeben.

Datentypen, Encoding

POST-Parameter werden mit dem MIME-Type application/x-www-form-urlencoded formatiert und mit UTF-8 kodiert übergeben.

Antworten werden als JSON (Mime-Type application/json) formatiert und mit UTF-8 kodiert übertragen.

Fehlende Werte sowie null sind als gleichwertig zu betrachten. Im Gegensatz dazu bedeutet ein leeres Array oder Objekt, dass das Feld zwar berechnet wurde, jedoch tatsächlich keine Daten enthält.

Verhalten im Fehlerfall

Genutzte HTTP-Statuscodes

Hinweis: Der code wird nur zurückgegeben, wenn die Anfrage die API erreicht. Antworten des Webservers enthalten damit kein JSON. Insbesondere ist dies der Fall für alle Requests über HTTP, die durch den Server mit 301 Moved Permanently und einer Weiterleitung zu HTTPS beantwortet werden.

Format

Beispiel

GET https://autofokus24.de/api/v2/calculate/7909/aak?pretty_print&mileage=1&year=2013&month=5

{
    "error": {
        "status": 300,
        "code": "MULTIPLE_CHOICES",
        "message": "For HSN=7909 \/ TSN=aak multiple models exist"
    },
    "options": {
        "model": [
            "X5",
            "X6"
        ]
    },
    "url": "https:\/\/autofokus24.de\/api\/v2\/calculate\/7909\/aak?pretty_print&mileage=1&year=2013&month=5&model={model}"
}

URLs

Allgemeines

Prefix: /api/v2

Die folgenden URLs werden an den Prefix angehangen. Die zu verwendende HTTP-Methode zum Zugriff ist vorangestellt.

Alle aufgelisteten Parameter müssen, wenn nicht anders angegeben, übergeben werden.

Zusätzlich existiert für jede URI der Parameter pretty_print. Wird er mit übergeben, wird die Ausgabe serverseitig zur besseren Lesbarkeit formatiert. Der Wert des Parameters wird ignoriert.

Übersicht und Abrechnung

GetAllColors

Beschreibung

Gibt ein Objekt mit Kurzbezeichnung-Farbname-Zuordnungen zurück. Die Kürzel können in Calculate verwendet werden.

Aufruf

• Methode: GET
• URL: …/colors

Beispiel

GET /api/v2/colors

{
    "wht": "weiss",
    "red": "rot",
    "ora": "orange",
    ...
}

GetAllEquipment

Beschreibung

Gibt ein Objekt mit Kurzbezeichnung-Featurename-Zuordnungen zurück. Die Kürzel können in Calculate verwendet werden.

Aufruf

• Methode: GET
• URL: …/equipment

Beispiel

GET /api/v2/equipment

{
    "GAS": "Gasantrieb",
    "ELE": "Elektromotor",
    "BHG": "behindertengerecht",
    ...
}

GetAllBodies

Beschreibung

Gibt ein Array aller verfügbaren Aufbauvarianten zurück. Die Kürzel können in Calculate verwendet werden.

Aufruf

• Methode: GET
• URL: …/bodies

Beispiel

GET /api/v2/bodies

[
    "BUS",
    "CABRIO",
    "COUPE",
    ...
]

GetBrands

Beschreibung

Gibt die Liste bekannter Marken mit ihrer jeweiligen ID zurück.

Aufruf

• Methode: GET
• URL: …/brands

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

• brands, welches wiederum ein Objekt mit ID–Marken-Zuordnungen enthält
• models_url: Die URL der nächsten möglichen Abfrage

Beispiel

GET /api/v2/brands

{
    "brands": {
        "1": "Alfa Romeo",
        "57": "ALPINA",
        "37": "VW",
        ...
    },
    "models_url": "https://autofokus24.de/api/v1/brands/{brand_id}/models",
}

GetModels

Beschreibung

Gibt die Liste der in einem bestimmten Zeitraum hergestellten Modelle zu einer angegebenen Marke zurück.

Aufruf

• Methode: GET
• URL: …/brands/{brand_id}/models

Parameter

In der URL übergeben:

Im Query-String übergeben:

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

• models, welches wiederum ein Objekt mit ID–Modellbezeichnung-Zuordnungen enthält
• series_url: Die URL der nächsten möglichen Abfrage

Fehler

• 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/brands/37/models?year=2015&month=5

{
    "models": {
        "850": "Amarok",
        "851": "Bora",
        "864": "Passat",
        ...
    },
    "series_url": "https://autofokus24.de/api/v2/models/{model_id}/series"
}

GetSeries

Beschreibung

Gibt die Liste der in einem bestimmten Zeitraum hergestellten Baureihen zu einem angegebenen Modell einer Marke zurück.

Aufruf

• Methode: GET
• URL: …/models/{model_id}/series

Parameter

In der URL übergeben:

Im Query-String übergeben:

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

• series, welches wiederum ein Objekt mit ID–Baureihenbezeichnung-Zuordnungen enthält
• bodies_url: Die URL der nächsten möglichen Abfrage

Fehler

• 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/models/864/series?year=2015&month=5

{
    "series": {
        "1191": "Modell ab 2010",
        "1192": "Modell ab 2008 (CC)",
    },
    "bodies_url": "https://autofokus24.de/api/v2/series/{series_id}/bodies"
}

GetBodies

Beschreibung

Gibt die Liste der verfügbaren Aufbauten zu einem Modell in einer Baureihe zurück.

Aufruf

• Methode: GET
• URL: …/series/{series_id}/bodies

Parameter

In der URL übergeben:

Im Query-String übergeben:

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

• bodies, welches wiederum aus Aufbau-Objekten besteht, wobei die ID der Aufbauvariante als Key genutzt wird
• engines_url: Die URL der nächsten möglichen Abfrage

Die Aufbauobjekte bestehen aus folgenden Feldern:

Fehler

• 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/series/1191/bodies?year=2015&month=5

{
    "bodies": {
        "42": {
            "body": "KOMBI",
            "doors": "5"
        },
        "45": {
            "body": "LIMOUSINE",
            "doors": "4"
        }
    },
    "engines_url": "https://autofokus24.de/api/v2/series/1191/bodies/{body_id}/engines"
}

GetEngines

Beschreibung

Gibt die Liste der verfügbaren Motoren zu einem Modell in einer Baureihe mit einem bestimmten Aufbau zurück.

Aufruf

• Methode: GET
• URL: …/series/{series_id}/bodies/{body_id}/engines

Parameter

In der URL übergeben:

Im Query-String übergeben:

Rückgabe

Zurückgegeben wird ein Objekt mit zwei Elementen:

• engines, welches wiederum aus Motor-Objekten besteht, wobei die ID des Motors als Key genutzt wird
• editions_url: Die URL der nächsten möglichen Abfrage

Die Motorobjekte bestehen aus folgenden Feldern:

Fehler

• 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/series/1191/bodies/42/engines?year=2015&month=5

{
    "engines": {
        "6590": {
            "kw": "77",
            "fuel": "DIESEL",
            "cylinders": "4",
            "cubic_capacity": "1.6"
        },
        "9050": {
            "kw": "90",
            "fuel": "BENZIN",
            "cylinders": "4",
            "cubic_capacity": "1.4"
        },
        ...
    },
    "editions_url": "https://autofokus24.de/api/v2/series/1191/bodies/42/engines/{engine_id}/editions"
}

GetEditions

Beschreibung

Gibt die Liste der verfügbaren Sondermodelle zu einem Modell in einer Baureihe mit einem bestimmten Aufbau und Motor zurück.

Aufruf

• Methode: GET
• URL: …/series/{series_id}/bodies/{body_id}/engines/{engine_id}/editions

Parameter

In der URL übergeben:

Im Query-String übergeben:

Rückgabe

Zurückgegeben wird ein Objekt mit einem Element, editions, welches wiederum aus Sondermodell-Objekten besteht, wobei die ID des Sondermodells als Key genutzt wird.

Eine Folge-URL wird nicht übergeben, da in der Baumstruktur keine weiteren Schritte notwendig sind, um ein Fahrzeug zu identifizieren.

Die Sondermodellobjekte bestehen aus folgenden Feldern:

Fehler

• 404 NO_DATA

Details siehe oben.

Beispiel

GET /api/v2/series/1212/bodies/27/engines/11730/editions?year=2010&month=5

{
    "editions": {
        "55302": {
            "edition": "BlueMotion Comfortline",
            "hsn": "0603",
            "tsn_list": [
                "APW"
            ]
        },
        "55304": {
            "edition": "Comfortline",
            "hsn": "0603",
            "tsn_list": [
                "APW",
                "ASF"
            ]
        },
        ...
    },
}

Calculate

Beschreibung

Gibt zu einer angegebenen HSN und TSN entsprechende Preisschätzungen, Ausstattung und weitere Grundinformationen zurück. Da der Parameter free_text sehr lang werden kann, darf diese Funktion auch per POST abgerufen werden.

Leere Werte werden nicht zurückgegeben, damit können einzelne Elemente der Antwort, wie motor_name, color oder equipment_by_edition, mitunter scheinbar fehlen.

Aufruf

• Methode: GET
• URL: …/calculate/{hsn}/{tsn}

Parameter

In der URL übergeben:

Im Query-String übergeben:

Rückgabe

Zurückgegeben wird eine Liste von Fahrzeug-Objekten, die jeweils aus den in folgender Tabelle erklärten Feldern bestehen.

Fehler

• 300 MULTIPLE_MODELS
• 404 NO_DATA
• 404 MODEL_NOT_FOUND
• 404 SERIES_NOT_FOUND
• 404 EDITION_NOT_FOUND
• 404 NO_MATCHES

Details siehe oben.

Beispiel

GET /api/v2/calculate/0035/afs?pretty_print&mileage=20000&year=2010&month=10&doors=5&dealer_price_range=3

[
    {
        "hsn": "0035",
        "tsn": "afs",
        "brand": "Opel",
        "model": "Corsa",
        "series": "Modell ab 2006 (D)",
        "production_start": 2007,
        "edition": null,
        "body": "LIMOUSINE",
        "doors": 5,
        "color": null,
        "engine": "4-Zylinder DIESELMOTOR",
        "engine_name": null,
        "fuel": "DIESEL",
        "kw": 55,
        "cubic_capacity": 1248,
        "equipment_by_date": [
            "AIB",
            "BAB",
            ...
        ],
        "equipment_by_engine": [],
        "equipment_by_edition": [],
        "equipment": [
            "AIB",
            "BAB",
            ...
        ],
        "selling_price": 2345,
        "buying_price": 1234,
        "dealer_price_range": 3,
        "guarantee": "Mit Gewährleistung",
        "estimated_standing_time": 40,
        "sales_probability": null,
        "degeneration": null
    }
]