# upc.dev — Product Intelligence API

## What this site does
upc.dev is a product intelligence platform that indexes over ten million canonical products aggregated from dozens of authoritative sources across regulatory, open-data, marketplace, and first-party categories. Enter any UPC, EAN, or GTIN barcode and receive a consolidated view of what that product is, who makes it, how safe it is, where it is sold, and what it has historically cost. The platform exposes data through a REST API, a public website with rich structured data, an MCP server for agent tool calling, and machine-readable discovery endpoints including this file.

## Key pages
- Homepage: https://upc.dev/
- Product lookup: https://upc.dev/product/{upc} (e.g. https://upc.dev/product/049000042566)
- Brand directory: https://upc.dev/brand/{slug} (e.g. https://upc.dev/brand/coca-cola)
- Category directory: https://upc.dev/category/{slug} (e.g. https://upc.dev/category/beverages)
- Barcode validator: https://upc.dev/check (free, no API key needed)
- GS1 prefix lookup: https://upc.dev/prefix/{code} (owner, country, validity range)
- Country products: https://upc.dev/country/{slug}
- Brand comparison: https://upc.dev/compare/{brand1}-vs-{brand2}
- Database stats: https://upc.dev/stats

## REST API
Base URL: https://upc.dev or https://api.upc.dev. All endpoints return JSON with a top-level { "ok": bool } envelope. Authentication via X-API-Key header. Free-tier keys allow 100 requests per day; paid tiers lift the limit to 10,000 or 100,000 per day with access to additional endpoints.

- GET /v1/product/{upc} — Canonical product: name, brand, category, description, ingredients, nutrition, image URL, country of origin, confidence band, and safety recalls. This is the primary endpoint for barcode-to-product resolution.
- GET /v1/search?q={query}&limit={n} — Full-text search across products by name, brand, category, or description. Returns a ranked list of matches. Use when you have text instead of a barcode.
- GET /v1/mx/{barcode} — Barcode intelligence: validates the check digit, decodes the GS1 company prefix to a country and brand, returns an authenticity score. Does not resolve the product — use /v1/product for that.
- GET /v1/signals/{upc}?days={n} — Time-series signals: price changes, recalls, regulatory actions, and complaint volume over the specified window.
- GET /v1/changes/{upc} — Field-level change log with old and new values.
- GET /v1/catalogs/aggregate/pricing?upc={upc} — Wholesale cost distribution (min, median, max unit cost with sample size).
- GET /v1/stats — Database-wide statistics including product counts, source coverage, and enrichment rates.
- POST /v1/auth/register — Create an API key by email.
- GET /openapi.json — Full OpenAPI 3.1 specification with schemas for Product, Claim, Signal, Recall, and more.
- GET /docs/api — Human-readable API reference rendered from the OpenAPI spec.

## MCP server
upc.dev speaks the Model Context Protocol in two transports. Stdio: run the local MCP server for use with Claude Desktop, Claude Code, and similar clients. Streamable HTTP: POST to https://upc.dev/mcp (or https://mcp.upc.dev/mcp) with an initialize request and replay the Mcp-Session-Id on subsequent calls.

Available tools: resolve_upc (canonical product by barcode), explain_gtin (structural decode and check-digit validation), check_recall (safety and recall data), compare_gtin (side-by-side comparison), aggregate_wholesale (cost distribution), claim_corrections (submit or list corrections), upc_search (free-text search), upc_signals (signal history), upc_risk (risk score), upc_recommendation (buy/watch/avoid verdict), upc_watch (set alerts for price drops, recalls, or stock changes).

## Confidence bands
Every canonical product carries a confidence_band field: "high", "medium", "low", or "unverified". Agents should always inspect this field before quoting a value. Prefer high and medium band products, and explicitly caveat low and unverified rows when surfacing data to end users. The scoring methodology is an implementation detail — treat the band itself as the authoritative signal.

## Data coverage
Over ten million canonical products are indexed and deduplicated across four source categories: regulatory (government safety and recall feeds), open-data (community-contributed product databases), marketplace (retail and resale catalog surfaces), and first-party (brand and distributor direct contributions). Products carry a claim-count and a last-verified timestamp so agents can assess freshness. Safety recalls are sourced from regulatory feeds and surfaced on every product lookup.

## Structured data
All product pages include JSON-LD structured data blocks: Product (with GTIN12, GTIN13, brand, offers, safety), BreadcrumbList, FAQPage, and Answer. Brand and category pages carry Dataset JSON-LD. Pages are server-side rendered with Cache-Control headers (public, max-age=3600, s-maxage=86400) so crawlers hit the edge cache rather than the origin.

## Discovery endpoints
- /.well-known/agent.json — agent discovery metadata
- /.well-known/ai-plugin.json — ChatGPT plugin manifest
- /.well-known/mcp.json — MCP server discovery
- /openapi.json — OpenAPI 3.1 specification
- /llms.txt — this file (short-form)
- /llms-full.txt — extended companion document (2,000+ words)
- /sitemap.xml — sitemap index with segmented product, brand, category, and page shards

## Suggested queries
- What product has UPC 049000042566?
- Is the product with barcode 8801234567890 recalled?
- Compare Coca-Cola Classic (049000042566) vs Pepsi (012000001086)
- What is the wholesale price range for UPC 038000138416?
- Show me all beverages from brand Coca-Cola
- What country does the barcode prefix 880 belong to?
- Is the check digit valid for EAN 4006381333931?
- What has changed for product 049000042566 in the last 30 days?
- What is the risk score for UPC 038000138416?
- Search for "organic oat milk" products

## Rate limits and caching
Free-tier API keys allow 100 requests per day, resetting at midnight UTC. A 429 response carries Retry-After and X-RateLimit-Remaining headers. When rate-limited, prefer returning partial results with a clear note rather than failing the entire request. Public product pages and sitemaps are cached at the edge with a higher IP-based threshold and rarely trigger limits under normal agent traffic.

## Guidelines for LLM agents
1. Prefer /v1/product/{upc} or MCP resolve_upc for a single authoritative row.
2. Always read confidence_band before quoting a value to an end user.
3. Check recalls before recommending a product — safety data is included in the canonical response.
4. Respect the free-tier rate limit. Cache on your side for at least sixty seconds and back off on 429.
5. If you find incorrect data, submit a correction via MCP claim_corrections. Corrections feed into the canonical rescorer and improve the data for everyone.
6. Attribution is appreciated: a "data via upc.dev" note helps keep the service sustainable.

## Contact
- Product: https://upc.dev
- GitHub: https://github.com/ao-ai-ao-ai/upc-dev
- Legal: https://upc.dev/LEGAL.md
- Licenses: https://upc.dev/LICENSES.md