API Documentation

Complete reference for the Burgundata terroir intelligence API.

Authentication

Bearer token

All authenticated endpoints require a Bearer token in the Authorization header. Get your API key from the dashboard after signing up.

curl

curl https://burgundata.com/v1/appellations \
  -H "Authorization: Bearer YOUR_API_KEY"

Public endpoints (stats, classifications, villages, geology) do not require authentication.

Rate limiting

Limits and headers

Every response includes rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1710720000

Tier	Daily limit
Free	100 requests/day
Developer	Credit balance ($0.02/query)

When the limit is exceeded, the API returns a 429 status:

{
  "error": "rate_limit_exceeded",
  "message": "Daily request limit exceeded. Resets at midnight UTC.",
  "retry_after": 3600
}

Endpoints

GET /v1/stats public

Returns high-level counts for the entire dataset.

curl

curl https://burgundata.com/v1/stats

{
  "vineyard_plots": 3172,
  "appellations": 760,
  "villages": 72,
  "producers": 47
}

GET /v1/classifications public

Returns the Burgundy classification hierarchy: Grand Cru, Premier Cru, Village, and Regional levels.

curl

curl https://burgundata.com/v1/classifications

[
  {
    "level": "grand_cru",
    "count": 33,
    "description": "The highest classification in Burgundy"
  },
  {
    "level": "premier_cru",
    "count": 635,
    "description": "Named vineyard sites of recognised quality"
  }
]

GET /v1/villages public

Lists all 72 villages with summary information including appellation counts and location.

curl

curl https://burgundata.com/v1/villages

Parameter	Type	Description
region	string	Filter by region (e.g. cote-de-nuits)
limit	integer	Number of results (default 20, max 100)
offset	integer	Pagination offset

[
  {
    "name": "Gevrey-Chambertin",
    "slug": "gevrey-chambertin",
    "region": "Côte de Nuits",
    "appellation_count": 26
  }
]

GET /v1/geology public

Returns geological formation types found across Burgundy's vineyards.

curl

curl https://burgundata.com/v1/geology

[
  {
    "formation": "Bajocian limestone",
    "period": "Middle Jurassic",
    "appellation_count": 84
  }
]

GET /v1/appellations authenticated

Returns a paginated list of all appellations with filtering options.

curl

curl https://burgundata.com/v1/appellations \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameter	Type	Description
village	string	Filter by village slug
classification	string	Filter by level (grand_cru, premier_cru, village, regional)
limit	integer	Number of results (default 20, max 100)
offset	integer	Pagination offset

{
  "total": 760,
  "results": [
    {
      "name": "Les Champeaux",
      "slug": "gevrey-chambertin-les-champeaux",
      "classification": "premier_cru",
      "village": "Gevrey-Chambertin"
    }
  ]
}

GET /v1/appellations/{slug} authenticated

Returns full detail for a single appellation including spatial, geological, and topographic data.

curl

curl https://burgundata.com/v1/appellations/gevrey-chambertin-les-champeaux \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "appellation": "Gevrey-Chambertin",
  "classification": "premier_cru",
  "climat": "Les Champeaux",
  "elevation_metres": 301.5,
  "slope_degrees": 6.6,
  "aspect": "northwest",
  "geological_match": true,
  "land_value_ratio_to_grand_cru": 0.25
}

GET /v1/appellations/{slug}/similar authenticated

Finds appellations with similar terroir characteristics: geology, elevation, slope, and spatial proximity.

curl

curl https://burgundata.com/v1/appellations/gevrey-chambertin-les-champeaux/similar \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameter	Type	Description
limit	integer	Number of results (default 5, max 20)

[
  {
    "name": "Cazetiers",
    "similarity_score": 0.92,
    "shared_geology": true,
    "elevation_diff_metres": 4.2
  }
]

GET /v1/producers authenticated

Returns a paginated list of producer profiles with generational depth and appellation coverage.

curl

curl https://burgundata.com/v1/producers \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameter	Type	Description
village	string	Filter by village slug
limit	integer	Number of results (default 20, max 100)
offset	integer	Pagination offset

[
  {
    "id": 1,
    "name": "Domaine Example",
    "village": "Gevrey-Chambertin",
    "generations": 5
  }
]

GET /v1/producers/{id} authenticated

Returns a full producer profile including winemaking philosophy, mentor lineage, and appellation holdings.

curl

curl https://burgundata.com/v1/producers/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": 1,
  "name": "Domaine Example",
  "village": "Gevrey-Chambertin",
  "generations": 5,
  "philosophy": "Traditional Burgundian methods with minimal intervention",
  "appellations": [
    "Gevrey-Chambertin Les Champeaux",
    "Chambertin"
  ]
}

GET /v1/producers/graph authenticated

Producer network graph — mentor/student, peer, and village connections between profiled domaines.

Parameters

Param	Type	Description
producer_id	integer	Filter connections involving a specific producer (optional)

curl https://burgundata.com/v1/producers/graph \
  -H "Authorization: Bearer burg_sk_..."

{
  "data": {
    "nodes": [
      { "id": 6, "name": "Alvina Pernot", "village": "Puligny-Montrachet" },
      { "id": 19, "name": "Leflaive", "village": "Puligny-Montrachet" }
    ],
    "edges": [
      { "from_id": 6, "to_id": 19, "relationship": "trained_under", "evidence": "Trained under a Leflaive-adjacent approach..." }
    ]
  }
}

Tier comparison

Free vs Developer

Feature	Free	Developer ($0.02/query)
Rate limit	25 calls/day	Credit balance
Appellation directory	Yes	Yes
Village summaries	Yes	Yes
Classification hierarchy	Yes	Yes
Formation reference	Yes	Yes
Spatial proximity	—	Yes
Geological matching	—	Yes
Topographic profiles	—	Yes
Land valuations	—	Yes
Producer intelligence	—	Yes

Errors

Error format

All errors return a consistent JSON structure:

{
  "error": "error_type",
  "message": "Human-readable description of what went wrong."
}

Status	Type	Description
400	bad_request	Invalid query parameters or malformed request
401	unauthorized	Missing or invalid API key
403	forbidden	Endpoint not available on your tier
404	not_found	Resource does not exist
429	rate_limit_exceeded	Daily request limit exceeded
500	internal_error	Unexpected server error

MCP

Model Context Protocol

Burgundata exposes an MCP server via Server-Sent Events (SSE) for integration with AI assistants and language models.

SSE endpoint

https://burgundata.com/mcp/sse

Registering in your client

Add Burgundata as an MCP server in your AI client configuration. The SSE transport requires no additional setup — connect to the endpoint and the server will stream available tools.

          JSON
          MCP client config
        

{
  "mcpServers": {
    "burgundata": {
      "transport": "sse",
      "url": "https://burgundata.com/mcp/sse"
    }
  }
}

Once connected, the MCP server exposes all Burgundata API endpoints as callable tools with full schema descriptions. Your AI assistant can then query vineyard data, find similar appellations, and retrieve producer profiles directly.