API Documentation

X-API-Key: your-api-key-here

Look up a single product by EAN/UPC barcode.

Parameters

Name	In	Type	Description
code required	path	string	EAN/UPC barcode (8–14 digits)
lang optional	query	string	ISO language code (default: "en")

Example — curl

curl -H "X-API-Key: your-key" \
     "http://localhost:5100/api/v1/ean/5449000000439?lang=en"

Example — Python

import requests

resp = requests.get(
    "http://localhost:5100/api/v1/ean/5449000000439",
    headers={"X-API-Key": "your-key"},
    params={"lang": "pl"},
)
product = resp.json()
print(product["name"])  # "Coca-Cola Classic 330ml"

Example — JavaScript

const resp = await fetch(
    "http://localhost:5100/api/v1/ean/5449000000439?lang=en",
    { headers: { "X-API-Key": "your-key" } }
);
const product = await resp.json();
console.log(product.name);

Example — C# (.NET)

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your-key");

var resp = await client.GetAsync(
    "http://localhost:5100/api/v1/ean/5449000000439?lang=en"
);
var json = await resp.Content.ReadAsStringAsync();

Response (200)

{
  "ean": "5449000000439",
  "name": "Coca-Cola Classic 330ml",
  "brand": "Coca-Cola",
  "category": "Beverages",
  "image_url": "https://images.openfoodfacts.org/...",
  "source": "cache",
  "confidence": 0.95
}

Error (404)

{ "detail": "Product not found for EAN: 0000000000000" }

Batch lookup for multiple EAN codes (max 50 per request).

Request Body

{
  "codes": ["5449000000439", "4006381333931", "0000000000000"],
  "lang": "en"
}

Response (200)

{
  "results": [
    { "ean": "5449000000439", "name": "Coca-Cola", ... },
    { "ean": "4006381333931", "name": "Nivea Creme", ... },
    null
  ],
  "found": 2,
  "not_found": 1
}

Full-text search in the product database by name or brand.

Parameters

Name	In	Type	Description
q required	query	string	Search query (min 2 chars)
brand optional	query	string	Filter by brand
category optional	query	string	Filter by category
lang optional	query	string	Language (default: "en")
limit optional	query	int	Results per page (1–100, default: 20)
offset optional	query	int	Pagination offset (default: 0)

Example

curl -H "X-API-Key: your-key" \
     "http://localhost:5100/api/v1/search?q=coca+cola&limit=5"

Register a new API key (free plan). No authentication required.

Request Body

{ "email": "you@example.com" }

Response (200)

{
  "api_key": "a1b2c3d4e5f6...",
  "plan": "free",
  "daily_limit": 100,
  "message": "API key created successfully."
}

Get usage statistics for your API key.

Response (200)

{
  "plan": "free",
  "daily_limit": 100,
  "requests_today": 42,
  "requests_remaining": 58,
  "total_requests": 1337,
  "top_endpoints": [
    { "endpoint": "/api/v1/ean/{code}", "count": 1200 }
  ]
}

Every response includes rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 2026-02-18

When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Code	Meaning
400	Bad request (invalid parameters)
401	Missing or invalid API key
403	API key expired or insufficient permissions
404	Product not found
409	Conflict (e.g., email already registered)
429	Rate limit exceeded
500	Internal server error