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

Le risposte sui vini includono lwin quando è disponibile un Liv-ex Wine Identification Number.

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,
      "lwin": "1234567",
      "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,
      "lwin": "1234567",
      "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, es, fr, it, da, pt, sv, nl)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept-Language: de" \
     "https://api.grapeminds.eu/public/v1/wines/106636"

Risposta di esempio:

{
  "id": 106636,
  "lwin": "1234567",
  "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", "color": "white", "producer_id": 24860, "residual_sugar": null },
      { "id": 106636, "display_name": "Teufelspfad Spätburgunder", "color": "red", "producer_id": 24860, "residual_sugar": "dry" }
    ],
    "wines_count": 5
  }
}
GET /producer-insights/{producerId}

Ottenere l’introduzione e i dati aziendali che abbiamo su un produttore di vino

Parametri Query:

  • lang — Codice lingua (de, en, es, fr, it, da, pt, sv, nl)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/producer-insights/1234?lang=en"

Risposta di esempio:

{
  "producer_id": 1234,
  "lang": "en",
  "introduction": "Josmeyer is a family-run estate in Wintzenheim in Alsace, founded in 1854...",
  "insights": {
    "country_code": "FR",
    "city": "Wintzenheim",
    "lat": 48.0631,
    "lng": 7.2856,
    "founded_year": 1854,
    "hectares": 30.0,
    "annual_production_bottles": null,
    "organic_certified": true,
    "biodynamic_certified": true,
    "certifications": ["Demeter"],
    "website_url": "https://www.josmeyer.com",
    "instagram_url": null,
    "has_ecommerce": null
  }
}

Un campo null significa che non disponiamo di quel dato, mai che la risposta sia no. insights è null finché non sono stati accertati dati aziendali per questo produttore.

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": "Producer insight not found for the specified language.", "generating": false }

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

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

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, es, fr, it, da, pt, sv, nl)
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, es, fr, it, da, pt, sv, nl)
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, es, fr, it, da, pt, sv, nl)

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"
    }
  ],
  "match": {
    "status": "matched",
    "confidence": 96,
    "candidate_id": 106636,
    "candidates_count": 1
  },
  "candidates": [
    {
      "id": 106636,
      "display_name": "Weingut Braunewell, Teufelspfad Spätburgunder",
      "match_confidence": 96,
      "color": "red",
      "type": "wine",
      "sub_type": "still",
      "residual_sugar": "dry",
      "producer": { "id": 24860, "name": "Braunewell", "title": "Weingut" },
      "region": { "id": 187, "name": "Rheinhessen", "country": "DE" }
    }
  ]
}

Risoluzione della corrispondenza

L’oggetto match consente ai client di distinguere una corrispondenza affidabile da un risultato ambiguo o da nessuna corrispondenza nel database.

  • matched: è stato trovato un miglior candidato chiaro.
  • ambiguous: sono stati trovati candidati, ma il miglior risultato non è chiaramente separato dalle alternative.
  • not_found: non è stata rilevata alcuna etichetta oppure non è stato trovato alcun candidato nel database.
  • match.confidence: punteggio deterministico da 0-100 basato sul testo dell’etichetta rilevata e sul nome visualizzato del candidato.
  • match.candidate_id: ID del miglior candidato quando esistono candidati, altrimenti null.
  • match.candidates_count: numero di candidati restituiti considerati per la risoluzione.
  • candidates[].match_confidence: punteggio di corrispondenza testuale da 0-100 specifico del candidato.

Licenza di archiviazione permanente

Acquisire una licenza di archiviazione permanente per un dataset di vino. Una volta concessa la licenza, il dataset può essere archiviato in modo permanente e utilizzato commercialmente senza limitazioni di tempo.

Richiede un abbonamento API attivo e l'accettazione dei Termini di licenza commerciale dei dataset nel tuo dashboard API.
POST /licence/{wine_id}

Acquisire una licenza di archiviazione permanente per un dataset di vino.

Parametri percorso:

  • wine_id * — L'ID numerico del dataset vino da concedere in licenza.
curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.grapeminds.eu/public/v1/licence/9146"

Risposta di esempio (201 – Nuova licenza):

{
  "message": "Licensed.",
  "wine_id": 9146,
  "licensed_at": "2025-06-01T12:00:00.000000Z"
}

Risposta di esempio (200 – Già concesso in licenza):

{
  "message": "Already licensed.",
  "wine_id": 9146,
  "licensed_at": "2025-05-15T08:30:00.000000Z"
}

Ogni licenza viene fatturata come evento di utilizzo misurato sul tuo abbonamento attivo. Puoi visualizzare tutti i dataset concessi in licenza e accettare i termini richiesti nel tuo Dashboard API.

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