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

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,
            ...
        ]
    },
    ...
]