Drive Analytics API

Schnellstart

1. In Einstellungen → API-Zugriff einen Key erstellen. Der Klartext wird einmalig angezeigt, kopiere ihn sofort.
2. Den Key bei jeder Anfrage im Authorization-Header mitschicken.
3. Loslegen, z. B. deine Fahrzeuge abrufen:

curl -H "Authorization: Bearer da_DEIN_KEY" \
     https://driveanalytics.uk/api/v1/cars

Antwort:

{
  "data": [
    {
      "id": 6,
      "license_plate": "M-AB-1234",
      "make": "Mercedes-Benz",
      "model": "C 220 d",
      "is_registered": true,
      "access": "owner",
      "current_mileage": 84210,
      "position": { "lat": 52.5163, "lon": 13.3777, "fuel_percent": 64,
                    "voltage_v": 12.7, "seen_at": "2026-06-25T09:12:00+00:00" }
    }
  ],
  "meta": { "count": 1 }
}

Authentifizierung

Jede Anfrage braucht deinen API-Key als Bearer-Token im Authorization-Header (alternativ der Header X-API-Key). Keys beginnen mit da_. Auf dem Server wird nur ein Hash gespeichert, der Klartext ist nach dem Erstellen nicht mehr abrufbar. Du kannst beliebig viele Keys mit eigenen Namen anlegen (max. 20 aktiv) und einzeln widerrufen, ein widerrufener Key wird sofort mit 401 abgelehnt.

Authorization: Bearer da_QMQvA2zPe8x1k...   # empfohlen
X-API-Key: da_QMQvA2zPe8x1k...               # Alternative

Basis-URL & Version

Alle Endpunkte liegen unter https://driveanalytics.uk/api/v1. Die Versionsnummer im Pfad bleibt stabil; abwärtskompatible Ergänzungen (neue Felder/Endpunkte) kommen ohne Versionswechsel dazu. Alle Anfragen laufen ausschließlich über HTTPS.

Antwort-Format

Erfolg, Einzelobjekt:

{ "data": { "id": 6, ... } }

Erfolg, Liste (mit meta):

{ "data": [ { ... }, { ... } ], "meta": { "count": 2, "limit": 50, "offset": 0 } }

• Zeitstempel: ISO 8601 mit Zeitzone (UTC), z. B. 2026-06-25T09:12:00+00:00.
• Geldbeträge und Liter: Strings (volle Dezimal-Präzision), z. B. "46.43".
• Distanzen (m/km), Koordinaten, Geschwindigkeiten, Zähler und Scores: Zahlen.
• null bedeutet „nicht vorhanden / unbekannt".

Fehler

Fehler kommen als JSON mit passendem HTTP-Status:

{ "error": { "code": "forbidden", "message": "Nur der Besitzer kann Fahrten löschen." } }

Rate-Limits

120 Anfragen pro Minute je API-Key. Bei Überschreitung kommt 429 mit code: "rate_limited", warte dann kurz und wiederhole.

Paginierung & Filter

Listen unterstützen ?limit= (Standard 50, max. 200) und ?offset=. Fahrten und der Export akzeptieren zusätzlich einen Zeitraum über ?from=YYYY-MM-DD und ?to=YYYY-MM-DD.

# Zweite Seite à 25, nur Juni 2026
curl -H "Authorization: Bearer da_DEIN_KEY" \
  "https://driveanalytics.uk/api/v1/cars/6/trips?limit=25&offset=25&from=2026-06-01&to=2026-06-30"

Code-Beispiele

Dieselbe Anfrage (Fahrten eines Autos) in drei Sprachen:

cURL

curl -H "Authorization: Bearer $DA_KEY" \
  "https://driveanalytics.uk/api/v1/cars/6/trips?limit=10"

JavaScript (fetch)

const res = await fetch(
  "https://driveanalytics.uk/api/v1/cars/6/trips?limit=10",
  { headers: { Authorization: `Bearer ${process.env.DA_KEY}` } }
);
const { data, meta } = await res.json();
console.log(meta.count, data[0].distance_km);

Python (requests)

import os, requests
r = requests.get(
    "https://driveanalytics.uk/api/v1/cars/6/trips",
    params={"limit": 10},
    headers={"Authorization": f"Bearer {os.environ['DA_KEY']}"},
)
r.raise_for_status()
for trip in r.json()["data"]:
    print(trip["started_at"], trip["distance_km"], "km")

Objekt: Fahrzeug

Felder eines car-Objekts.

{
  "id": 6,                          // int, eindeutige Fahrzeug-ID
  "vin": "WVWZZZ1KZAW000000",       // string|null, Fahrgestellnummer
  "license_plate": "M-AB-1234",     // string|null
  "license_country": "D",           // string|null
  "make": "Mercedes-Benz",          // string|null, Marke
  "model": "C 220 d",               // string|null
  "first_registration": "2019-03-01", // date|null, Erstzulassung
  "body_class": "Limousine",        // string|null
  "is_registered": true,            // bool, aktiver Tracker?
  "access": "owner",                // "owner" | "shared"
  "current_mileage": 84210,         // int|null, km
  "odometer_auto": true,            // bool, km automatisch via OBD?
  "mileage_updated_at": "2026-06-25T09:12:00+00:00",
  "position": {                     // object|null, letzte bekannte Position
    "lat": 52.5163, "lon": 13.3777,
    "fuel_percent": 64,             // int|null
    "range_km": 540,                // int|null
    "voltage_v": 12.7,              // float|null, Bordspannung
    "dtc_codes": [],                // string[], Fehlercodes
    "seen_at": "2026-06-25T09:12:00+00:00",
    "moved_at": "2026-06-25T08:55:00+00:00"
  },
  "created_at": "2026-06-19T06:58:08+00:00"
}

Objekt: Fahrt

Die Übersicht (trip_summary); das Detail enthält zusätzlich route, speed_series, events, score_breakdown.

{
  "id": 42, "car_id": 6,
  "started_at": "2026-06-24T08:00:00+00:00",
  "ended_at": "2026-06-24T08:30:00+00:00",
  "duration_min": 30,
  "distance_m": 18230,
  "distance_km": 18.23,
  "top_speed_kmh": 121,
  "avg_fuel_l_per_100km": "6.4",    // string|null
  "category": "business",           // "private"|"business"|"commute"|null
  "purpose": "Kundentermin Müller", // string|null (nur bei business)
  "driving_score": 88,              // int|null, 0–100
  "event_count": 1,                 // Anzahl Ereignisse (harsh_brake, ...)
  "shared": false,
  "share_url": null                 // string|null, öffentlicher Link
}

Objekt: Tankrechnung

{
  "id": 3, "car_id": 6,
  "fueled_at": "2026-06-13T18:08:00+00:00",
  "liters": "46.43",                // string
  "price_per_liter": "1.899",       // string
  "total_amount": "88.17",          // string, in Originalwährung
  "discount_amount": null,          // string|null
  "currency": "EUR",
  "total_amount_eur": "88.17",      // string, in EUR umgerechnet
  "fx_rate": null, "fx_rate_date": null,
  "fuel_type": "diesel",            // e5|e10|super_plus|diesel|...
  "station_name": "Shell Berlin",
  "station_address": "...",
  "status": "confirmed",
  "owned": true,                    // false = geteiltes Fahrzeug (nur lesen)
  "image_url": "/api/v1/fuel-receipts/3/image"
}

Objekte: Wartung, Geofence, Mitteilung, Batterie

Wartungsposition

{ "id": 12, "kind": "oil_change", "name": "Motoröl",
  "interval_km": 10000, "interval_months": 12,
  "last_service_date": "2025-11-02", "last_service_mileage": 71200,
  "due_date": "2026-11-02", "due_km": 81200,
  "severity": "ok",                 // "ok"|"warn"|"danger"
  "notify_lead_times": ["1_month","1000_km"] }

Geofence-Zone

{ "id": 1, "name": "Zuhause", "lat": 52.5, "lon": 13.4,
  "radius_m": 150, "notify_enter": true, "notify_leave": true, "enabled": true }

Mitteilung

{ "id": 87, "type": "theft", "priority": "critical",
  "title": "Manipulationsversuch", "body": "...", "car_id": 6,
  "deeplink_url": "/cars/6", "read": false, "read_at": null,
  "created_at": "2026-06-24T18:30:00+00:00" }

Batterie-Gesundheit

{ "status": "good",               // good|watch|critical|no_data
  "label": "Gut", "resting_v": 12.7, "crank_min_v": 11.1,
  "charge_max_v": 14.9, "charging_ok": true,
  "trend": "stable", "days": 14, "note": "Batterie in gutem Zustand.",
  "spark": [12.6, 12.7, 12.7] }

Endpunkte · Konto

Endpunkte · Fahrzeuge

{ "date": "2026-06-25", "mileage": 84210 }   // beide optional

Endpunkte · Fahrten

{ "category": "business", "purpose": "Kundentermin Müller" }

{ "data": { "share_url": "https://driveanalytics.uk/t/AbC123", "token": "AbC123" } }

Endpunkte · Tankrechnungen

Endpunkte · Wartung

Siehe Fahrzeuge: GET /cars/{id}/maintenance und POST /cars/{id}/maintenance/{item_id}/done.

Endpunkte · Geofence-Zonen

{ "name": "Zuhause", "lat": 52.5, "lon": 13.4, "radius_m": 150,
  "notify_enter": true, "notify_leave": true }

{ "enabled": false }

Endpunkte · Benachrichtigungen

Endpunkte · Fahrtenbuch-Export

Gibt es im Zeitraum unkategorisierte Fahrten, kommt 409 uncategorized_trips — setze zuerst überall eine Kategorie via PATCH /api/v1/trips/{id}.

curl -L -H "Authorization: Bearer $DA_KEY" \
  "https://driveanalytics.uk/api/v1/logbook/export?format=pdf&from=2026-01-01&to=2026-03-31" \
  -o fahrtenbuch.pdf