Handicap Engine API — REST API für WHS Golf Handicap Berechnung

Öffentliche Endpunkte

Diese Endpunkte erfordern keine Authentifizierung und sind für alle Clients frei zugänglich.

GET /v1/courses?q={suchbegriff} Sucht Golfplätze nach Name oder Ort. Gibt Course Rating, Slope Rating und Par pro Abschlag zurück. Fallback auf externe Platzdatenbank bei 0 lokalen Ergebnissen. Kein Auth erforderlich

GET /v1/courses/{courseId} Gibt vollständige Platzdetails zurück: alle Abschläge (TeeSets), Ratings mit CR/SR/Par/Bogey-Rating, Lochdaten (wenn verfügbar), Verifikationsstatus. Kein Auth erforderlich

GET /v1/health Service-Gesundheitsstatus. Prüft Datenbankverbindung und gibt aktuellen Systemstatus zurück. Kein Auth erforderlich

Authentifizierte Endpunkte

Für spielerbezogene Daten (Runden, Handicap Index, Simulationen) ist ein JWT Bearer Token erforderlich.

POST /v1/auth/register Registriert einen neuen Benutzer. Gibt 202 zurück (unabhängig von E-Mail-Existenz, Enumerationsschutz). Kein Auth erforderlich · Rate Limited

POST /v1/auth/login Authentifiziert einen Benutzer. Gibt Access JWT (15 min) und Refresh Token (30 Tage) zurück. TOTP MFA wird unterstützt (mehrstufiger Flow). Kein Auth erforderlich · Rate Limited

GET /v1/players/{playerId}/handicap Berechnet den aktuellen Handicap Index nach WHS. Gibt Fenster (bis zu 20 Runden), verwendete Differentials, Fidelity-Status, ESR-Flag und historische Entwicklung zurück. JWT Bearer erforderlich · Player-Scope

POST /v1/rounds Trägt eine gespielte Runde ein. Unterstützt drei Eingabemodi: Gesamtscore (AGS), lochweise (NDB-Kappung serverseitig), Stableford (Rückrechnung). 9-Loch-Runden werden korrekt normalisiert. JWT Bearer erforderlich · Rate Limited

POST /v1/players/{playerId}/simulate Was-wäre-wenn-Simulation: Gibt projizierten Handicap Index für einen hypothetischen Score zurück. Berücksichtigt das aktuelle 20-Runden-Fenster. JWT Bearer erforderlich · Player-Scope · Rate Limited

Alle Endpunkte in der vollständigen API-Referenz →

Schnellstart

Plätze suchen und Handicap-Daten in wenigen Minuten integrieren.

# Golfplätze suchen (kein API-Key erforderlich)
curl "https://handicap-engine.de/v1/courses?q=Hamburg" \
  -H "Accept: application/json"

# Antwort (gekürzt)
{
  "courses": [{
    "id": "uuid",
    "name": "Hamburger Golf-Club Falkenstein",
    "city": "Hamburg",
    "teeSets": [{
      "name": "Gelb",
      "ratings": [{
        "courseRating": 72.6,
        "slopeRating": 130,
        "par": 72,
        "routingType": "FULL_18"
      }]
    }]
  }]
}

# Score Differential berechnen (clientseitig)
# Formel: (AGS − Course Rating) × 113 / Slope Rating
diff = (85 - 72.6) * 113 / 130  # = 10.8

Technische Details

Basis-URL

https://handicap-engine.de/v1/
Alle API-Anfragen laufen über HTTPS. HTTP wird auf HTTPS umgeleitet.

Authentifizierung

JWT Bearer Token im Authorization-Header. Access Token TTL: 15 Minuten. Refresh Token TTL: 30 Tage. Token-Rotation bei jedem Refresh.

Antwortformat

Alle Antworten sind application/json. Fehler haben das Format {"error": {"code": "...", "message": "..."}}.

Rate Limiting

Öffentliche Endpunkte: 30 Req/Min. Auth-Endpunkte: 5 Login-Versuche/Min. Antwort bei Überschreitung: 429 Too Many Requests mit Retry-After.

WHS-Konformität

Implementiert WHS Rules of Handicapping (R&A / USGA 2024). Score Differential, Handicap Index, ESR §5.9, 9-Loch §3.1, Soft/Hard Cap.

OpenAPI Spec

Vollständige Spezifikation unter openapi.yaml. Maschinenlesbar, alle Felder mit Beschreibungen und WHS-Regelreferenzen.

Rate Limits im Überblick

Alle Limits sind Sliding-Window-basiert. Bei Überschreitung: 429 mit Retry-After-Header.

Endpunkt	Limit	Fenster
POST /v1/auth/login	5 pro IP, 10 pro E-Mail-Hash	1 min / 10 min
POST /v1/auth/register	3 pro IP	1 min
POST /v1/auth/forgot-password	3	15 min
POST /v1/auth/token/refresh	20	1 min
POST /v1/rounds	50	1 Stunde
POST /v1/players/{id}/simulate	30	1 min
GET /v1/courses (Suche)	unlimitiert (öffentlich)	—