---
name: elabel-atlas
description: Search and retrieve public EU wine e-label records from e-label Atlas. Use when identifying a wine by name, producer, GTIN, or Atlas ID, checking ingredients, allergens, nutrition, or provenance, or synchronizing recently updated public e-label data.
---

# e-label Atlas

e-label Atlas is a provider-neutral directory of public EU wine e-label data. Use it to find a wine and read the public record supplied by its e-label provider. Treat Atlas as a discovery source, not as legal advice or a substitute for the producer's label.

## Choose an interface

- Prefer the Atlas MCP tools when they are available. Connect to https://www.elabel-atlas.eu/mcp using MCP Streamable HTTP.
- Use the REST equivalents under `https://www.elabel-atlas.eu/api/v1` when MCP is unavailable or the user needs a URL, script, or raw HTTP response.
- Public reads require no authentication. A bearer key with the `read:public` scope raises the rate limit. Never ask for or expose a key unless the user needs the keyed tier.

## Limits and pagination

Anonymous public operations allow 60 requests per minute per client address. A valid `read:public` key allows 600 requests per minute. REST responses report `x-ratelimit-limit`, `x-ratelimit-remaining`, and reset metadata. On HTTP 429, respect `retry-after` before retrying. Do not retry in a tight loop.

List and synchronization operations can return `next_cursor`. Pass that opaque value unchanged with the same filters to request the next page. Continue only while the task needs more records and a cursor is present.

## Workflows

### Find a wine and inspect its ingredients

1. Call `search_elabels` with the product name, producer name, or partial GTIN in `q`.
2. Compare the product identity and provider fields. Do not assume the first result is the intended wine when several vintages or variants match.
3. Call `get_elabel` with the selected `atlas_record_id`.
4. Read the `ingredients` array. Entries with `is_allergen: true` are declared allergens.

Example request: "Find Demo Wine Cooperative Grüner Veltliner 2025 and tell me its ingredients and allergens."

### Look up a bottle by barcode

1. Normalize the complete printed GTIN to digits only.
2. Call `lookup_elabel_by_gtin` with that GTIN.
3. If more than one record is returned, distinguish variants using the consumer product variant, lot, vintage, and product name. Report ambiguity instead of choosing silently.

REST example:

```sh
curl --fail --silent --show-error \
  "https://www.elabel-atlas.eu/api/v1/public-records/4006381333931"
```

### Synchronize changed records

1. Call `list_elabels_updated_since` with an ISO 8601 `updated_since` value and a practical page limit.
2. Save or process the returned records.
3. If `next_cursor` is present, call the tool again with the same `updated_since` and the cursor unchanged.
4. Use each record's `atlas_updated_at` as the server update time. Do not substitute a provider timestamp.

REST example:

```sh
curl --fail --silent --show-error \
  "https://www.elabel-atlas.eu/api/v1/public-records?updated_since=2026-09-01T00%3A00%3A00Z&limit=100"
```

## Record URLs and attribution

Use the returned canonical `record_url` when linking to a record. A record with a GTIN uses a GS1 Digital Link path. A record without a GTIN uses `/records/{atlas_record_id}`. Preserve provider attribution when presenting Atlas data. Terms are at https://www.elabel-atlas.eu/legal/terms and the data licence is at https://www.elabel-atlas.eu/legal/terms#data-licence.

Public records with a GTIN use a canonical path beginning `/01/{gtin14}`, followed by `/22/{consumer_product_variant}` and/or `/10/{lot}` when present. The REST `get_elabel` equivalent returns the `jsonld` Product projection directly when requested with `Accept: application/ld+json`. When present, `image_url` is Atlas's normalized public image asset.

## Generated operation reference

### `list_elabels_updated_since`

Use this to synchronize public e-label records changed after a known time. It returns records in stable update order with an optional continuation cursor.

REST equivalent: `GET https://www.elabel-atlas.eu/api/v1/public-records`.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `updated_since` | string | no | Exclusive Atlas server update time in ISO 8601 format. Offsets may use +HH:MM or +HHMM. Records updated exactly at this time are omitted. |
| `cursor` | string | no | Opaque next_cursor from the previous response. Keep all other filters unchanged while paging. |
| `limit` | integer | no | Maximum records to return, from 1 to 100. Defaults to 50. |
| `producer` | string | no | Exact producer name, matched case-insensitively. |
| `country` | string | no | Two-letter ISO 3166-1 alpha-2 country code, such as AT or FR. |
| `category` | string (one of: wine, sparkling, fortified, aromatised) | no | Product category: wine, sparkling, fortified, or aromatised. |
| `vintage` | integer | no | Four-digit vintage year from 1000 to 9999. |

#### Returns

- `records` (array of object).
- `next_cursor` (string or null).

### `lookup_elabel_by_gtin`

Use this when you have a complete GTIN. It returns every public e-label record that claims that identifier, with provider attribution.

REST equivalent: `GET https://www.elabel-atlas.eu/api/v1/public-records/{id}`.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | string | yes | An 8, 12, 13, or 14 digit GTIN including its check digit. |

#### Returns

- `gtin` (string).
- `records` (array of object).

### `get_elabel`

Use this to retrieve one public e-label after another Atlas tool returned its atlas_record_id. It returns the full record, source provider, attribution, and licence.

REST equivalent: `GET https://www.elabel-atlas.eu/api/v1/public-records/by-id/{id}`.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | string | yes | The atlas_record_id returned by a public record or search operation. |

#### Returns

- `atlas_record_id` (string).
- `atlas_updated_at` (string).
- `provider` (object).
- `licence` (string).
- `attribution` (string).
- `record_url` (string, optional).
- `image_url` (string, optional).
- `image_width` (integer, optional).
- `image_height` (integer, optional).
- `jsonld` (object, optional).

### `search_elabels`

Use this to find public wine e-labels by product name, producer, or GTIN fragment. Optional country, category, and vintage fields narrow the results.

REST equivalent: `GET https://www.elabel-atlas.eu/api/v1/search`.

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `q` | string | yes | A product name, producer, or GTIN to search for. |
| `country` | string | no | Two-letter ISO 3166-1 alpha-2 country code, such as AT or FR. |
| `category` | string (one of: wine, sparkling, fortified, aromatised) | no | Product category: wine, sparkling, fortified, or aromatised. |
| `vintage` | integer | no | Four-digit vintage year from 1000 to 9999. |
| `limit` | integer | no | Maximum records to return, from 1 to 50. Defaults to 25. |

#### Returns

- `query` (string).
- `records` (array of object).