Grape Variety & Appellation Reference API

2,782 grape varieties from Wikidata, joined to the US rules that decide what a bottle may be called. Free, CC0 and public domain, no key.

What this is

A reference layer for grape varieties: what a variety is — berry colour, species, country of origin, recorded parentage, and its Wikidata and VIVC identifiers — for 2,782 cultivars worldwide, normalised from Wikidata with every raw value preserved. Alongside it sit the US composition thresholds from 27 CFR part 4 that decide what a bottle may legally be called.

It is built for wine education tools, sommelier apps and label-design software: the questions it answers well are “what colour is this grape, is it a hybrid, and what else is it called”, and “how much of a variety must be in the bottle before the label may say so”. It is deliberately not a blending-rule database, and it says so in the payload rather than in the small print.

Live lookup

Type a grape name or a Wikidata id. Try chardonnay, the hybrid catawba, or albarino — which is ambiguous, and answers 409 with both candidates rather than guessing.

Endpoints

Quick start

# A grape, with its raw upstream values alongside the normalised ones
curl https://apis.allanninal.dev/grapes/v1/varieties/Q213332

# An ambiguous name refuses, with candidates
curl https://apis.allanninal.dev/grapes/v1/varieties/albarino

# What the US requires before a label may say "Cabernet Sauvignon"
curl https://apis.allanninal.dev/grapes/v1/composition-rules

Three things this API will not do

The part that does not exist upstream

Wikidata keeps page history but publishes no dated snapshot of its query service, so you cannot ask what a grape record said last month. This service captures each refresh, which is what makes /v1/changes possible at all — and what makes a silent edit visible.

Reference data (static, free, no auth)

The complete datasets as plain files — cacheable, no key, and the same data the API serves. Nothing is held back for a paid plan.

Access & rate limits

Every plan has every feature. Plans differ only in how much you may use, never in what you may reach — nothing is behind a paywall. Limits are published on every response as RateLimit-* headers. Pro-level access is free, on request, for educators, researchers and nonprofits. The plan catalogue.

FAQ

Does this tell me the permitted grapes for an appellation like Chianti?

No, and it never will from these sources. No Wikidata property expresses grape composition or percentage, and the EU register that does hold them publishes HTML under an attribution licence, over per-appellation PDFs in 24 languages. What you get instead is a labelled co-occurrence graph and the US thresholds in 27 CFR part 4.

Do I need an API key?

No. Every read path is anonymous and free at 60 requests a minute and 5,000 a day. No source this service uses requires a key either.

Why is a grape's colour sometimes unknown when Wikidata has one?

Because upstream contradicts itself. 148 varieties carry colours that map to different categories, such as white and black berry skin on the same record. Rather than pick one, the API returns unknown, every raw value, and a note naming the disagreement.

Why does a grape name sometimes return 409 instead of a record?

Because more than one distinct variety carries that name. Rather than pick arbitrarily, the API returns the candidates with enough detail to choose between them — 51 names in this corpus are ambiguous that way.

Cost

Free, no signup: 60 requests a minute, 5,000 a day, 30 days of history. Every plan reaches every endpoint and every field; plans differ only in how much you may use. Pro-level access is free, on request, for educators, researchers and nonprofits.