# Watsons Türkiye API scraper — search watsons.com.tr's beauty and personal-care catalogue and read full product records: TRY price, Watsons Club member price and was-price when published, stock level, rating and review breakdown, EAN barcodes, images, breadcrumb, description and reviews. No account, no browser.

> Search watsons.com.tr by keyword, or browse a category, and get one row per product: product code, title, brand, image, price in TRY, Watsons Club member price and was-price when Watsons publishes them, stock status and unit count, rating and review count, EAN barcodes and category path. Filter by brand, price range and in-stock, sort the way the site does, and page through the results. The response also lists the brands, categories and price bands available for the query.
> ReefAPI engine `watsons-tr` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/watsons-tr/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 /watsons-tr/v1/search — 1 credit
Search watsons.com.tr by keyword, or browse a category, and get one row per product: product code, title, brand, image, price in TRY, Watsons Club member price and was-price when Watsons publishes them, stock status and unit count, rating and review count, EAN barcodes and category path. Filter by brand, price range and in-stock, sort the way the site does, and page through the results. The response also lists the brands, categories and price bands available for the query.

**Parameters:**
- `query` (string, optional) — What to look for on watsons.com.tr — a Turkish keyword ('şampuan', 'ruj'), a brand ('elseve') or a product name. Optional when `category` is given (then the category is browsed).
- `category` (string, optional) — Watsons category code — the number after /c/ in a category URL (https://www.watsons.com.tr/sac-bakim/sampuanlar/c/212 → 212). A full category URL is also accepted. Every search returns the matching categories with their codes in `filters.categories`.
- `page` (integer, optional, default 1) — Result page, 1-based.
- `page_size` (integer, optional, default 28) — Products per page, 1-100 (the site's default is 28).
- `sort` (enum, optional, default "relevance") — Result order — only the orderings watsons.com.tr itself offers. [one of: relevance, price_asc, price_desc, newest, rating, most_reviewed, name_asc, name_desc, stock]
- `brand` (string, optional) — Only these brands. One brand or several separated by commas (several = any of them). Use the names returned in `filters.brands`; case does not matter.
- `in_stock` (boolean, optional, default false) — true = only products Watsons shows as in stock.
- `min_price` (number, optional) — Lowest price in TRY (inclusive).
- `max_price` (number, optional) — Highest price in TRY (inclusive).
- `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, product_id (BP_… code), sku, title, brand, range_name, url, image, price (number, TRY; null when Watsons shows no price), price_display, price_type, currency=TRY, was_price (struck-through price, null when none), discount_amount, discount_percent, member_price (Watsons Club price, null when none), member_price_display, prior_price (published 30-day prior price, null when none), stock_status (inStock | lowStock | outOfStock), stock_level (units), in_stock, purchasable, rating (1-5, null with no reviews), review_count, rating_scale (5), category_path[], barcodes[] (EAN), badges[], new_in, promotion, multibuy}, count, page, page_size, total_results, total_pages, sort, redirect_url (set when Watsons sends the keyword to a landing page instead), filters{brands[]{name, value, count}, categories[]{name, code, count}, subcategories[]{name, code, count}, price_bands[]{label, min, max, count}}

**Example request body:**
```json
{
  "query": "şampuan"
}
```

### POST /watsons-tr/v1/product/detail — 1 credit
The full Watsons Türkiye product record by product code or URL: title, brand, price in TRY with was-price, discount and Watsons Club member price when published, the basket-promotion message, stock status with unit count, rating with review count and per-star breakdown, every image, the category breadcrumb, the description as clean text with its sections, ingredients and usage when the description publishes them, EAN barcodes, supplier, package dimensions and shade/size variants.

**Parameters:**
- `product_id` (string, required) — Watsons product code as returned in `product_id` by `search` (BP_153319). The bare number (153319) or a full watsons.com.tr product URL is also accepted.
- `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, sku, title, brand, brand_id, brand_url, range_name, url, price, price_display, price_type, currency=TRY, was_price, discount_amount, discount_percent, member_price, member_price_display, prior_price, promotion_message (basket-level offer text — NOT applied to price), promotions[]{code, title, description}, multibuy, stock_status, stock_level, in_stock, purchasable, available_for_pickup, max_order_quantity, rating, review_count, rating_scale (5), rating_breakdown{'1'..'5': count}, images[], breadcrumb[]{code, name, url}, category_path[], description, description_sections[]{heading, text}, ingredients (null unless the description has an ingredients section), how_to_use, barcodes[], supplier, dimensions{width, height, depth, unit (null — Watsons publishes no unit)}, variants[]{sku, name, variant_type, price, price_display, price_type, member_price, stock_status, stock_level, in_stock, purchasable, url, barcodes[]}, variant_count, badges[], new_in, age_restricted, updated_at}

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

### POST /watsons-tr/v1/product/reviews — 1 credit
Written customer reviews of one Watsons Türkiye product, newest first: star rating (1-5), headline, review text and date. Watsons publishes the text of written reviews only, so this can be far fewer than the product's review_count, which counts every star rating (and can be 0 while the product has ratings).

**Parameters:**
- `product_id` (string, required) — Watsons product code as returned in `product_id` by `search` (BP_153319). The bare number (153319) or a full watsons.com.tr product URL is also accepted.
- `limit` (integer, optional, default 20) — How many reviews to return, newest first (1-200, default 20).
- `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:** reviews[]{rating, headline, comment, date}, count, total_written_reviews (written reviews Watsons publishes — not the star-rating count), rating_scale (5), order ('newest_first')

**Example request body:**
```json
{
  "product_id": "BP_153319",
  "limit": 5
}
```

### POST /watsons-tr/v1/search/suggest — 1 credit
Watsons Türkiye's own search-box suggestions for a partial keyword: the suggested search terms and the top matching products with price.

**Parameters:**
- `query` (string, required) — What the shopper has typed so far (at least 2 characters).
- `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:** suggestions[] (search terms), products[]{product_id, title, brand (often null here), url, image, price, price_display, currency}, products_total

**Example request body:**
```json
{
  "query": "şamp"
}
```

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