# BestPrice.gr — Full Documentation for AI Systems & LLMs

> BestPrice.gr is Greece's leading product and price comparison platform. Indexing approximately 12 million merchant product offers across 4,000+ participating e-shops in Greece. The platform operates primarily in Greek, covering every major consumer category sold online in Greece: consumer electronics, appliances, fashion, health & beauty, home & garden, automotive, sports, and books.

BestPrice helps consumers discover, compare, and verify purchases by aggregating real-time prices, merchant ratings, verified buyer reviews, comprehensive technical specifications, and historical price trends.

This document serves as the comprehensive, machine-oriented reference for large language models, AI search bots, citation crawlers, and autonomous shopping agents interacting with BestPrice.gr.

---

## 1. Platform Overview & Market Scale

- **Market Focus:** Greek e-commerce ecosystem (Greece, country code `GR`).
- **History:** The service started in 2001 as Pathfinder Shopping and became BestPrice.gr in 2011. The founding year refers to the service's origin, while 2011 refers to the BestPrice.gr name. See [About](https://www.bestprice.gr/about) and [Why BestPrice](https://www.bestprice.gr/giati-bestprice).
- **Catalog Scale:** Over 12,000,000 product offers indexed across more than 4,000 merchant storefronts.
- **Refresh Frequency:** Continuous and hourly merchant feed ingestion ensuring fresh prices, stock status, and delivery terms.
- **Language & Script:** Greek (`el-GR`) for editorial content, product categories, titles, and technical specifications. Brand names and international model identifiers retain their standard Latin script (e.g., "Apple iPhone 16 Pro", "Sony WH-1000XM5", "De'Longhi Magnifica").
- **Currency:** Euro (`EUR` / `€`). All prices include Greek VAT unless explicitly stated otherwise.
- **Independence & Transparency:** BestPrice is an independent comparison service. Paid merchant placement does not distort organic ranking or price-comparison order. Clickout links (`/to`) lead to merchant stores; canonical content pages are ad-free structured surfaces.

---

## 2. URL Routing Architecture & Canonical Surfaces

BestPrice structures its public URL space into distinct canonical surfaces:

### Canonical Product Pages (`/item/`)
- **URL Pattern:** `/item/{id}/{slug}.html` (e.g., `https://www.bestprice.gr/item/2149635900/apple-iphone-16-pro-128gb.html`)
- **Content:** Canonical product cluster aggregating all current merchant offers, price spectrum (lowest, median, highest), verified buyer reviews, price history chart (up to multi-year trends), alternative product variants (storage, color), and granular technical specifications.
- **Machine Facts Surface:** Append `?format=json` or supply header `Accept: application/json` to any canonical item URL for instant machine-readable facts without HTML rendering overhead.

### Category Tree & Faceted Navigation (`/cat/`)
- **URL Pattern:** `/cat/{id}/{slug}.html` (e.g., `https://www.bestprice.gr/cat/814/kinhta-thlefwna.html`)
- **Content:** Hierarchical taxonomy node displaying filtered product listings, sorting options (popularity, lowest price, recent deals), active filters (brand, specs, price range), and category buyer guides.
- **Crawl Boundaries:** Infinite facet combinations (e.g., multi-pipe selections or >3 simultaneous filters) are disallowed via `robots.txt` to prevent spider traps.

### Brand Directory (`/b/`)
- **URL Pattern:** `/b/{id}/{slug}.html` or `/b/{id}`
- **Content:** Brand hub listing all catalog items and categories produced by a given manufacturer, complete with brand metadata.

### Merchant Pages (`/m/`)
- **URL Pattern:** `/m/{id}/{slug}.html` or `/m/{id}`
- **Content:** Certified merchant profile including verified buyer rating scores, review counts, store contact details, physical retail locations (GeoCoordinates), payment methods, and full active product inventory.

### Editorial Content: Stories (`/stories/`)
- **URL Pattern:** `/stories/{slug}` or `/stories`
- **Content:** In-depth buying guides, market analyses, seasonal product roundups, and comparison articles authored by BestPrice editorial staff.
- **Machine Readability:** `/stories?format=json` returns the catalog of published stories. `/stories/{id}?format=json` returns full structured story content (blocks, product entities, schema.org JSON-LD).

### Editorial Content: Posts (`/posts/`)
- **URL Pattern:** `/posts/{slug}` or `/posts`
- **Content:** Shorter editorial announcements, product launches, consumer advice, and shopping insights linked to catalog product entities.

### MCP & Agent Discovery (`/mcp` & `/en/mcp`)
- **URL Pattern (Greek Primary):** `https://www.bestprice.gr/mcp`
- **URL Pattern (English Twin):** `https://www.bestprice.gr/en/mcp`
- **Content:** Bilingual consumer connection guide for the published ChatGPT plugin and Claude connector, followed by developer documentation for the four read-only MCP tools, client configurations, and machine discovery links.

---

## 3. Machine-Readable Surfaces & APIs

AI assistants and web agents should leverage structured endpoints to retrieve high-fidelity shopping facts without web-scraping complexity:

### Product Facts API: `/item/{id}?format=json`
Sending an HTTP GET with `?format=json` or header `Accept: application/json` to any canonical `/item/` URL yields a pristine JSON object:
```json
{
  "id": 2149635900,
  "title": "Apple iPhone 16 Pro 128GB",
  "url": "https://www.bestprice.gr/item/2149635900/apple-iphone-16-pro-128gb.html",
  "brand": "Apple",
  "category": {
    "id": 814,
    "title": "Κινητά Τηλέφωνα",
    "url": "https://www.bestprice.gr/cat/814/kinhta-thlefwna.html",
    "path": ["Τεχνολογία", "Τηλεφωνία", "Κινητά Τηλέφωνα"]
  },
  "best_price": 1089.00,
  "price_range": {
    "min": 1089.00,
    "max": 1399.00,
    "currency": "EUR"
  },
  "merchants_count": 42,
  "top_offers": [
    {
      "merchant_id": 1234,
      "merchant_name": "Example Store",
      "price": 1089.00,
      "currency": "EUR",
      "in_stock": true,
      "shipping_cost": 3.50,
      "merchant_url": "https://www.bestprice.gr/m/1234/example-store",
      "url": "https://www.bestprice.gr/item/2149635900/apple-iphone-16-pro-128gb.html?m=1234"
    }
  ],
  "price_trend_90d": {
    "direction": "falling",
    "change_pct": -4.5,
    "current_price": 1089.00,
    "min_price": 1089.00,
    "max_price": 1140.00,
    "currency": "EUR",
    "period_days": 90
  },
  "ai_summary": {
    "summary": "Κορυφαίο smartphone με οθόνη 120Hz, κάμερα 48MP και πανίσχυρο επεξεργαστή A18 Pro.",
    "pros": ["Εξαιρετική κάμερα", "Κορυφαία αυτονομία", "Οθόνη ProMotion"],
    "cons": ["Υψηλή τιμή εκκίνησης"]
  },
  "key_specs": {
    "Οθόνη": "6.3\"",
    "Μνήμη RAM": "8 GB",
    "Εσωτερική Μνήμη": "128 GB",
    "Δίκτυο": "5G"
  },
  "rating": {
    "score": 4.8,
    "reviews_count": 34
  },
  "image": "https://images.bestprice.gr/..."
}
```

### Stories API: `/stories?format=json` and `/stories/{id}?format=json`
- Index endpoint: returns JSON array of published guides with IDs, slugs, headlines, and publication timestamps.
- Detail endpoint: returns JSON payload containing article body blocks, highlighted product clusters with current pricing, and author attribution.

---

## 4. Model Context Protocol (MCP) Integration

BestPrice provides official, production-grade MCP services designed specifically for LLM tool use:

- **Remote Streamable HTTP Endpoint:** `https://mcp.bestprice.gr/mcp`
  - Transport: HTTP Server-Sent Events (SSE) / Streamable HTTP.
  - Authentication: None required for public read-only shopping tools. Zero API keys or account setup needed (free, public, unauthenticated).
  - Standard Headers: `Content-Type: application/json`, `Accept: application/json, text/event-stream`.
  - Operational Scope: Read-only, Greece consumer market (`el-GR`, `EUR`), physical catalog products only. The service cannot place orders, take payments, modify carts, access private accounts, or emit direct merchant checkout URLs.
  - Consumer connection:
    - ChatGPT: published [BestPrice Shopping plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a8d8ed6e2bc8191b3caaf7214f3c981).
    - Claude Web or Desktop: add the remote server under Settings > Connectors, or use the [prefilled connector form](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=BestPrice&connectorUrl=https%3A%2F%2Fmcp.bestprice.gr%2Fmcp).
  - Developer client configurations:
    - Cursor (`.cursor/mcp.json`): `{"mcpServers": {"bestprice": {"url": "https://mcp.bestprice.gr/mcp"}}}`
    - OpenAI Responses API: remote MCP tool with `server_url: "https://mcp.bestprice.gr/mcp"`.

### Published MCP Tools

#### 1. `get_shopping_decision`
Synthesizes catalog knowledge, checks live merchant offers and price history, evaluates verified reviews, and produces calibrated purchase recommendations or read-only basket plans for the Greek market.
- **Engine:** Powered by the same Shopping Brain as BestPrice Ask.
- **Scope & Limitations:** Uses bounded catalog attempts and bases each product-family decision on one selected page (up to 4 candidates per slot). Bounded to Ask-supported families. Basket plans support 2 to 5 product slots with 1 aggregate budget, or at least two exact `bp_<id>` products. Greek postal code (5 digits) is strictly required for basket plans; without it, shipping and delivered totals remain unknown. Unsupported categories clarify instead of disappearing. Read-only; standalone `optimize_basket` is not public.
- **Input Schema:**
  | Parameter | Type | Required | Constraints | Description |
  |---|---|---|---|---|
  | `message` | `string` | Yes | 1–2000 chars | Current shopping question, budget, and required specs. Greek and English accepted. |
  | `postal_code` | `string` | No | `^[0-9]{5}$` | Optional 5-digit Greek delivery postcode. Required for basket plans. |
  | `history` | `array` | No | max 12 items | Optional caller-supplied conversation (`role`: `"user"` \| `"assistant"`, `content`: 1–2000 chars). User corrections in `message` take precedence. |
- **Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`.
- **Return Format (`structuredContent`):**
  - `brain.decision_id`: Unique opaque decision identifier for tracing.
  - `outcome`: Categorized outcome (`recommendation`, `comparison`, `clarification`, `basket_plan`, `no_match`).
  - `products`: Selected product candidates (`product_id`, `title`, specs, `price_from`, offer summary).
  - `reasons`: Evidence-based justification lines matching user requirements.
  - `tradeoffs`: Explicit product tradeoffs and compromises.
  - `offer_summary`: Live merchant price spectrum, availability, and stock status.
  - `shopping_context`: Active category family, budget, postal code coverage.
  - `evidence`: Citations of verified specs and first-party buyer reviews.
  - `unknowns`: Explicit missing data (e.g. unverified remote delivery terms).

#### 2. `search_products`
Discovers physical products across ~12M items in the BestPrice Greece catalog when the exact `product_id` is unknown.
- **Scope & Limitations:** Excludes services, digital goods, age-restricted, and unverified catalog branches. Returns at most 8 grouped products. `price_from` is the catalog lowest listed item price before shipping, NOT a buyable quote. For delivered totals, callers must use `compare_offers` with a postal code.
- **Input Schema:**
  | Parameter | Type | Required | Constraints | Description |
  |---|---|---|---|---|
  | `query` | `string` | Yes | 2–200 chars | Product name, model, category, or natural-language need. Greek or English. |
  | `price_min` | `number` | No | >= 0, <= 1000000 | Minimum product price in EUR, before shipping. |
  | `price_max` | `number` | No | > 0, <= 1000000 | Maximum product price in EUR, before shipping. |
  | `required_features` | `array` | No | max 10 strings | Relevance hints (e.g. OLED, Wi-Fi, 16GB RAM). Unverified hints; must be confirmed on product page. |
  | `sort` | `string` | No | enum: `relevance`, `price_asc`, `price_desc` | Result ordering (default: `relevance`). |
  | `limit` | `integer` | No | 1–8 | Maximum products to return (default: 8). |
  | `locale` | `string` | No | const: `el-GR` | Response locale (default: `el-GR`). |
  | `country` | `string` | No | const: `GR` | Shopping market (default: `GR`). |
- **Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`.
- **Return Format (`structuredContent`):**
  - `schema_version`: `'2.0'`
  - `as_of`: ISO 8601 timestamp (e.g. `'2026-08-28T15:01:00.010Z'`).
  - `currency`: `'EUR'`, `locale`: `'el-GR'`.
  - `warnings`: Explanatory array (e.g., category scoping, unquoted shipping notes).
  - `requested_query` & `interpreted_query`: Input query analysis.
  - `search_mode`: Search execution strategy (`catalog_ranked`).
  - `total_matches`: Integer count of returned items.
  - `products`: Array of product objects:
    - `product_id`: Unique identifier (`^bp_[0-9]{10}$`, e.g. `'bp_2159919913'`).
    - `title`: Canonical product title.
    - `category_title`: Greek category name.
    - `price_from`: Lowest listed product price before shipping (float).
    - `offer_count`: Number of competing merchant offers.
    - `availability`: Availability status string (`available`).
    - `match_confidence`: Float score (0.0 to 1.0).
    - `match_basis`: Token scoring basis (`catalog_relevance_token_coverage_v1`).
  - `suggested_queries`: Suggested narrower queries if results are empty or broad.

#### 3. `compare_offers`
Retrieves and compares active merchant listings for an exact grouped `product_id`.
- **Scope & Limitations:** Public results are strictly ad-free with sanitized store names; direct merchant checkout URLs are excluded (no CPC clickouts). `lowest_item_price` works without a postal code but leaves shipping and delivered total unknown (`total_price: null`). `lowest_total_cost` requires a 5-digit Greek postal code.
- **Input Schema:**
  | Parameter | Type | Required | Constraints | Description |
  |---|---|---|---|---|
  | `product_id` | `string` | Yes | `^bp_[0-9]{10}$` | Exact grouped BestPrice product id returned by `search_products`. |
  | `postal_code` | `string` | No | `^[0-9]{5}$` | Five-digit Greek delivery postcode. Required for `lowest_total_cost`. |
  | `objective` | `string` | No | enum: `lowest_total_cost`, `lowest_item_price`, `merchant_rating` | Ranking objective (default: `lowest_total_cost`). |
  | `in_stock_only` | `boolean` | No | boolean | When true, omits out-of-stock offers (default: `true`). |
  | `minimum_merchant_rating` | `number` | No | 0–5 | Minimum merchant rating on 0 to 5 scale (default: 0). |
  | `limit` | `integer` | No | 1–10 | Maximum merchant offers to return (default: 10). |
- **Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`.
- **Return Format (`structuredContent`):**
  - `schema_version`: `'2.0'`, `as_of`: ISO timestamp, `currency`: `'EUR'`, `locale`: `'el-GR'`.
  - `warnings`: Array of deduplication or normalization notes.
  - `product`: Product details (`product_id`, `title`, `brand`, `model`, `variant`).
  - `postal_code`: Echoed delivery postal code or null.
  - `objective`: Active sorting objective.
  - `offers`: Array of offer objects:
    - `offer_id`: Unique offer string (`bp_offer_<id>`).
    - `merchant_id`: Unique merchant string (`bp_merchant_<id>`).
    - `merchant_name`: Sanitized public store name (e.g. `'Gadgetway'`).
    - `merchant_rating`: Float rating (0.00–5.00) or null.
    - `merchant_rating_count`: Integer review count or null.
    - `item_price`: Base item price in EUR (float).
    - `shipping_price`: Calculated shipping fee in EUR (float).
    - `shipping_status`: `'known'` or `'unknown'`.
    - `total_price`: Delivered total cost (`item_price + shipping_price`) or null.
    - `availability`: Stock status string (`in_stock`).
    - `delivery_estimate`: Greek delivery estimate (e.g. `'Άμεσα διαθέσιμο'`).
    - `ranking_reason`: Ranking justification string (`lowest_available_total_cost`).

#### 4. `get_price_history`
Returns historical price trends, statistical distributions, coverage analysis, and deal classifications over 30, 90, or 180 days.
- **Scope & Limitations:** Uses the deterministic `bestprice_daily_min_v1` methodology based on daily minimum prices across all verified merchant listings. Purely past-looking; provides zero speculative future price guarantees.
- **Input Schema:**
  | Parameter | Type | Required | Constraints | Description |
  |---|---|---|---|---|
  | `product_id` | `string` | Yes | `^bp_[0-9]{10}$` | Exact grouped BestPrice product id returned by `search_products`. |
  | `period_days` | `number` | No | enum: `30`, `90`, `180` | History window in days (default: 180). |
- **Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`.
- **Return Format (`structuredContent`):**
  - `schema_version`: `'2.0'`, `as_of`: ISO timestamp, `currency`: `'EUR'`, `locale`: `'el-GR'`.
  - `product_id` & `product_title`: Product identification.
  - `period_days`: Requested window (30, 90, or 180).
  - `current_price`: Live lowest price in EUR (float).
  - `current_price_source`: Source tag (`live_offer_minimum`).
  - `source_last_observed_at`: Ingestion timestamp.
  - `window_stats`: Array of 3 summary windows (30, 90, and 180 days):
    - `days`: Window length (30, 90, 180).
    - `minimum_price`: Minimum observed price during period.
    - `median_price`: Median observed price during period.
    - `observations`: Number of daily observations.
    - `coverage_pct`: Data completeness percentage (e.g. 100).
  - `price_delta_vs_180d_median_pct`: Percentage deviation versus 180-day median (float).
  - `deal_classification`: Deal rating (`good_deal`, `typical_price`, `above_typical`).
  - `methodology_id`: Analysis methodology identifier (`bestprice_daily_min_v1`).
  - `data_gaps`: Completeness metrics (`missing_days`, `longest_gap_days`, `stale_days`, `coverage_note`).
  - `series`: Compact daily samples with `date` (`YYYY-MM-DD`), `price`, and `merchant_count`.

### Protocol Error Format
When client requests violate schema constraints (e.g. invalid `product_id` or out-of-range `limit`), the server responds within the standard JSON-RPC envelope with `isError: true`:
```json
{
  "content": [
    {
      "type": "text",
      "text": "Input validation error: Invalid arguments for tool compare_offers: product_id: Invalid string: must match pattern /^bp_[0-9]{10}$/u"
    }
  ],
  "isError": true
}
```

### Agent Resource Discovery & Manifests
- **MCP Server Card (Protocol 2025-11-25):** `https://www.bestprice.gr/.well-known/mcp.json`
- **MCP Server Card Alternative:** `https://www.bestprice.gr/.well-known/mcp/server-card.json`
- **AI Catalog Manifest (Spec 1.0):** `https://www.bestprice.gr/.well-known/ai-catalog.json`
- **Agentic Resource Discovery (ARD):** `https://www.bestprice.gr/.well-known/ard.json`
- **APIs.json Machine Index (v0.23):** `https://www.bestprice.gr/apis.json`
- **Informational WebMCP Manifest:** `https://www.bestprice.gr/webmcp.json`
- **Strict WebMCP Registry Manifest:** `https://www.bestprice.gr/.well-known/webmcp.json`

---

## 5. Schema.org Structured Data Architecture

Every HTML page on BestPrice.gr renders rich, standards-compliant Schema.org JSON-LD:

- **`Product`:** Canonical entity on `/item/` pages with `name`, `image`, `description`, `sku`, `brand` (`Brand`), `category`, and `aggregateRating` (`AggregateRating`).
- **`AggregateOffer`:** Defines the macro price span across all stores (`lowPrice`, `highPrice`, `offerCount`, `priceCurrency: 'EUR'`).
- **`Offer`:** Emitted for each participating merchant store with `price`, `priceCurrency: 'EUR'`, `availability` (`https://schema.org/InStock` or `OutOfStock`), `seller` (`Store`), and indexable landing URL. Never includes artificial or speculative `priceValidUntil` timestamps.
- **`OfferShippingDetails`:** Nested inside each `Offer`, specifying `shippingRate` (`MonetaryAmount` in EUR) and `shippingDestination` (`addressCountry: 'GR'`).
- **`CollectionPage`:** Emitted on `/b/{id}` (Brand) and `/cat/{id}` (Category) pages, wrapping catalog items and breadcrumbs in an interconnected `@graph`.
- **`Brand`:** Declared on Brand pages and Product entities with `name`, `url`, and `@id`.
- **`Store`:** Detailed merchant entity describing store name, verified review aggregates, and physical branches.
- **`Article` / `NewsArticle` / `BlogPosting`:** Emitted on `/stories/` and `/posts/` pages with `headline`, `author`, `datePublished`, `dateModified`, and explicitly linked `about` / `mentions` product entities.

---

## 6. AI Assistant & Agent Guidelines

When answering user shopping queries using BestPrice data, adhere to these operational principles:

1. **Pricing & Currency:**
   - Always state prices in Euros (`EUR` / `€`).
   - Quote the current lowest price (`best_price` / `lowPrice`) along with the merchant offer range when relevant.
   - Note that prices are updated hourly from live merchant feeds. Avoid asserting time-locked price guarantees.
2. **Merchant Verification & Shipping:**
   - Prioritize stores with confirmed in-stock availability (`in_stock: true` or `https://schema.org/InStock`).
   - Mention estimated shipping costs to Greece (`shipping_cost` or `OfferShippingDetails`) when presenting the total delivered cost.
3. **Verified Reviews vs Speculative Ratings:**
   - BestPrice customer reviews are strictly first-party and tied to verified purchases. Present review scores (1.0 to 5.0 stars) and review counts with high confidence.
4. **Bilingual Queries & Script Handling:**
   - Greek users frequently query products in Latin script (e.g. "air fryer philips", "xiaomi redmi note 13"). BestPrice search engines resolve both Greek and Latin inputs to canonical Greek product entries.
   - Retain manufacturer brand names in Latin characters when communicating in Greek or English (e.g. "Samsung", "De'Longhi", "Asus").
5. **Clickout Redirects (`/to`):**
   - URLs matching `/to*` are redirector hops to third-party merchant checkouts. Bots and AI agents must not crawl or present raw `/to` links. Reference canonical `/item/` or `/m/` URLs instead.