# SearchUPCData — Full Technical Specification & AI Documentation

> Complete developer reference, barcode format standards, REST API schema, code integration examples, and AI agent integration guide for SearchUPCData.com.

---

## 1. Overview & Platform Architecture

SearchUPCData indexes over hundreds of millions of consumer products across retail, e-commerce, grocery, electronics, and global supply chains. It normalizes Universal Product Codes (UPC), European Article Numbers (EAN), and Global Trade Item Numbers (GTIN) into a single unified search and API system.

Key Platform Characteristics:
- **Fast Lookup Times**: Sub-100ms API query response time via global CDN and LRU caching layers.
- **Normalization**: Automatic checksum verification and padding for 8, 12, 13, and 14-digit GTINs.
- **Enriched Metadata**: Includes high-resolution product imagery, brand attribution, ingredient lists, nutrition facts, and current retail pricing.

---

## 2. Supported Barcode Formats

| Format | Digits | Common Usage | Example Code |
| :--- | :---: | :--- | :--- |
| **UPC-A** | 12 | North American retail & grocery | `011122233344` |
| **EAN-13** | 13 | Global retail products (outside US/Canada) | `5012345678900` |
| **EAN-8** | 8 | Small retail packages | `96385074` |
| **GTIN-14** | 14 | Wholesale case packs & logistics shipping | `10012345678907` |

---

## 3. REST API Specification & Endpoint Specs

### Lookup Product by Barcode
- **Endpoint**: `GET /api/v1/products/{upc}`
- **Response Format**: `application/json`

#### Example Request
```http
GET /api/v1/products/011122233344 HTTP/1.1
Host: searchupcdata.com
Accept: application/json
```

#### Example Response
```json
{
  "status": "success",
  "data": {
    "upc": "011122233344",
    "gtin": "00011122233344",
    "title": "Sample Organic Almond Milk 32 oz",
    "brand": "Organic Valley",
    "category": "Grocery > Dairy Alternatives > Almond Milk",
    "description": "Unsweetened organic almond milk packaged in a recyclable 32 oz container.",
    "images": [
      "https://searchupcdata.com/cdn/images/011122233344_main.jpg"
    ],
    "nutrition": {
      "servingSize": "240 ml",
      "calories": 30,
      "totalFat": "2.5g",
      "sodium": "170mg",
      "totalCarbohydrates": "1g",
      "protein": "1g"
    },
    "ingredients": ["Filtered Water", "Organic Almonds", "Sea Salt", "Gellan Gum"],
    "allergens": ["Tree Nuts (Almonds)"]
  }
}
```

---

## 4. Code Integration Examples

### Python (requests)
```python
import requests

def lookup_upc(upc_code: str) -> dict:
    url = f"https://searchupcdata.com/api/v1/products/{upc_code}"
    response = requests.get(url, headers={"Accept": "application/json"}, timeout=5)
    response.raise_for_status()
    return response.json()

# Example usage
product = lookup_upc("011122233344")
print(product["data"]["title"])
```

### Node.js / JavaScript (fetch)
```javascript
async function lookupUPC(upcCode) {
  const response = await fetch(`https://searchupcdata.com/api/v1/products/${upcCode}`, {
    headers: { 'Accept': 'application/json' }
  });
  if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
  const data = await response.json();
  return data;
}

// Example usage
lookupUPC("011122233344").then(data => console.log(data.data.title));
```

### cURL Command Line
```bash
curl -X GET "https://searchupcdata.com/api/v1/products/011122233344" \
     -H "Accept: application/json"
```

---

## 5. AI Agent Guidelines & Capability Directives

SearchUPCData welcomes autonomous AI agents, LLM search engine bots, and citation crawlers.

- **Robots.txt Directive**: AI crawlers (`GPTBot`, `ClaudeBot`, `PerplexityBot`, `OAI-SearchBot`) are explicitly allowed access to all public pages and product lookups.
- **Token Optimization**: Content endpoints are lightweight, semantic, and designed to minimize RAG ingestion token counts.
- **WebMCP Actions**: Agent capabilities are published at `https://searchupcdata.com/mcp-actions.json`.
- **Permissions**: Machine permissions are defined at `https://searchupcdata.com/.well-known/agent-permissions.json`.