Gebruik Atlas-data.

Snelstart

Stel de basis-URL eenmalig in en voer daarna een voorbeeld hieronder uit.

ATLAS_API=https://www.elabel-atlas.eu/api/v1

Authenticatie

Anonieme requests kunnen elk openbaar read-endpoint gebruiken. Een sleutel verhoogt de rate limit en is vereist voor write-operaties van aanbieders. Eigenaren en beheerders van aanbieder-workspaces kunnen een sleutel aanmaken in de ingelogde workspace onder API-sleutels. Heb je een leessleutel nodig zonder aanbieder-workspace, of bulktoegang, mail dan naar david@essentialcode.eu.

curl --fail --silent --show-error \
  -H "Authorization: Bearer $ATLAS_API_KEY" \
  "$ATLAS_API/public-records?limit=1"

Rate limits

Elke openbare operatie staat 60 anonieme requests per minuut per adres toe, of 600 per minuut per leessleutel. Responses bevatten limit-, remaining- en reset-headers. Een request boven de limiet geeft HTTP 429 terug:

HTTP/1.1 429 Too Many Requests
retry-after: 60
x-ratelimit-limit: 60
x-ratelimit-remaining: 0

{"error":{"code":"rate_limited","message":"The public API rate limit was exceeded."}}

Openbare read-endpoints

curl --fail --silent --show-error \
  "$ATLAS_API/search?q=Veltliner&limit=1"

{
  "query": "Veltliner",
  "records": [{
    "atlas_record_id": "QXSvIVqvHcRW-LjHtG88I",
    "name": "Grüner Veltliner 2025",
    "provider": { "name": "Demo Wine Cooperative" },
    "gtin": "4006381333931"
  }]
}

curl --fail --silent --show-error \
  "$ATLAS_API/public-records?limit=1"

{
  "records": [{
    "atlas_record_id": "ovPcoHyHMEbzdcGC_Zkm_",
    "name": "Grüner Veltliner Ried Steinberg 2024",
    "provider": { "name": "Glasswise" }
  }],
  "next_cursor": "eyJ1cGRhdGVkQXQiOjE3ODk1MDIxMjQ3MDcsImlkIjoib3ZQY29IeUhNRWJ6ZGNHQ19aa21fIn0"
}

curl --fail --silent --show-error \
  "$ATLAS_API/public-records/4006381333931"

{
  "gtin": "4006381333931",
  "records": [{
    "atlas_record_id": "QXSvIVqvHcRW-LjHtG88I",
    "name": "Grüner Veltliner 2025",
    "provider": { "name": "Demo Wine Cooperative" }
  }]
}

RECORD_ID=$(curl --fail --silent --show-error \
  "$ATLAS_API/public-records?limit=1" | jq -r '.records[0].atlas_record_id')
curl --fail --silent --show-error \
  "$ATLAS_API/public-records/by-id/$RECORD_ID"

{
  "atlas_record_id": "ovPcoHyHMEbzdcGC_Zkm_",
  "name": "Grüner Veltliner Ried Steinberg 2024",
  "provider": { "name": "Glasswise" },
  "atlas_updated_at": "2026-09-15T19:55:24.707Z"
}

Paginering

De openbare recordlijst geeft next_cursor terug als er een volgende pagina is. Stuur die exacte opaque waarde met dezelfde filters. Decodeer of wijzig hem niet.

CURSOR=$(curl --fail --silent --show-error \
  "$ATLAS_API/public-records?limit=1" | jq -r '.next_cursor')
curl --fail --silent --show-error \
  "$ATLAS_API/public-records?limit=1&cursor=$CURSOR"

Talen van openbare records

Openbare recordpagina's lokaliseren alleen Atlas-eigen labels en de codes die het E-Label Standard Format definieert, waaronder wijntype, wijneigenschappen, landcodes, nutriticodes en eenheden. Alle door de aanbieder geschreven tekst blijft exact zoals geleverd, inclusief ingrediëntnamen en -categorieën en alle verpakkings- of afvaltekst die de aanbieder schreef.

De eerste code in languages is altijd de primaire taal van het record, ook als Atlas de interface niet in die taal kan tonen. Een pagina biedt de primaire inhoud en ondersteunde talen met aanbiedervertalingen. Link naar een selectie met ?lang=de of ?lang=hr. Zonder parameter gebruikt Atlas Accept-Language als passende inhoud bestaat en redirect naar de bijbehorende deelbare URL.

Gebruik bij voorkeur gestructureerde ingredients[] om allergenen- en bio-vlaggen te behouden. Gebruik ingredients_text alleen als de aanbieder een complete declaratie in lopende tekst heeft. Aanbieders kunnen translations.{language}-waarden toevoegen voor ingredients_text, designation_of_origin en elke packaging[].disposal-instructie. De packaging-array volgt lengte en volgorde van de primaire lijst; gebruik null voor een instructie die moet terugvallen. Ontbrekende vertalingen vallen terug op de primaire top-levelwaarde. REST en MCP geven deze optionele map terug, en JSON-LD gebruikt taalgetagde waarden. Deze door de aanbieder geleverde map is de enige manier waarop aanbiedertekst tussen talen verandert.

De request body van de aanbieder volgt het E-Label Standard Format.

Op openbare pagina's rendert Atlas de eigen codes van de Standard (productType, color, sweetness, packagingGas, packagingType, materialType en collection) in de paginataal uit de gepubliceerde Standard-vocabulaire. Elke andere aanbiederwaarde blijft exact zoals geleverd.

MCP

Model Context Protocol, of MCP, is een standaardmanier voor een AI-client om externe tools aan te roepen. e-label Atlas biedt een anonieme Streamable HTTP-server op https://www.elabel-atlas.eu/mcp.

De server exposeert search_elabels, lookup_elabel_by_gtin, get_elabel en list_elabels_updated_since.

Installeer Atlas in een agent

Kies je client. De Claude Code-plugin en de Codex-setup bevatten zowel de Atlas-skillbegeleiding als de live MCP-tools. Andere clients verbinden met dezelfde read-only MCP-server.

claude plugin marketplace add https://www.elabel-atlas.eu/claude/marketplace.json && \
  claude plugin install elabel-atlas@elabel-atlas

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=e-label%20Atlas&connectorUrl=https%3A%2F%2Fwww.elabel-atlas.eu%2Fmcp

mkdir -p "$HOME/.agents/skills/elabel-atlas"
curl --fail --location   https://www.elabel-atlas.eu/api/v1/SKILL.md   --output "$HOME/.agents/skills/elabel-atlas/SKILL.md"
codex mcp add elabel-atlas --url https://www.elabel-atlas.eu/mcp

{
  "mcpServers": {
    "elabel-atlas": {
      "url": "https://www.elabel-atlas.eu/mcp"
    }
  }
}

{
  "mcpServers": {
    "elabel-atlas": {
      "httpUrl": "https://www.elabel-atlas.eu/mcp"
    }
  }
}