Endpunkt-Übersicht

Alle verfügbaren API-Endpunkte auf einen Blick. Jeder Endpunkt erfordert Authentifizierung per Bearer Token.

Basis-URL: https://api.grapeminds.eu/public/v1

Wir pflegen fertige Code-Beispiele für gängige Sprachen auf GitHub: github.com/grapeminds/api-examples

Test-Endpoint

GET /ping

Prüfen Sie, ob Ihr API-Schlüssel gültig und Ihre Verbindung aktiv ist

Nutzen Sie diesen Endpunkt als ersten Aufruf beim Einrichten Ihrer Integration. Er bestätigt, dass Ihr API-Schlüssel korrekt funktioniert, ohne dabei echte Anfragen zu verbrauchen.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/ping"

Beispiel-Antwort:

{
  "message": "API authentication successful",
  "authenticated_as": {
    "user_id": 1,
    "user_name": "Jane Doe",
    "user_email": "[email protected]"
  },
  "api_key": {
    "name": "My Integration Key",
    "prefix": "gm_abc1",
    "abilities": ["*"],
    "rate_limit_per_minute": 60
  },
  "timestamp": "2026-03-05T12:00:00+00:00"
}

Wein-Endpoints

GET /wines

Alle Weine mit Paginierung und Filtern auflisten

Query-Parameter:

  • page — Seitennummer (Standard: 1)
  • per_page — Einträge pro Seite (Standard: 15, max: 100)
  • color — Nach Farbe filtern (rot, weiß, rosé)
  • sub_type — Nach Typ filtern (still, schäumend)
  • producer_id — Nach Produzenten-ID filtern
  • region_id — Nach Regions-ID filtern
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/wines?color=red&per_page=20"

Beispiel-Antwort:

{
  "data": [
    {
      "id": 106636,
      "display_name": "Weingut Braunewell, Teufelspfad Spätburgunder",
      "color": "red",
      "type": "wine",
      "sub_type": "still",
      "residual_sugar": "dry",
      "producer": { "id": 24860, "name": "Braunewell", "title": "Weingut", "display_name": "Weingut Braunewell" },
      "region": { "id": 187, "name": "Rheinhessen", "country": "DE", "language": "en" }
    }
  ],
  "meta": { "current_page": 1, "last_page": 10, "per_page": 20, "total": 195, "from": 1, "to": 20 }
}
GET /wines/search

Weine nach Name oder Produzent suchen

Query-Parameter:

  • q — Suchanfrage (min. 3 Zeichen, erforderlich)
  • limit — Max. Ergebnisse (Standard: 20, max: 100)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/wines/search?q=Braunewell"

Beispiel-Antwort:

{
  "data": [
    {
      "id": 106636,
      "display_name": "Weingut Braunewell, Teufelspfad Spätburgunder",
      "color": "red",
      "residual_sugar": "dry",
      "producer_name": "Braunewell",
      "producer_title": "Weingut",
      "producer_display_name": "Weingut Braunewell"
    }
  ],
  "meta": { "query": "Braunewell", "count": 5 }
}
GET /wines/{id}

Detaillierte Weininformationen abrufen

Headers:

  • Accept-Language — Sprachcode (de, en, fr, it)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept-Language: de" \
     "https://api.grapeminds.eu/public/v1/wines/106636"

Beispiel-Antwort:

{
  "id": 106636,
  "display_name": "Weingut Braunewell, Teufelspfad Spätburgunder",
  "color": "red",
  "type": "wine",
  "sub_type": "still",
  "producer": { "id": 24860, "name": "Braunewell", "title": "Weingut", "display_name": "Weingut Braunewell" },
  "region": { "id": 187, "name": "Rheinhessen", "country": "de" },
  "residual_sugar": "trocken",
  "grapes": [
    { "id": 12345, "name": "Spätburgunder" }
  ],
  "description": { "text": "...", "language": "de" },
  "tasting_notes": { "text": "...", "language": "de" },
  "pairing": { "text": "...", "language": "de" },
  "flavor_profile": {
    "sweetness": 2, "acidity": 5, "tannins": 6,
    "alcohol": 6, "body": 6, "finish": 6
  }
}

Produzenten-Endpoints

GET /producers

Alle Produzenten mit Paginierung auflisten

Query-Parameter:

  • search — Nach Name suchen (min. 2 Zeichen)
  • per_page — Einträge pro Seite (Standard: 15, max: 100)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/producers?search=Braunewell"

Beispiel-Antwort:

{
  "data": [
    { "id": 24860, "name": "Braunewell", "title": "Weingut" }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 15, "total": 1, "from": 1, "to": 1 }
}
GET /producers/{id}

Produzentendetails mit optionalen Weinen abrufen

Antwortfelder:

  • title — Erzeuger-Präfix (z.B. "Weingut", "Château", "Domaine"), kann null sein
  • display_name — Vollständiger berechneter Name (Titel + Name)

Query-Parameter:

  • include_wines — Weine einschließen (boolean, Standard: false)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/producers/24860?include_wines=true"

Beispiel-Antwort:

{
  "data": {
    "id": 24860,
    "name": "Braunewell",
    "title": "Weingut",
    "display_name": "Weingut Braunewell",
    "wines": [
      { "id": 45686, "display_name": "Teufelspfad Riesling", "vintage": null, "color": "white", "producer_id": 24860, "residual_sugar": null },
      { "id": 106636, "display_name": "Teufelspfad Spätburgunder", "vintage": null, "color": "red", "producer_id": 24860, "residual_sugar": "dry" }
    ],
    "wines_count": 5
  }
}

Regions-Endpoints

GET /regions

Alle Regionen mit Paginierung auflisten

Query-Parameter:

  • country — Nach Ländercode filtern
  • search — Nach Name suchen

Headers:

  • Accept-Language — Sprachcode (de, en, fr, it)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept-Language: en" \
     "https://api.grapeminds.eu/public/v1/regions?country=DE"

Beispiel-Antwort:

{
  "data": [
    { "id": 187, "name": "Rheinhessen", "country": "DE", "language": "en" },
    { "id": 188, "name": "Pfalz", "country": "DE", "language": "en" },
    { "id": 189, "name": "Mosel", "country": "DE", "language": "en" }
  ],
  "meta": { "current_page": 1, "last_page": 2, "per_page": 15, "total": 25, "from": 1, "to": 15, "language": "en" }
}
GET /regions/{id}

Regionendetails mit optionalen Weinen abrufen

Query-Parameter:

  • include_wines — Weine einschließen (boolean, Standard: false)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept-Language: en" \
     "https://api.grapeminds.eu/public/v1/regions/187?include_wines=true"

Beispiel-Antwort:

{
  "data": {
    "id": 187,
    "name": "Rheinhessen",
    "country": "DE",
    "language": "en",
    "wines": [
      {
        "id": 106636,
        "display_name": "Weingut Braunewell, Teufelspfad Spätburgunder",
        "color": "red",
        "producer_id": 24860,
        "region_id": 187,
        "residual_sugar": "dry",
        "producer": { "id": 24860, "name": "Braunewell", "title": "Weingut" }
      }
    ],
    "wines_count": 42
  }
}
GET /region-insights/{regionId}

Detaillierte Einblicke für eine Weinregion abrufen

Query-Parameter:

  • lang — Sprachcode (de, en, fr, it)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/region-insights/187?lang=en"

Beispiel-Antwort:

{
  "id": 5,
  "region_id": 187,
  "lang": "en",
  "summary": "Rheinhessen is Germany's largest wine region...",
  "climate_and_terroir": "Moderate continental climate with mild winters...",
  "signature_styles": "Elegant Rieslings and aromatic Silvaner...",
  "key_grapes": "Riesling, Silvaner, Müller-Thurgau, Scheurebe"
}

404 – generating-Flag: Wenn die Ressource existiert, aber der Inhalt in der angeforderten Sprache noch nicht verfügbar ist, löst die API im Hintergrund KI-Generierung aus und gibt 404 mit generating: true zurück. Bitte nach ~30 Sekunden erneut versuchen.

404-Antwort (generating: false – Ressource existiert nicht):

{ "error": "Region insight not found for the specified language.", "generating": false }

404-Antwort (generating: true – KI-Generierung ausgelöst):

{ "error": "Region insight not found for the specified language.", "generating": true }

Trinkreife-Endpunkt

GET /drinking-periods/{wineId}

Optimales Trinkfenster für einen Wein abrufen

Query-Parameter:

  • lang — Sprachcode (de, en, fr, it)

Erklärung des Trinkfensters: Die Werte 'from' und 'to' geben Jahre nach dem Jahrgang an. Für einen 2020er Jahrgang mit from=5 und to=20: optimaler Trinkzeitraum ist 2025-2040. 

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/drinking-periods/106636?lang=en"

Beispiel-Antwort:

{
  "id": 42,
  "wine_id": 106636,
  "lang": "en",
  "from": 2020,
  "to": 2035,
  "statement": "This wine can be enjoyed now but will continue to improve over the next decade.",
  "young": "Vibrant dark fruit, firm tannins and a long finish.",
  "ripe": "Complex aromas of leather, tobacco and dried fruit with silky tannins.",
  "storage": "Store at 12-14°C in a dark place, bottles horizontal."
}

404 – generating-Flag: Wenn die Ressource existiert, aber der Inhalt in der angeforderten Sprache noch nicht verfügbar ist, löst die API im Hintergrund KI-Generierung aus und gibt 404 mit generating: true zurück. Bitte nach ~30 Sekunden erneut versuchen.

404-Antwort (generating: false – Ressource existiert nicht):

{ "error": "Drinking period not found for the specified language.", "generating": false }

404-Antwort (generating: true – KI-Generierung ausgelöst):

{ "error": "Drinking period not found for the specified language.", "generating": true }

Fotoanalyse (Enterprise)

*Nur für Enterprise-Kunden verfügbar.

POST /photo/analyze

Analysiere ein Weinetikett-Foto und finde passende Weine

Request Body (JSON):

  • photo * — Base64-kodiertes Bild (mit oder ohne data:image-Präfix)
  • max_results — Max. Kandidaten pro Etikett (Standard: 10, Max: 50)
curl -X POST \
     -H "Authorization: Bearer YOUR_ENTERPRISE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"photo": "data:image/jpeg;base64,/9j/4AAQ...", "max_results": 5}' \
     "https://api.grapeminds.eu/public/v1/photo/analyze"

Beispiel-Antwort:

{
  "message": "ok",
  "detected_labels": [
    {
      "producer_name": "Braunewell",
      "wine_name": "Teufelspfad Spätburgunder",
      "vintage": null,
      "color": "red",
      "region_name": "Rheinhessen",
      "country": "DE"
    }
  ],
  "candidates": [
    {
      "id": 106636,
      "display_name": "Weingut Braunewell, Teufelspfad Spätburgunder",
      "color": "red",
      "type": "wine",
      "sub_type": "still",
      "residual_sugar": "dry",
      "producer": { "id": 24860, "name": "Braunewell", "title": "Weingut" },
      "region": { "id": 187, "name": "Rheinhessen", "country": "DE" }
    }
  ]
}

Entwickler-Tools

Postman Collection

Lade die importfertige Postman Collection mit allen Endpunkten herunter.

KI & LLM-Integration

Maschinenlesbare Dokumentation für KI-Assistenten (wine-api-llms.txt).

Bereit loszulegen?

Teste die grapeminds Wine API kostenlos.

Als API Kunde registrieren