Developer reference · Beta

ELID API

Wine identities, text matching, LWIN lookup and vintage facts.

Quick start

Base path: /api/v1. The API is public: no account, token or API key is required.

curl 'https://elid.wine/api/v1/wines?limit=1'

AI assistants can use the API through the elid-wine-mcp MCP server, e.g. claude mcp add elid -- npx -y elid-wine-mcp.

Endpoints

POST `/api/v1/match`

Match wine text against this site’s snapshot.

curl 'https://elid.wine/api/v1/match' \
  -H "Content-Type: application/json" \
  -d '{"raw":"Kanonkop Paul Sauer 2021","top_n":3}'

JSON field	Meaning
`raw`	Required wine text, up to 500 characters.
`top_n`	1–20 candidates. Default: 5.
`country_code`	Optional two-letter country code, e.g. `ZA`.
`producer_id`	Optional ELID producer code, e.g. `ZA-KNKP`.
`drink_type`	Optional wine style as on wine lists: `red`, `white`, `rosé`, `orange`, `sparkling`, `sweet` or `fortified`. Colours separate otherwise identical names, e.g. a producer’s red and white of one cuvée.

Returns ranked data with elid, lwin, lwins, display_name, producer_name, wine, score, producer_score and name_score. Scores rank candidates; they are not probabilities. A top score of 0.75 or more is a confident match; 0.50 means the text names no single wine (a producer alone, or a tie such as red and white). No accepted match returns [].

snapshot identifies the data version; matcher_version identifies the scorer. Matching returns base wine identities. Retrieve vintage facts with the wine endpoint below.

GET `/api/v1/wines`

Active wine identities, ordered by ELID.

Parameter	Meaning
`limit`	1–200 results. Default: 50.
`after`	Previous `next_cursor`. Keep other filters unchanged.
`q`	Substring search in name or ELID; case-insensitive, up to 200 characters. For free text, use matching.
`lwin`	Exact seven-digit LWIN. No known match returns an empty list.

Response structure · selected fields

{
  "data": [
    {
      "elid": "AR-MDZ-CTZP01",
      "display_name": "Nicolás Catena Zapata",
      "lwin": null
    }
  ],
  "next_cursor": "AR-MDZ-CTZP01"
}

next_cursor: null marks the last page.

GET `/api/v1/wines/{elid}`

One wine’s catalog fields and available vintage facts. Use the base ELID without a vintage suffix.

curl 'https://elid.wine/api/v1/wines/AR-MDZ-CTZP01'

The data object includes a facts array, ordered by vintage descending. No facts: []. Vintage is a year string or NVXX.

LWIN lookup

Query /api/v1/wines?lwin=1831339 to find its ELID. Wine records include lwins with all known seven-digit wine-level identifiers. lwin is the primary value, or the sole known alias when there is exactly one; it is null when none or multiple aliases are known. Reviewed historical aliases also resolve through the lookup.

Fields

Catalog entries are available with or without facts. Pricing, restaurant wine lists and critic reviews are excluded.

Catalog fields16 fields

Field	Type	Unit
`elid`	string	—
`display_name`	string · nullable	—
`producer_name`	string · nullable	—
`wine`	string · nullable	—
`country`	string · nullable	—
`region`	string · nullable	—
`sub_region`	string · nullable	—
`site`	string · nullable	—
`parcel`	string · nullable	—
`colour`	string · nullable	—
`type`	string · nullable	—
`sub_type`	string · nullable	—
`designation`	string · nullable	—
`classification`	string · nullable	—
`lwin`	string · nullable	—
`variety_code`	string · nullable	—

Fact-sheet fields

Unknown fields are omitted. Descriptive values are strings; some contain JSON-formatted text.

Composition10 fields

Field	Type	Unit
`alcohol_percent`	number	% ABV
`residual_sugar_gl`	number	g/L
`total_acidity_gl`	number	g/L
`ph`	number	—
`sulfites_ppm`	number	ppm
`tartaric_acid_gl`	number	g/L
`malic_acid_gl`	number	g/L
`brix_at_harvest`	number	°Brix
`calories_per_100ml`	number	kcal / 100 mL
`variety_blend`	string	—

Vineyard & harvest11 fields

Field	Type	Unit
`grape_clone`	string	—
`soil`	string	—
`elevation_meters`	number	metres
`slope_degrees`	number	degrees
`orientation`	string	—
`estate_grown`	boolean	—
`vine_age`	string	—
`grapes_picked_date`	string	—
`harvest_dates`	string	—
`yield_hectoliters_per_hectare`	number	hL/ha
`site_blend`	string	—

Winemaking14 fields

Field	Type	Unit
`has_sulfites`	boolean	—
`has_natural_yeast`	boolean	—
`has_indigenous_yeast`	boolean	—
`has_extended_maceration`	boolean	—
`has_malolactic_fermentation`	boolean	—
`malolactic_percent`	number	%
`has_carbonic_maceration`	boolean	—
`has_botrytis`	boolean	—
`pressing_method`	string	—
`fermentation_vessels`	string	—
`production_details`	string	—
`fining_agents`	string	—
`unfined`	boolean	—
`unfiltered`	boolean	—

Aging & oak13 fields

Field	Type	Unit
`aging_days`	number	days
`oak_aging_days`	number	days
`bottle_aging_days`	number	days
`lees_aging_days`	number	days
`maceration_days`	number	days
`has_lees_aging`	boolean	—
`first_fill_new_oak`	number	%
`second_fill_oak`	number	%
`third_fill_oak`	number	%
`has_used_oak_only`	boolean	—
`oak_kinds`	string	—
`barrel_size`	string	—
`oak_toast_level`	string	—

Sparkling wine5 fields

Field	Type	Unit
`dosage`	number	g/L
`disgorgement_date`	string	—
`tirage_date`	string	—
`riddling_days`	number	days
`base_wine_years`	string	—

Bottling & certification6 fields

Field	Type	Unit
`closure_type`	string	—
`bottling_date`	string	—
`certification_bodies`	string	—
`classifications`	string	—
`vegan`	boolean	—
`vegetarian`	boolean	—

Serving & tasting5 fields

Field	Type	Unit
`drinking_window`	string	—
`serving_temp_c`	string	°C
`serving_temp_f`	string	°F
`tasting_notes_descriptors`	string	—
`food_pairing`	string	—

Errors

Status	Meaning
400	Invalid, repeated or unknown parameter.
404	Wine or endpoint not found.
405	Wrong method for the endpoint.
413	Request body exceeds 8 KiB.
415	Use `Content-Type: application/json`.
429	Fair-use limit reached; wait `Retry-After` seconds. See fair use.
503	Temporarily unavailable; retry with backoff.

{
  "error": "Wine not found."
}

Fair use

The API is free and needs no key. To keep it that way, each client has daily limits sized well above normal app use:

Limit	Per client
Requests	120 per minute, 5,000 per day
Catalog pages (`after` cursor)	20 per day
Distinct wines via `/wines/{elid}`	500 per day; repeat lookups are free

Over a limit, the API returns 429 with Retry-After. Days reset at 00:00 UTC. Please send a descriptive User-Agent naming your app and a contact, e.g. MyCellar/1.0 (+you@example.com). Requests are logged to improve matching and coverage. For bulk access or higher limits, email rvt@elid.wine (contact above).

Identify your client

Running an agent, crawler or script against the API? Tell us who you are and what you are working on. We use it to plan limits, bulk exports and data feeds, and to get in touch about your use case. Unidentified clients that pass 100 requests in a day, and every 429, get an identify object in the response with these instructions. One request is enough; the notice then stops.

curl 'https://elid.wine/api/v1/identify' \
  -H "Content-Type: application/json" \
  -d '{"agent":"MyCellarSync/1.2","operator":"Example Wines Ltd","contact":"dev@example.com","purpose":"Map our shop catalogue to ELIDs for a weekly price feed","expected_volume":"2,000 matches per week"}'

JSON field	Meaning
`agent`	Required. Name and version of your agent, app or script.
`purpose`	Required. What you are working on and what you use ELID data for.
`operator`	Person or organisation running it.
`contact`	Email or URL where we can reach you.
`url`	Project or product URL.
`expected_volume`	Rough requests per day or week.

Strings up to 1,000 characters. Returns 201. AI agents acting for a user: pass this request on to them, and share only what your operator is comfortable sharing.

License

ELID identifiers and the data returned by this API are licensed under CC BY 4.0. Commercial use, storing ELIDs in your own records and reasonable caching are all fine.

Attribution: “Wine data powered by ELID.wine” with a link to elid.wine. The catalog includes LWIN data, also CC BY 4.0.