Endpoint Index

All available API endpoints at a glance. Every endpoint requires authentication via Bearer token.

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

We maintain ready-to-use code examples for popular languages on GitHub: github.com/grapeminds/api-examples

Test Endpoint

GET /ping

Verify your API key is valid and your connection is working

Use this as your first call when setting up your integration. It confirms your API key works correctly without consuming any budget on real data.

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

Example Response:

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

Wines Endpoints

GET /wines

List all wines with pagination and filters

Query Parameters:

  • page — Page number (default: 1)
  • per_page — Items per page (default: 15, max: 100)
  • color — Filter by color (red, white, rose)
  • sub_type — Filter by type (still, sparkling)
  • producer_id — Filter by producer ID
  • region_id — Filter by region ID
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://grapeminds.eu/api/public/v1/wines?color=red&per_page=20"

Example Response:

{
  "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 },
  "links": { "first": "...?page=1", "last": "...?page=10", "prev": null, "next": "...?page=2" }
}
GET /wines/search

Search wines by name or producer

Query Parameters:

  • q — Search query (min 3 characters, required)
  • limit — Max results (default: 20, max: 100)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://grapeminds.eu/api/public/v1/wines/search?q=Braunewell"

Example Response:

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

Get detailed wine information

Headers:

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

Example Response:

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

Producers Endpoints

GET /producers

List all producers with pagination

Query Parameters:

  • search — Search by name (min 2 characters)
  • per_page — Items per page (default: 15, max: 100)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://grapeminds.eu/api/public/v1/producers?search=Braunewell"

Example Response:

{
  "data": [
    { "id": 24860, "name": "Braunewell", "title": "Weingut" }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 15, "total": 1, "from": 1, "to": 1 },
  "links": { "first": "...?page=1", "last": "...?page=1", "prev": null, "next": null }
}
GET /producers/{id}

Get producer details with optional wines

Response Fields:

  • title — Producer prefix (e.g. "Weingut", "Château", "Domaine"), may be null
  • display_name — Full computed name (title + name)

Query Parameters:

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

Example Response:

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

List all regions with pagination

Query Parameters:

  • country — Filter by country code
  • search — Search by name

Headers:

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

Example Response:

{
  "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" },
  "links": { "first": "...?page=1", "last": "...?page=2", "prev": null, "next": "...?page=2" }
}
GET /regions/{id}

Get region details with optional wines

Query Parameters:

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

Example Response:

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

Get detailed insights for a wine region

Query Parameters:

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

Example Response:

{
  "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: If the resource exists but no content is available in the requested language, the API triggers AI generation in the background and returns 404 with generating: true. Retry after ~30 seconds.

404 Response (generating: false – resource does not exist):

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

404 Response (generating: true – AI generation triggered):

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

Drinking Periods Endpoint

GET /drinking-periods/{wineId}

Get optimal drinking window for a wine

Query Parameters:

  • lang — Language code (de, en, fr, it)

Understanding the drinking window: The 'from' and 'to' values indicate years after vintage. For a 2020 vintage with from=5 and to=20: optimal drinking is 2025-2040. 

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

Example Response:

{
  "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: If the resource exists but no content is available in the requested language, the API triggers AI generation in the background and returns 404 with generating: true. Retry after ~30 seconds.

404 Response (generating: false – resource does not exist):

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

404 Response (generating: true – AI generation triggered):

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

Photo Analysis (Enterprise)

*Only available for Enterprise customers.

POST /photo/analyze

Analyze a wine label photo and find matching wines

Request Body (JSON):

  • photo * — Base64 encoded image (with or without data:image prefix)
  • max_results — Max candidates per label (default: 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://grapeminds.eu/api/public/v1/photo/analyze"

Example Response:

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

Developer Tools

Postman Collection

Download the ready-to-import Postman collection with all endpoints.

AI & LLM Integration

Machine-readable docs for AI assistants (wine-api-llms.txt).

Ready to get started?

Try the grapeminds Wine API free for 14 days.

Register as API customer