# Vatan Bilgisayar API scraper — search vatanbilgisayar.com (Turkish electronics) and read full product records: TRY price with the Web'e Özel and basket ('sepette') prices kept apart, struck price, instalments, availability, rating, specifications, variants, images, store stock across Vatan's shops and the deal lists. No account, no browser.

> Search vatanbilgisayar.com by keyword or browse a category, 24 products per page: slug, product code, title, images, the online price in TRY with the struck price, the Web'e Özel price and the basket-only ('sepette') price kept apart, the card's rating, colour options and deal notes. Filter by brand, price range and in-stock, sort the way the site does, page through results. Keywords Vatan redirects to a category are followed with the filters kept. The response lists the categories, brands and price bands available.
> ReefAPI engine `vatan` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/vatan/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /vatan/v1/search — 1 credit
Search vatanbilgisayar.com by keyword or browse a category, 24 products per page: slug, product code, title, images, the online price in TRY with the struck price, the Web'e Özel price and the basket-only ('sepette') price kept apart, the card's rating, colour options and deal notes. Filter by brand, price range and in-stock, sort the way the site does, page through results. Keywords Vatan redirects to a category are followed with the filters kept. The response lists the categories, brands and price bands available.

**Parameters:**
- `query` (string, optional) — What to look for on vatanbilgisayar.com — a Turkish keyword ('kulaklık', 'robot süpürge'), a brand or a model. Optional when `category` is given.
- `category` (string, optional) — Browse a Vatan category instead of searching: its URL or path ('notebook', '/apple/cep-telefonu-modelleri/'), as returned in `filters.categories[].path`.
- `brand` (string, optional) — Only this brand: the `brand` value from `filters.brands` (e.g. 'jbl', 'lenovo').
- `page` (integer, optional, default 1) — Result page, 1-based. Vatan pages hold 24 products.
- `sort` (enum, optional, default "relevance") — Result order — only the orderings vatanbilgisayar.com itself offers. [one of: relevance, best_selling, price_asc, price_desc, most_reviewed, newest, oldest]
- `min_price` (number, optional) — Lowest price in TRY.
- `max_price` (number, optional) — Highest price in TRY.
- `in_stock_only` (boolean, optional, default false) — true: only products Vatan lists as in stock (the site's own 'Stoktakiler' filter).
- `include_fallback_results` (boolean, optional, default false) — When no product on the page contains a word of the query, results is empty and fallback_results_dropped counts the dropped products. true returns them apart, in fallback_results.
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** results[]{position, slug (use with product/detail), product_code (Vatan's code, often the MPN), title, url, image, images[], price (TRY — the online price; the Web'e Özel price when one applies), currency, regular_price (the big price on a Web'e Özel product), price_label, price_note, was_price (struck price), discount_percent, discount_amount, basket_price (a 'Sepette' price applied only in the basket — NOT the price), basket_price_label, rating_rounded (the card's 1-decimal score, null when unrated; exact rating in product/detail), lowest_price_note, web_exclusive_badge, color_options, color_options_out_of_stock, is_outlet, badge_images[]}, count, page, page_size (24), total_results (the site's own count), total_pages, page_notice, sort, query, category, brand, redirected_to (the listing a keyword was redirected to), keyword_matches_on_page, fallback_results_dropped, fallback_total, fallback_results[] (only with include_fallback_results=true), filters{categories[]{name, path, count}, brands[]{name, brand, count}, price_bands[]{label, path, count}}

**Example request body:**
```json
{
  "query": "kulaklık"
}
```

### POST /vatan/v1/product/detail — 1 credit
The full Vatan product record by numeric id, URL or slug: title, brand, product code and MPN, online price in TRY with the Web'e Özel, struck and basket-only prices kept apart, interest-free instalments, availability (including 'out of stock online'), free shipping, rating and review count, image gallery, breadcrumb, key attributes and the full specification table, description, colour/capacity variants with their ids, and the page's review sample.

**Parameters:**
- `product_id` (string, required) — A Vatan product: its numeric id (141004, `product_id` in suggest and detail), its product URL, or the URL slug every search row returns in `slug`.
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** product{product_id, product_code, mpn, title, brand, color, url, slug, group_id, price, currency, regular_price, price_label, price_note, was_price, discount_percent, discount_amount, basket_price, basket_price_label, schema_org_price, installment{months, monthly_amount, same_as_cash_price}, installment_from_monthly, lowest_price_note, summary, availability (in_stock | out_of_stock | out_of_stock_online | pre_order | null), free_shipping, rating, review_count, rating_scale, schema_org_reviews[]{rating, title, text, date} (the page's structured sample, not the newest), images[], breadcrumb[]{name, url}, category_path[], key_attributes[]{name, value}, specifications[]{group, name, value}, description, variants[]{product_id, url, label, image}, is_outlet}

**Example request body:**
```json
{
  "product_id": "141004"
}
```

### POST /vatan/v1/product/stores — 1 credit
Which Vatan stores hold a product right now: every store with stock, its city, address, phone, coordinates, opening hours, whether it is a hyperstore, and the stock number Vatan publishes. Accepts the numeric id, URL or slug.

**Parameters:**
- `product_id` (string, required) — A Vatan product: its numeric id (141004, `product_id` in suggest and detail), its product URL, or the URL slug every search row returns in `slug`.
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** stores[]{store_id, name, city, address, phone, latitude, longitude, opening_hours, is_hyperstore, stock, image}, count, cities[], product_id

**Example request body:**
```json
{
  "product_id": "141004"
}
```

### POST /vatan/v1/search/suggest — 1 credit
Vatan's own search-box list for a partial keyword: the matching products with numeric id, title, price, URL, image and category, plus the suggested categories.

**Parameters:**
- `query` (string, required) — What the shopper has typed so far (at least 2 characters).
- `limit` (integer, optional, default 50) — How many products to return (the site's list can hold several hundred).
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** products[]{product_id, title, price, currency, url, image, category, brand_group}, products_total, categories[]{name, path}, query

**Example request body:**
```json
{
  "query": "robot süpürge"
}
```

### POST /vatan/v1/deals — 1 credit
Vatan's deal lists as product rows: Fırsat Ürünler, Web'e Özel prices or Outlet items, with the same fields, sorting and paging as search.

**Parameters:**
- `type` (enum, optional, default "firsat") — Which Vatan deal list. [one of: firsat, web_ozel, outlet]
- `page` (integer, optional, default 1) — Result page, 1-based. Vatan pages hold 24 products.
- `sort` (enum, optional, default "relevance") — Result order — only the orderings vatanbilgisayar.com itself offers. [one of: relevance, best_selling, price_asc, price_desc, most_reviewed, newest, oldest]
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** results[]{position, slug (use with product/detail), product_code (Vatan's code, often the MPN), title, url, image, images[], price (TRY — the online price; the Web'e Özel price when one applies), currency, regular_price (the big price on a Web'e Özel product), price_label, price_note, was_price (struck price), discount_percent, discount_amount, basket_price (a 'Sepette' price applied only in the basket — NOT the price), basket_price_label, rating_rounded (the card's 1-decimal score, null when unrated; exact rating in product/detail), lowest_price_note, web_exclusive_badge, color_options, color_options_out_of_stock, is_outlet, badge_images[]}, count, page, page_size (24), total_results (the site's own count), total_pages, page_notice, sort, query, category, brand, redirected_to (the listing a keyword was redirected to), keyword_matches_on_page, fallback_results_dropped, fallback_total, fallback_results[] (only with include_fallback_results=true), filters{categories[]{name, path, count}, brands[]{name, brand, count}, price_bands[]{label, path, count}}, type

**Example request body:**
```json
{
  "type": "firsat"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=vatan
- Human docs page: https://reefapi.com/docs/vatan
- Overview page: https://reefapi.com/vatan-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt