Developer reference · Beta

ELID API

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

Quick start

Base path: /api/v1. Authenticate with a bearer token.

curl 'https://elid.wine/api/v1/wines?limit=1' \
  -H "Authorization: Bearer $ELID_API_TOKEN"

Endpoints

POST `/api/v1/match`

Match wine text against this site’s snapshot.

curl 'https://elid.wine/api/v1/match' \
  -H "Authorization: Bearer $ELID_API_TOKEN" \
  -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`.

Returns ranked data with elid, lwin, display_name, producer_name, wine, score, producer_score and name_score. Scores rank candidates; they are not probabilities. 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' \
  -H "Authorization: Bearer $ELID_API_TOKEN"

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 also include lwin as a string, or null when unknown. Only seven-digit wine-level LWINs are supported.

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.
401	Missing, invalid or revoked token.
404	Wine or endpoint not found.
405	Wrong method for the endpoint.
413	Request body exceeds 8 KiB.
415	Use `Content-Type: application/json`.
503	Temporarily unavailable; retry with backoff.

{
  "error": "A valid bearer token is required."
}