Dokumentation der RESTful API Version 1

Hinweis: Diese API-Version (1.0) wird nicht mehr aktiv weiterentwickelt. Neue Integrationen sollten die RESTful API, Version 2.0 verwenden. Version 1.0 bleibt für bestehende Anbindungen weiterhin verfügbar.

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