Indice degli endpoint

Tutti gli endpoint API a colpo d'occhio. Ogni endpoint richiede autenticazione tramite Bearer token.

URL base: https://api.grapeminds.eu/public/v1

Manteniamo esempi di codice pronti all'uso per i linguaggi più diffusi su GitHub: github.com/grapeminds/api-examples

Endpoint di test

GET /ping

Verifica che la tua chiave API sia valida e che la connessione funzioni

Usa questo come prima chiamata quando configuri la tua integrazione. Conferma che la tua chiave API funziona correttamente senza consumare budget su dati reali.

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

Risposta di esempio:

{
  "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"
}

Endpoint Vini

GET /wines

Elenca tutti i vini con paginazione e filtri

Parametri Query:

  • page — Numero di pagina (predefinito: 1)
  • per_page — Elementi per pagina (predefinito: 15, max: 100)
  • color — Filtra per colore (rosso, bianco, rosato)
  • sub_type — Filtra per tipo (fermo, spumante)
  • producer_id — Filtra per ID produttore
  • region_id — Filtra per ID regione
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/wines?color=red&per_page=20"

Risposta di esempio:

{
  "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

Cerca vini per nome o produttore

Parametri Query:

  • q — Query di ricerca (min 3 caratteri, obbligatorio)
  • limit — Risultati massimi (predefinito: 20, max: 100)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/wines/search?q=Braunewell"

Risposta di esempio:

{
  "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}

Ottieni informazioni dettagliate sul vino

Headers:

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

Risposta di esempio:

{
  "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
  }
}

Endpoint Produttori

GET /producers

Elenca tutti i produttori con paginazione

Parametri Query:

  • search — Cerca per nome (min 2 caratteri)
  • per_page — Elementi per pagina (predefinito: 15, max: 100)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/producers?search=Braunewell"

Risposta di esempio:

{
  "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}

Ottieni dettagli produttore con vini opzionali

Campi di risposta:

  • title — Prefisso del produttore (es. "Weingut", "Château", "Domaine"), può essere null
  • display_name — Nome completo calcolato (titolo + nome)

Parametri Query:

  • include_wines — Includi vini (boolean, predefinito: false)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/producers/24860?include_wines=true"

Risposta di esempio:

{
  "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
  }
}

Endpoint Regioni

GET /regions

Elenca tutte le regioni con paginazione

Parametri Query:

  • country — Filtra per codice paese
  • search — Cerca per nome

Headers:

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

Risposta di esempio:

{
  "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}

Ottieni dettagli regione con vini opzionali

Parametri Query:

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

Risposta di esempio:

{
  "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}

Ottieni informazioni dettagliate su una regione vinicola

Parametri Query:

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

Risposta di esempio:

{
  "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 – flag generating: Se la risorsa esiste ma il contenuto non è ancora disponibile nella lingua richiesta, l'API avvia la generazione IA in background e restituisce 404 con generating: true. Riprovare dopo ~30 secondi.

Risposta 404 (generating: false – risorsa inesistente):

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

Risposta 404 (generating: true – generazione IA avviata):

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

Endpoint Periodo di bevibilità

GET /drinking-periods/{wineId}

Ottieni la finestra di bevibilità ottimale per un vino

Parametri Query:

  • lang — Codice lingua (de, en, fr, it)

Comprensione della finestra di consumo: I valori 'from' e 'to' indicano anni dopo l'annata. Per un'annata 2020 con from=5 e to=20: bevibilità ottimale dal 2025 al 2040. 

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

Risposta di esempio:

{
  "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 – flag generating: Se la risorsa esiste ma il contenuto non è ancora disponibile nella lingua richiesta, l'API avvia la generazione IA in background e restituisce 404 con generating: true. Riprovare dopo ~30 secondi.

Risposta 404 (generating: false – risorsa inesistente):

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

Risposta 404 (generating: true – generazione IA avviata):

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

Analisi foto (Enterprise)

*Disponibile solo per i clienti Enterprise.

POST /photo/analyze

Analizza una foto dell'etichetta del vino e trova i vini corrispondenti

Corpo della richiesta (JSON):

  • photo * — Immagine codificata in Base64 (con o senza prefisso data:image)
  • max_results — Candidati max. per etichetta (predefinito: 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"

Risposta di esempio:

{
  "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" }
    }
  ]
}

Strumenti per sviluppatori

Collezione Postman

Scarica la collezione Postman pronta per l'importazione con tutti gli endpoint.

Integrazione IA & LLM

Documentazione leggibile dalle macchine per assistenti IA (wine-api-llms.txt).

Pronti per iniziare?

Prova gratuitamente l'API Wine di grapeminds.

Registrati come cliente API