Benutzer-Werkzeuge

Webseiten-Werkzeuge


dokumentation_der_restful_api_version_2

Dies ist eine alte Version des Dokuments!


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.

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.

HTTP-Status/
status
HTTP-Status Name
code
Beschreibung Verwendung
300 Multiple Choices MULTIPLE_MODELS Mehrere zutreffende Modelle gefunden Calculate
301 Moved Permanently MOVED_PERMANENTLY Zugriff ohne SSL mit Weiterleitung auf HTTPS Überall
400 Bad Request INVALID_INPUT Falsche oder fehlende Parameter Überall
401 Unauthorized UNAUTHORIZED Authentifizierungsfehler Überall bei fehlenden oder falschen Anmeldedaten
404 Not found NOT_FOUND Fehlerhafte URL Requests an nicht existierende URIs oder mit falschen Datentypen (z.B. einem String statt Integer) o.ä., die dadurch nicht zugeordnet werden können
NO_DATA Keine Modelle gefunden GetModels
Keine Baureihen gefunden GetSeries
Keine Aufbauten gefunden GetBodies
Keine Motoren gefunden GetEngines
Keine Sondermodelle gefunden GetEditions
HSN/TSN nicht gefunden Calculate
MODEL_NOT_FOUND HSN/TSN gefunden, aber keine Treffer durch Angabe des Modells
SERIES_NOT_FOUND HSN/TSN gefunden, aber keine Treffer durch Angabe der Baureihe
EDITION_NOT_FOUND HSN/TSN gefunden, aber keine Treffer durch Angabe des Sondermodells
NO_MATCHES HSN/TSN gefunden, aber keine Treffer zum gewünschten Zeitpunkt oder durch Angabe von Aufbau oder Türen
405 Method Not Allowed METHOD_NOT_ALLOWED Unzulässige HTTP-Methode Überall
450 Rate Limit Exceeded RATE_LIMIT_EXCEEDED Request-Limit wurde erreicht
500 Internal Server Error INTERNAL_SERVER_ERROR Ein serverseitiger Fehler ist aufgetreten. Wenn möglich, wird eine kurze Erklärung in
message

gegeben

503 Service Unavailable SERVICE_UNAVAILABLE API ist auf Grund von Wartungsarbeiten o.ä. temporär nicht erreichbar

Format

error

(Objekt)

status
Integer, entspricht dem HTTP-Status
code
Maschinenlesbare Bezeichnung des Fehlers
message
Beschreibung des Fehlers. Diese kann sich ohne Ankündigung ändern und sollte nicht zur automatisierten Auswertung herangezogen werden
invalid
Für Status 400 (Bad Request): Liste ungültiger Eingabeparameter.Beispiel:
"invalid":["year","month"]
missing
Für Status 400 (Bad Request): Liste fehlender Eingabeparameter.Beispiel:
"missing":["year","month"]
options
Für Status 300 (Multiple Choices): Objekt mit Auswahlmöglichkeiten.Beispiel:
"options":{"model":["X5","X6"]}]
url
Für Status 300 (Multiple Choices): URL-Template mit Platzhaltern für die in
options

gelisteten Möglichkeiten.Beispiel (gekürzt):

<nowiki>"url": "...\/calculate\/7909\/aak?...&model={model}"</nowiki>

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

Name Methode URL Rückgabe Abrechnung
GetAllColors
GET
/colors
Mögliche Farbcodes
GetAllEquipment
GET
/equipment
Mögliche Ausstattungs-Kürzel
GetAllBodies
GET
/bodies
Mögliche Aufbauvarianten
GetBrands
GET
/brands
Alle Marken
GetModels
GET
/brands/{brand_id}/models
Modelle einer Marke
GetSeries
GET
/models/{model_id}/series
Baureihen eines Modells
GetBodies
GET
/series/{series_id}/bodies
Aufbauten einer Baureihe
GetEngines
GET
/series/{series_id}/bodies/{body_id}/engines
Motoren zur aktuellen Auswahl Nur kostenpflichtig, falls kein Folgeaufruf von GetEditions erfolgt
GetEditions
GET
/series/{series_id}/bodies/{body_id}/engines/{engine_id}/editions
Sondermodelle und HSN/TSNs zur aktuellen Auswahl Kostenpflichtig, wird gezählt und abgerechnet
Calculate
GET

,

POST
/calculate/{hsn}/{tsn}
Fahrzeugbewertung

GetAllColors

Beschreibung

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

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.

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.

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

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:

Parameter Beschreibung
brand_id
ID der Marke

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year
Jahr der Erstzulassung Ja
month
Monat der Erstzulassung

Fehler

  • 404 BRAND_NOT_FOUND

    : Marke nicht gefunden

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:

Parameter Beschreibung
model_id
ID des Modells

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year
Jahr der Erstzulassung Ja
month
Monat der Erstzulassung

Fehler

  • 404 MODEL_NOT_FOUND

    : Modell nicht gefunden

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:

Parameter Beschreibung
series_id
ID der Baureihe

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year
Jahr der Erstzulassung Ja
month
Monat der Erstzulassung

Fehler

  • 404 SERIES_NOT_FOUND

    : Baureihe nicht gefunden

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:

Parameter Beschreibung
series_id
ID der Baureihe
body_id
ID der Aufbauvariante

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year
Jahr der Erstzulassung Ja
month
Monat der Erstzulassung

Fehler

  • 404 SERIES_NOT_FOUND

    : Baureihe nicht gefunden

  • 404 BODY_NOT_FOUND

    : Aufbau nicht gefunden

Beispiel

GET /api/v2/series/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/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:

Parameter Beschreibung
series_id
ID der Baureihe
body_id
ID der Aufbauvariante
engine_id
ID des Motors

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year
Jahr der Erstzulassung Ja
month
Monat der Erstzulassung

Fehler

  • 404 SERIES_NOT_FOUND

    : Baureihe nicht gefunden

  • 404 BODY_NOT_FOUND

    : Aufbau nicht gefunden

  • 404 ENGINE_NOT_FOUND

    : Motor nicht gefunden

Beispiel

GET /api/v2/series/1212/bodies/27/engines/11730/editions?year=2010&month=5
{
        "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:

Parameter Beschreibung
hsn
Herstellerschlüsselnummer
tsn
Typschlüsselnummer

Im Query-String übergeben:

Parameter Beschreibung Erforderlich?
year
Jahr der Erstzulassung Ja
month
Monat der Erstzulassung
mileage
Laufleistung in km
free_text
Beliebiger Fließtext zur Auswertung mit Einfluss auf die Bewertung Nein
model
Modellbezeichnung
series
Baureihenbezeichnung
edition
Sondermodellbezeichnung; die Schreibweise des Sondermodells ist der Funktion GetEditions zu entnehmen
equipment
Aufzählung der Ausstattungsmerkmale
color
Kurzbezeichnung der Farbe
power
Motorleistung in KW
fuel
Kraftstoff
body
Aufbau
doors
Anzahl Türen
dealer_type
Unternehmensart
price_range
durchschnittliche Preisklasse des Händlers
stock_size
durchschnittlicher Fahrzeugbestand
guarantees
üblicherweise angebotene Garantieleistungen
idle_time
Standzeit zur Berechnung der Verkaufswahrscheinlichkeiten in
sales_probability
yearly_mileage
Jährliche Laufleistung in km zur Berechnung der Restwertprognose in
degeneration
estimated_life
Geplante Nutzungsdauer in Jahren zur Berechnung der Restwertprognose in
degeneration

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/v2/calculate/0603/aqh?year=2015&month=5&mileage=10000&idle_time=2&color=wht
[
    {
        "hsn": "0603",
        "tsn": "aqh",
        "brand": "VW",
        "model": "Passat",
        "series": "Modell ab 2010",
        "production_start": 2010,
        "body": "KOMBI",
        "doors": 5,
        "color": "wht",
        "engine": "4-Zylinder DIESELMOTOR",
        "fuel": "DIESEL",
        "kw": 77,
        "equipment_by_date": [
            "KLI",
            "AIB",
            ...
        ],
        "equipment_by_engine": [
            "BC",
            "PF",
            ...
        ],
        "equipment": [
            "KLI",
            "AIB",
            ...
        ],
        "selling_price": 16777,
        "buying_price": 12497,
        "dealer_price_range": 4,
        "estimated_standing_time": 33
    }

]

dokumentation_der_restful_api_version_2.1484865123.txt.gz · Zuletzt geändert: 2017-01-19 23:32 von Christian