# Namshi API scraper — the Gulf's leading fashion and lifestyle store (namshi.com) for the UAE, Saudi Arabia, Kuwait, Bahrain, Oman and Qatar: search clothing, shoes, bags, beauty and sportswear by keyword with namshi's own filters and sorts, browse any category, and read the full product record with its size variants — each price labelled with the market and currency it came from, in English or Arabic. No account, no browser.

> Search one namshi storefront by keyword and get the matching products: namshi product id, title, brand, images, the price the shopper actually pays together with the struck-through price and the discount percentage, the market and currency the price is quoted in, rating and review count where namshi publishes them, and the express / global / outlet flags. Filter by brand, colour, price band, discounted-only, new arrivals and delivery programme; sort by namshi's ranking, price, discount or newest. The response also carries namshi's whole facet catalogue with counts, so the next call can be narrowed without guessing codes.
> ReefAPI engine `namshi` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/namshi/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.
- **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). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/namshi/v1/search — 1 credit
Search one namshi storefront by keyword and get the matching products: namshi product id, title, brand, images, the price the shopper actually pays together with the struck-through price and the discount percentage, the market and currency the price is quoted in, rating and review count where namshi publishes them, and the express / global / outlet flags. Filter by brand, colour, price band, discounted-only, new arrivals and delivery programme; sort by namshi's ranking, price, discount or newest. The response also carries namshi's whole facet catalogue with counts, so the next call can be narrowed without guessing codes.

**Parameters:**
- `query` (string, required) — What to search for on namshi.com — a product, a brand, a category or a description, in English or Arabic, e.g. 'red summer dress', 'nike air force', 'abaya'. namshi matches loosely, so a keyword it does not know still returns its nearest matches rather than nothing.
- `country` (enum, optional, default "ae") — Which namshi storefront to read. Each one is a separate market with its OWN catalogue, availability and currency — a price is only meaningful together with the market it came from, and every row returns both. All six were measured open. [one of: ae, sa, kw, bh, om, qa]
- `language` (enum, optional, default "en") — Language of the titles, descriptions, categories and filter names namshi returns. [one of: en, ar]
- `page` (integer, optional, default 1) — Result page. namshi returns 60 products per page; `total_pages` in the response says how many there are.
- `sort` (enum, optional, default "recommended") — How namshi orders the results. Anything outside this list is refused, because namshi answers an unrecognised sort by dropping the search and returning its whole catalogue. [one of: recommended, price_asc, price_desc, discount, newest]
- `brand` (string, optional) — Keep only one brand, given as namshi's brand code — lowercase with underscores, as it appears in `brand_code` on every result row and in the `brand_code` entry of `filters` (e.g. 'nike', 'tommy_hilfiger', 'h_m').
- `colour` (string, optional) — Keep only one colour family, given as namshi's colour code. The codes available for the current result set, with counts, are returned under `filters` → `colour_family` (e.g. 'red', 'black', 'multicolour').
- `price_min` (number, optional) — Lowest price to keep, IN THE CURRENCY OF THE CHOSEN MARKET (AED for ae, SAR for sa, KWD for kw, BHD for bh, OMR for om, QAR for qa). The band namshi itself offers for the current result set is in `filters` → `current_price` → `range`.
- `price_max` (number, optional) — Highest price to keep, in the currency of the chosen market. Must not be below `price_min`.
- `discounted_only` (boolean, optional, default false) — Keep only products namshi currently shows at a reduced price (those with a struck-through `price_before_discount`).
- `new_arrivals_only` (boolean, optional, default false) — Keep only the products namshi flags as new arrivals.
- `delivery_type` (enum, optional) — Keep only products in one of namshi's delivery programmes. [one of: standard, global]

**Returns:** results[]{product_id, variant_sku, title, brand, brand_code, url, image, images[], price (what the shopper pays), price_before_discount (the struck-through price, null when the product is not discounted), discount_percent, currency, market, rating, review_count, rating_scale (null on the many products namshi publishes no rating for), placement (namshi's own row label, e.g. 'organic'), express_delivery, global_delivery, outlet, has_size_variants, max_quantity (namshi's per-order cap, not stock), listing_type}, count, total_results, total_pages, page, echoed_query, department, breadcrumbs[]{name, path}, filters[]{code, name, type, options[]{code, name, count}, range{min, max}}, sorts_available[], redirected (true when namshi answered the keyword with its own canonical landing page instead of a result list), landing_path, currency, market, country, language, query

**Example request body:**
```json
{
  "query": "red summer dress",
  "country": "ae"
}
```

### POST https://api.reefapi.com/namshi/v1/category/products — 1 credit
List one namshi category by its path — the same product rows, filters, sorts and paging as `search`, plus the category breadcrumb. Use it to walk a department (women's dresses, men's shoes, kids' clothing) rather than a keyword.

**Parameters:**
- `category` (string, required) — The namshi category to list, as its path or as a full category URL. Take it from `breadcrumbs[].path` or from `filters` → `category` on any result, e.g. 'women-clothing-dresses', 'men-shoes', 'women/women-clothing/women-clothing-dresses/women-clothing-dresses-midi'.
- `country` (enum, optional, default "ae") — Which namshi storefront to read. Each one is a separate market with its OWN catalogue, availability and currency — a price is only meaningful together with the market it came from, and every row returns both. All six were measured open. [one of: ae, sa, kw, bh, om, qa]
- `language` (enum, optional, default "en") — Language of the titles, descriptions, categories and filter names namshi returns. [one of: en, ar]
- `page` (integer, optional, default 1) — Result page. namshi returns 60 products per page; `total_pages` in the response says how many there are.
- `sort` (enum, optional, default "recommended") — How namshi orders the results. Anything outside this list is refused, because namshi answers an unrecognised sort by dropping the search and returning its whole catalogue. [one of: recommended, price_asc, price_desc, discount, newest]
- `brand` (string, optional) — Keep only one brand, given as namshi's brand code — lowercase with underscores, as it appears in `brand_code` on every result row and in the `brand_code` entry of `filters` (e.g. 'nike', 'tommy_hilfiger', 'h_m').
- `colour` (string, optional) — Keep only one colour family, given as namshi's colour code. The codes available for the current result set, with counts, are returned under `filters` → `colour_family` (e.g. 'red', 'black', 'multicolour').
- `price_min` (number, optional) — Lowest price to keep, IN THE CURRENCY OF THE CHOSEN MARKET (AED for ae, SAR for sa, KWD for kw, BHD for bh, OMR for om, QAR for qa). The band namshi itself offers for the current result set is in `filters` → `current_price` → `range`.
- `price_max` (number, optional) — Highest price to keep, in the currency of the chosen market. Must not be below `price_min`.
- `discounted_only` (boolean, optional, default false) — Keep only products namshi currently shows at a reduced price (those with a struck-through `price_before_discount`).
- `new_arrivals_only` (boolean, optional, default false) — Keep only the products namshi flags as new arrivals.
- `delivery_type` (enum, optional) — Keep only products in one of namshi's delivery programmes. [one of: standard, global]

**Returns:** results[]{product_id, variant_sku, title, brand, brand_code, url, image, images[], price (what the shopper pays), price_before_discount (the struck-through price, null when the product is not discounted), discount_percent, currency, market, rating, review_count, rating_scale (null on the many products namshi publishes no rating for), placement (namshi's own row label, e.g. 'organic'), express_delivery, global_delivery, outlet, has_size_variants, max_quantity (namshi's per-order cap, not stock), listing_type}, count, total_results, total_pages, page, echoed_query, department, breadcrumbs[]{name, path}, filters[]{code, name, type, options[]{code, name, count}, range{min, max}}, sorts_available[], redirected (true when namshi answered the keyword with its own canonical landing page instead of a result list), landing_path, currency, market, country, language, category

**Example request body:**
```json
{
  "category": "women-clothing-dresses",
  "country": "sa"
}
```

### POST https://api.reefapi.com/namshi/v1/product/detail — 1 credit
The full namshi product record for one product in one market: title, brand and brand logo, description, the whole image gallery, the price paid with the struck-through price and discount, the market and currency, availability, rating and review count where namshi publishes them, the attribute table, the category breadcrumb, the returns and exchange policy flags, and every size variant with its own stock state and its own price.

**Parameters:**
- `product_id` (string, required) — Which product to read: the code before /p/ in a namshi product URL (…/Z39B32B8C27F319D6E18FZ/p/ → Z39B32B8C27F319D6E18FZ), or the full product URL itself. Every `search` and `category/products` row returns it as `product_id`; a size-specific code such as …FZ-2 is accepted and resolves to its parent product.
- `country` (enum, optional, default "ae") — Which namshi storefront to read. Each one is a separate market with its OWN catalogue, availability and currency — a price is only meaningful together with the market it came from, and every row returns both. All six were measured open. [one of: ae, sa, kw, bh, om, qa]
- `language` (enum, optional, default "en") — Language of the titles, descriptions, categories and filter names namshi returns. [one of: en, ar]

**Returns:** product{product_id, variant_sku, title, brand, brand_code, brand_logo, url, description, images[], videos[], price, price_before_discount, discount_percent, currency, market, gtin (null — namshi publishes none), availability (in_stock|out_of_stock), rating, review_count, rating_scale, specifications[]{name, value}, variant_type, variants[]{variant_sku, size, size_conversions, available, stock_label, price, price_before_discount, discount_percent, currency, max_quantity, url}, breadcrumbs[]{name, path}, category_path, images_count, express_delivery, outlet, sold_by_namshi, returnable, exchangeable, final_sale, customizable, max_quantity, placement, country, language}

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

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

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