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

Die Schnittstelle ist nur über HTTPS erreichbar.

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.

• 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

• 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}

GET /brand/42

{
    "error": {
        "status": 404,
        "code": "BRAND_NOT_FOUND",
        "message": "Marke nicht gefunden"
    }
}

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.

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}

Gibt ein Objekt mit Kurzbezeichnung-Farbname-Zuordnungen zurück.

GET /api/v1/colors

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

Gibt ein Objekt mit Kurzbezeichnung-Featurename-Zuordnungen zurück.

GET /api/v1/features

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

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

GET /api/v1/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.

In der URL übergeben:

• brand_id

  : ID der Marke

Im Query-String übergeben:

• year

  : Jahr der Erstzulassung

• month

  : Monat der Erstzulassung

• 404 BRAND_NOT_FOUND

  : Marke nicht gefunden

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"
}

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

In der URL übergeben:

• model_id

  : ID des Modells

Im Query-String übergeben:

• year

  : Jahr der Erstzulassung

• month

  : Monat der Erstzulassung

• 404 MODEL_NOT_FOUND

  : Modell nicht gefunden

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"
}

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

In der URL übergeben:

• submodel_id

  : ID der Baureihe

Im Query-String übergeben:

• year

  : Jahr der Erstzulassung

• month

  : Monat der Erstzulassung

• 404 SUBMODEL_NOT_FOUND

  : Submodell nicht gefunden

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"
}

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

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

• 404 SUBMODEL_NOT_FOUND

  : Submodell nicht gefunden

• 404 BODY_NOT_FOUND

  : Aufbau nicht gefunden

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"
}

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

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

• 404 SUBMODEL_NOT_FOUND

  : Submodell nicht gefunden

• 404 BODY_NOT_FOUND

  : Aufbau nicht gefunden

• 404 ENGINE_NOT_FOUND

  : Motor nicht gefunden

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

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.

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

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

]