Usa i dati Atlas.

Avvio rapido

Imposta la base URL una volta, poi esegui qualsiasi esempio qui sotto.

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

Autenticazione

Le richieste anonime possono usare ogni endpoint pubblico di lettura. Una chiave alza il rate limit ed è necessaria per le operazioni di scrittura dei fornitori. Proprietari e amministratori di workspace fornitore possono creare una chiave nel workspace con accesso effettuato, sotto Chiavi API. Se ti serve una chiave di lettura senza un workspace fornitore o un accesso bulk, scrivi a david@essentialcode.eu.

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

Rate limit

Ogni operazione pubblica consente 60 richieste anonime al minuto per indirizzo, oppure 600 al minuto per chiave di lettura. Le risposte includono gli header limit, remaining e reset. Una richiesta oltre il limite restituisce HTTP 429:

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."}}

Endpoint pubblici di lettura

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"
}

Paginazione

La lista pubblica dei record restituisce next_cursor quando esiste un'altra pagina. Invia quel valore opaco esatto con gli stessi filtri. Non decodificarlo né modificarlo.

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"

Lingue dei record pubblici

Le pagine dei record pubblici localizzano solo le etichette di Atlas e i codici definiti dall'E-Label Standard Format, inclusi tipo di vino, proprietà del vino, codici paese, chiavi nutrizionali e unità. Ogni testo scritto dal fornitore resta esattamente come fornito, inclusi nomi e categorie degli ingredienti e qualsiasi testo su imballaggio o smaltimento scritto dal fornitore.

Il primo codice in languages è sempre la lingua primaria del record, anche quando Atlas non può rendere la sua interfaccia in quella lingua. Una pagina offre il contenuto primario e le lingue supportate che hanno traduzioni del fornitore. Collega a una selezione con ?lang=de o ?lang=hr. Senza parametro, Atlas usa Accept-Language quando esiste contenuto corrispondente e reindirizza all'URL condivisibile corrispondente.

Preferisci ingredients[] strutturati per preservare i flag allergeni e biologico. Usa ingredients_text solo quando il fornitore ha una dichiarazione in prosa completa. I fornitori possono aggiungere valori translations.{language} per ingredients_text, designation_of_origin e ogni istruzione packaging[].disposal. L'array packaging segue lunghezza e ordine della lista primaria; usa null per un'istruzione che deve ricadere sul valore primario. Le traduzioni mancanti ricadono sul valore primario di primo livello. REST e MCP restituiscono questa mappa opzionale, e JSON-LD usa valori con tag di lingua. Questa mappa fornita dal fornitore è l'unico modo in cui il testo del fornitore cambia tra le lingue.

Il body della richiesta del fornitore segue l'E-Label Standard Format.

Sulle pagine pubbliche Atlas rende i codici propri dello Standard (productType, color, sweetness, packagingGas, packagingType, materialType e collection) nella lingua della pagina dal vocabolario Standard pubblicato. Ogni altro valore del fornitore resta esattamente come fornito.

MCP

Model Context Protocol, o MCP, è un modo standard per un client di IA di chiamare strumenti esterni. e-label Atlas fornisce un server Streamable HTTP anonimo su https://www.elabel-atlas.eu/mcp.

Il server espone search_elabels, lookup_elabel_by_gtin, get_elabel e list_elabels_updated_since.

Installa Atlas in un agente

Scegli il tuo client. Il plugin di Claude Code e la configurazione di Codex includono sia la guida della skill Atlas sia gli strumenti MCP live. Gli altri client si collegano allo stesso server MCP in sola lettura.

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"
    }
  }
}