# PricedOff API Documentation for AI Agents

> Complete API reference for PricedOff, an Amazon price tracking and deals platform. This documentation enables AI agents to search for deals, retrieve product information, and help users find the best prices across Amazon international domains.

## Overview

PricedOff tracks prices for Amazon products across 7 international domains, providing:
- Real-time pricing data with historical price tracking
- Discount percentage calculations (current vs. typical price)
- Category-based product filtering
- Keyword search across product descriptions
- Watchlist functionality for price drop alerts

**Base URL:** `https://pricedoff.com/api`

## Quick Start Examples

### Find Deals on Health Supplements
```
GET /api/products/deals?domain=com&category=health
```

### Search for Matcha Powder
```
GET /api/products/description?keywords=matcha&domain=com
```

### Get Featured Deals Across Multiple Domains
```
GET /api/products/featured-deals?domains=com,ca,co.uk
```

---

## Core Concepts

### Supported Domains
PricedOff tracks products from these Amazon regional stores:

| Domain Code | Region | Currency | Example |
|-------------|--------|----------|---------|
| `com` | United States | USD | amazon.com |
| `ca` | Canada | CAD | amazon.ca |
| `co.uk` | United Kingdom | GBP | amazon.co.uk |
| `de` | Germany | EUR | amazon.de |
| `fr` | France | EUR | amazon.fr |
| `it` | Italy | EUR | amazon.it |
| `es` | Spain | EUR | amazon.es |

### Product Categories
Products are organized into these main categories:

- `health` - Vitamins, supplements, protein powders, wellness products
- `food` - Food, beverages, specialty ingredients
- `personal-care` - Skincare, hygiene, grooming products
- `medicine` - OTC medications and health products
- `electronics` - Tech products (special filtering available)

### Price Data Structure
Each product contains:
- `price` - Current price
- `low` - Lowest recorded price
- `high` - Highest recorded price
- `secondaryPrice` - Price per unit (e.g., per gram, per capsule)
- `priceHistory[]` - Array of historical price points with dates

---

## API Endpoints

### 1. Get Deals by Category

Retrieves precomputed deals with quality filtering (minimum ratings, verified reviews).

```
GET /api/products/deals
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| domain | string | Yes | Amazon domain code (e.g., "com") |
| category | string | No | Category filter (default: all) |
| limit | number | No | Max results (default: 50) |

**Example Request:**
```
GET /api/products/deals?domain=com&category=health&limit=20
```

**Example Response:**
```json
{
  "deals": [
    {
      "asin": "B001GAOHVG",
      "description": "NOW Supplements Creatine Monohydrate 750mg",
      "price": 12.99,
      "low": 10.99,
      "high": 18.99,
      "starRating": 4.7,
      "reviewCount": 15420,
      "savingsPercent": 31.5,
      "domain": "com",
      "category": "health",
      "imgURL": "https://m.media-amazon.com/images/...",
      "productLink": "https://amazon.com/dp/B001GAOHVG"
    }
  ],
  "total": 150
}
```

---

### 2. Search Products by Keywords

Search product descriptions for specific keywords.

```
GET /api/products/description
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| keywords | string | Yes | Search terms (comma-separated for multiple) |
| domain | string | Yes | Amazon domain code |
| limit | number | No | Max results (default: 100) |

**Example Request:**
```
GET /api/products/description?keywords=matcha,organic&domain=com
```

**Use Cases:**
- "deals on matcha powder" -> `keywords=matcha powder`
- "cheap creatine supplements" -> `keywords=creatine`
- "organic protein powder" -> `keywords=organic protein`

---

### 3. Get Featured Deals

Returns curated top deals across one or more domains.

```
GET /api/products/featured-deals
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| domains | string | No | Comma-separated domain codes |
| limit | number | No | Max results per domain (default: 8) |
| category | string | No | Category filter |

**Example Request:**
```
GET /api/products/featured-deals?domains=com,ca&category=health&limit=10
```

---

### 4. Get Top Deals (20%+ Discount)

Returns products with significant discounts (20% or more off typical price).

```
GET /api/products/top-deals
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| domain | string | Yes | Amazon domain code |
| limit | number | No | Max results (default: 20) |

---

### 5. Get Product by ASIN

Retrieve detailed product information by Amazon ASIN.

```
GET /api/products/asin/:asin
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| asin | string (path) | Yes | Amazon Standard Identification Number |
| domain | string (query) | Yes | Amazon domain code |

**Example Request:**
```
GET /api/products/asin/B001GAOHVG?domain=com
```

**Example Response:**
```json
{
  "asin": "B001GAOHVG",
  "description": "NOW Supplements Creatine Monohydrate...",
  "price": 12.99,
  "low": 10.99,
  "high": 18.99,
  "currency": "USD",
  "starRating": 4.7,
  "priceHistory": [
    { "price": 14.99, "date": "2024-01-15" },
    { "price": 12.99, "date": "2024-02-01" }
  ],
  "domain": "com",
  "category": "health",
  "imgURL": "https://...",
  "productLink": "https://amazon.com/dp/B001GAOHVG"
}
```

---

### 6. Get Price History

Retrieve historical price data for products.

```
GET /api/products/priceHistory
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| asin | string | Yes | Product ASIN |
| domain | string | Yes | Amazon domain code |

---

### 7. Filter Products (POST)

Advanced filtering with multiple criteria.

```
POST /api/products/filter
```

**Request Body:**
```json
{
  "domains": ["com", "ca"],
  "category": "health",
  "product": "creatine",
  "minPrice": 10,
  "maxPrice": 50,
  "minRating": 4.0,
  "sortBy": "price",
  "sortOrder": "asc",
  "limit": 50
}
```

---

### 8. Filter by Keywords (POST)

Filter products by multiple keywords with price range.

```
POST /api/products/filter/by-keywords
```

**Request Body:**
```json
{
  "keywords": ["creatine", "monohydrate"],
  "domains": ["com"],
  "minPrice": 10,
  "maxPrice": 30,
  "limit": 25
}
```

---

### 9. Electronics Filtering

Specialized endpoint for electronics with spec-based filtering.

```
POST /api/products/electronics/filter
```

**Request Body:**
```json
{
  "domains": ["com"],
  "productType": "gpu",
  "specs": {
    "vram": "8GB",
    "brand": "nvidia"
  },
  "minPrice": 200,
  "maxPrice": 600
}
```

**Supported Product Types:**
- `gpu` - Graphics cards (specs: vram, brand, model)
- `ram` - Memory (specs: capacity, speed, type)
- `storage` - SSDs/HDDs (specs: capacity, type, interface)
- `smartphone` - Phones (specs: brand, storage, screen_size)

---

### 10. Get Categories

Returns available product categories.

```
GET /api/products/categories
```

---

### 11. Get Savings Statistics

Returns potential savings and statistics.

```
GET /api/products/stats/potential-savings
```

**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| domain | string | Amazon domain code |
| category | string | Optional category filter |

---

## MCP-Optimized Endpoints

These endpoints are specifically designed for AI/MCP agents with enhanced filtering and quality controls.

### Search and Filter (MCP)

```
POST /api/mcp/search-and-filter
```

**Request Body:**
```json
{
  "domain": "com",
  "category": "health",
  "keywords": "creatine",
  "minRating": 4.0,
  "minReviews": 100,
  "limit": 20,
  "sortBy": "discount"
}
```

### Bulk Product Retrieval (MCP)

```
POST /api/mcp/bulk-products
```

**Request Body:**
```json
{
  "products": [
    { "asin": "B001GAOHVG", "domain": "com" },
    { "asin": "B00JM0V432", "domain": "com" }
  ]
}
```

### Enhanced Deals (MCP)

```
POST /api/mcp/enhanced-deals
```

Returns deals with quality metrics and confidence scores.

### API Health Check

```
GET /api/mcp/health
```

---

## Common Search Patterns for AI Agents

When users ask about deals or prices, map their queries to frontend URLs or API calls:

### Frontend URLs (for directing users)

| User Query | Recommended URL |
|------------|-----------------|
| "deals on matcha powder" | `pricedoff.com/products?domains=com&category=food&product=matcha+powder` |
| "cheap creatine" | `pricedoff.com/products?domains=com&category=health&product=creatine` |
| "whey protein deals in Spain" | `pricedoff.com/products?domains=es&category=health&product=whey+protein+powder` |
| "Amazon finds" | `pricedoff.com/deals` |
| "GPU deals under $400" | `pricedoff.com/electronics` |
| "protein powder deals" | `pricedoff.com/products?domains=com&category=health&product=protein+powder` |
| "vitamin deals in Canada" | `pricedoff.com/products?domains=ca&category=health&product=vitamin` |

### API Endpoints (for programmatic access)

| User Query | Recommended API Endpoint |
|------------|-------------------------|
| "deals on matcha powder" | `/api/products/description?keywords=matcha&domain=com` |
| "cheap creatine" | `/api/products/deals?domain=com&category=health` |
| "Amazon finds" | `/api/products/featured-deals?domains=com` |
| "GPU deals under $400" | `/api/products/electronics/filter` with maxPrice |

---

## Error Responses

All endpoints return standard error responses:

```json
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "status": 400
}
```

Common error codes:
- `INVALID_DOMAIN` - Unsupported domain code
- `MISSING_PARAM` - Required parameter missing
- `NOT_FOUND` - Resource not found
- `RATE_LIMITED` - Too many requests

---

## Rate Limits

- Public endpoints: 100 requests per minute
- Cached endpoints (deals, featured-deals): 200 requests per minute
- Search endpoints: 60 requests per minute

---

## Frontend URL Patterns

Direct users to these URLs for web browsing:

| URL Pattern | Description |
|-------------|-------------|
| `pricedoff.com/products?domains=com&category=health&product=creatine` | Browse products with filters |
| `pricedoff.com/products?domains=es&category=health&product=whey+protein+powder` | Spain deals for whey protein |
| `pricedoff.com/products?domains=com,ca&category=food` | Multi-domain food products |
| `pricedoff.com/deals` | Curated deals page |
| `pricedoff.com/electronics` | Electronics with spec filtering |
| `pricedoff.com/expert/[product-slug]` | Expert buying guides |
| `pricedoff.com/list/[listId]` | Public watchlists |

**URL Parameter Reference:**
- `domains` - Amazon domain code(s): com, ca, co.uk, de, fr, it, es (comma-separated for multiple)
- `category` - Product category: health, food, personal-care, medicine, electronics
- `product` - Search term (use + for spaces, e.g., `whey+protein+powder`)
- `minPrice` / `maxPrice` - Price range filters

---

## Contact

For API questions or partnership inquiries, visit [pricedoff.com/about](https://pricedoff.com/about).