Dokumentation der RESTful API Version 1

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.

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