# ASOS API scraper — product search, filters, sale & new-in browse, multi-region product detail (sizes/stock/prices), reviews & similar items across UK, US, DE, FR and global markets (asos.com)

> Keyword product search across the ASOS catalogue with filters (price, brand, colour, size, product type, sale, new-in, discount), sorting and offset/limit pagination.
> ReefAPI engine `asos` · 11 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/asos/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 or blocked 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, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /asos/v1/search — 1 credit
Keyword product search across the ASOS catalogue with filters (price, brand, colour, size, product type, sale, new-in, discount), sorting and offset/limit pagination.

**Parameters:**
- `query` (string, required) — Search keyword (e.g. 'summer dress', 'nike trainers').
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]
- `lang` (string, optional) — Override the store's locale (advanced), e.g. en-GB, de-DE.
- `currency` (string, optional) — Override the store's currency (advanced), e.g. USD, EUR.
- `country` (string, optional) — Override ship-to country code (advanced), e.g. GB, US.
- `offset` (integer, optional, default 0) — Pagination offset (skip N). Page forward with meta.next_offset.
- `limit` (integer, optional, default 48) — Results per page (1-200, default 48); clamped to 200.
- `sort` (enum, optional) — Sort order. Omit for relevance (default). Only these keys are valid. [one of: freshness, pricedesc, priceasc]
- `min_price` (number, optional) — Minimum price filter (in the store's currency).
- `max_price` (number, optional) — Maximum price filter (in the store's currency).
- `brand` (string, optional) — Filter by brand — name (e.g. 'Nike', 'ASOS DESIGN') or facet id. Names are auto-resolved to ids; call the 'filters' action to list options.
- `colour` (string, optional) — Filter by colour — name (e.g. 'Black', 'Blue', 'Multi') or facet id.
- `size` (string, optional) — Filter by size — label (e.g. 'M', 'UK 10', 'XS') or facet id.
- `product_type` (string, optional) — Filter by product type facet id (e.g. 8416=Dresses); see 'filters'.
- `on_sale` (enum, optional) — Limit to marked-down items only. [one of: sale, new_season]
- `new_in_within` (enum, optional) — Limit to items added within this window (the site's 'New in' filter). [one of: today, yesterday, 7d, 14d, 28d]
- `discount` (enum, optional) — Minimum discount tier for marked-down items. [one of: 20, 30, 40, 50, 60, 60+]
- `channel` (string, optional) — Client channel (advanced).
- `key_store_dataversion` (string, optional) — Internal catalogue version token (advanced).

**Returns:** products[] (id, name, price, brand, colour, images, in_stock, colour variants), facets[] (brands/colours/sizes/price/discount/product-type), total, offset, has_more, next_offset

**Example request body:**
```json
{
  "query": "dress"
}
```

### POST /asos/v1/category — 1 credit
Browse all products in a category by category_id, with the same filters, sorting and pagination as search. Get category ids from the 'navigation' action.

**Parameters:**
- `category_id` (integer, required) — ASOS category id (the cid in a category URL; see navigation).
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]
- `lang` (string, optional) — Override the store's locale (advanced), e.g. en-GB, de-DE.
- `currency` (string, optional) — Override the store's currency (advanced), e.g. USD, EUR.
- `country` (string, optional) — Override ship-to country code (advanced), e.g. GB, US.
- `offset` (integer, optional, default 0) — Pagination offset (skip N). Page forward with meta.next_offset.
- `limit` (integer, optional, default 48) — Results per page (1-200, default 48); clamped to 200.
- `sort` (enum, optional) — Sort order. Omit for relevance (default). Only these keys are valid. [one of: freshness, pricedesc, priceasc]
- `min_price` (number, optional) — Minimum price filter (in the store's currency).
- `max_price` (number, optional) — Maximum price filter (in the store's currency).
- `brand` (string, optional) — Filter by brand — name (e.g. 'Nike', 'ASOS DESIGN') or facet id. Names are auto-resolved to ids; call the 'filters' action to list options.
- `colour` (string, optional) — Filter by colour — name (e.g. 'Black', 'Blue', 'Multi') or facet id.
- `size` (string, optional) — Filter by size — label (e.g. 'M', 'UK 10', 'XS') or facet id.
- `product_type` (string, optional) — Filter by product type facet id (e.g. 8416=Dresses); see 'filters'.
- `on_sale` (enum, optional) — Limit to marked-down items only. [one of: sale, new_season]
- `new_in_within` (enum, optional) — Limit to items added within this window (the site's 'New in' filter). [one of: today, yesterday, 7d, 14d, 28d]
- `discount` (enum, optional) — Minimum discount tier for marked-down items. [one of: 20, 30, 40, 50, 60, 60+]
- `channel` (string, optional) — Client channel (advanced).

**Returns:** products[], facets[], category_name, category_id, total, offset, has_more, next_offset

**Example request body:**
```json
{
  "category_id": "8799"
}
```

### POST /asos/v1/sale — 1 credit
On-sale / marked-down products only. Provide a keyword (query) or a category_id; supports the same filters, sort and pagination as search.

**Parameters:**
- `query` (string, optional) — Keyword to find sale items for (sale needs query OR category_id).
- `category_id` (integer, optional) — Category id to browse on sale (alternative to query).
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]
- `lang` (string, optional) — Override the store's locale (advanced), e.g. en-GB, de-DE.
- `currency` (string, optional) — Override the store's currency (advanced), e.g. USD, EUR.
- `country` (string, optional) — Override ship-to country code (advanced), e.g. GB, US.
- `offset` (integer, optional, default 0) — Pagination offset (skip N). Page forward with meta.next_offset.
- `limit` (integer, optional, default 48) — Results per page (1-200, default 48); clamped to 200.
- `sort` (enum, optional) — Sort order. Omit for relevance (default). Only these keys are valid. [one of: freshness, pricedesc, priceasc]
- `min_price` (number, optional) — Minimum price filter (in the store's currency).
- `max_price` (number, optional) — Maximum price filter (in the store's currency).
- `brand` (string, optional) — Filter by brand — name (e.g. 'Nike', 'ASOS DESIGN') or facet id. Names are auto-resolved to ids; call the 'filters' action to list options.
- `colour` (string, optional) — Filter by colour — name (e.g. 'Black', 'Blue', 'Multi') or facet id.
- `size` (string, optional) — Filter by size — label (e.g. 'M', 'UK 10', 'XS') or facet id.
- `product_type` (string, optional) — Filter by product type facet id (e.g. 8416=Dresses); see 'filters'.
- `on_sale` (enum, optional) — Limit to marked-down items only. [one of: sale, new_season]
- `new_in_within` (enum, optional) — Limit to items added within this window (the site's 'New in' filter). [one of: today, yesterday, 7d, 14d, 28d]
- `discount` (enum, optional) — Minimum discount tier for marked-down items. [one of: 20, 30, 40, 50, 60, 60+]

**Returns:** products[] (marked-down only) with price.previous + is_marked_down, facets[], total, offset, has_more, next_offset

**Example request body:**
```json
{
  "query": "dress"
}
```

### POST /asos/v1/new_in — 1 credit
Newest arrivals — freshness-sorted products, optionally limited to a recent window (today / last 7 / 14 / 28 days). Provide a keyword (query) or a category_id.

**Parameters:**
- `query` (string, optional) — Keyword for new arrivals (new_in needs query OR category_id).
- `category_id` (integer, optional) — Category id for new arrivals (e.g. 27108 = women's New In).
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]
- `lang` (string, optional) — Override the store's locale (advanced), e.g. en-GB, de-DE.
- `currency` (string, optional) — Override the store's currency (advanced), e.g. USD, EUR.
- `country` (string, optional) — Override ship-to country code (advanced), e.g. GB, US.
- `offset` (integer, optional, default 0) — Pagination offset (skip N). Page forward with meta.next_offset.
- `limit` (integer, optional, default 48) — Results per page (1-200, default 48); clamped to 200.
- `sort` (enum, optional) — Sort order. Omit for relevance (default). Only these keys are valid. [one of: freshness, pricedesc, priceasc]
- `min_price` (number, optional) — Minimum price filter (in the store's currency).
- `max_price` (number, optional) — Maximum price filter (in the store's currency).
- `brand` (string, optional) — Filter by brand — name (e.g. 'Nike', 'ASOS DESIGN') or facet id. Names are auto-resolved to ids; call the 'filters' action to list options.
- `colour` (string, optional) — Filter by colour — name (e.g. 'Black', 'Blue', 'Multi') or facet id.
- `size` (string, optional) — Filter by size — label (e.g. 'M', 'UK 10', 'XS') or facet id.
- `product_type` (string, optional) — Filter by product type facet id (e.g. 8416=Dresses); see 'filters'.
- `on_sale` (enum, optional) — Limit to marked-down items only. [one of: sale, new_season]
- `new_in_within` (enum, optional) — Limit to items added within this window (the site's 'New in' filter). [one of: today, yesterday, 7d, 14d, 28d]
- `discount` (enum, optional) — Minimum discount tier for marked-down items. [one of: 20, 30, 40, 50, 60, 60+]

**Returns:** products[] sorted newest-first, facets[], total, offset, has_more, next_offset

**Example request body:**
```json
{
  "query": "trainers"
}
```

### POST /asos/v1/product — 1 credit
full product detail (sizes/stock/description/images) by product_id or product_url

**Parameters:**
- `product_id` (string, optional) — ASOS product id. (product needs product_id OR product_url.)
- `product_url` (string, optional) — Full ASOS product URL (alternative to product_id).
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]

**Returns:** product{} — name, brand, gender, product_type, price, description, care_info, size_and_fit, images, variants[] (size, brand_size, sku, ean, colour, in_stock, per-variant price)

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

### POST /asos/v1/products — 1 credit
batch product detail for comma-separated product_ids

**Parameters:**
- `product_ids` (string, required) — Comma-separated ASOS product ids (max 20).
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]

**Returns:** products[] — full detail per id (best-effort; failed ids skipped)

### POST /asos/v1/navigation — 1 credit
category links from gender landing pages; format=tree returns nested path hierarchy

**Parameters:**
- `gender` (enum, optional) — Which landing page to read categories from. [one of: women, men]
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]
- `format` (enum, optional) — Output shape. [one of: flat, tree]

**Returns:** categories[] {id, name, url} (flat) OR tree[] nested (format=tree)

### POST /asos/v1/reviews — 1 credit
product reviews + rating summary from PDP embedded ratings blob (paginated)

**Parameters:**
- `product_id` (string, optional) — ASOS product id. (reviews needs product_id OR product_url.)
- `product_url` (string, optional) — Full ASOS product URL (alternative to product_id).
- `offset` (integer, optional, default 0) — Pagination offset (skip N). Page forward with meta.next_offset.
- `limit` (integer, optional, default 10) — Reviews per page (1-50, default 10).

**Returns:** rating{summary, distribution}, reviews[], total, offset, has_more, next_offset

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

### POST /asos/v1/similar — 1 credit
related products via same-brand search fallback (true mightLike API is account-gated)

**Parameters:**
- `product_id` (string, optional) — ASOS product id. (similar needs product_id OR product_url.)
- `product_url` (string, optional) — Full ASOS product URL (alternative to product_id).
- `limit` (integer, optional, default 12) — Max similar products (1-200, default 12).
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]

**Returns:** products[] same-brand related items, brand, product_id, total

**Example request body:**
```json
{
  "product_id": "210879654",
  "limit": 6
}
```

### POST /asos/v1/filters — 1 credit
available search/category facets (brands, colours, sizes, price ranges)

**Parameters:**
- `query` (string, optional) — Keyword to get facets for. (filters needs query OR category_id.)
- `category_id` (integer, optional) — Category id to get facets for (alternative to query).
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]
- `lang` (string, optional) — Override the store's locale (advanced), e.g. en-GB, de-DE.
- `currency` (string, optional) — Override the store's currency (advanced), e.g. USD, EUR.
- `country` (string, optional) — Override ship-to country code (advanced), e.g. GB, US.

**Returns:** facets[] (brands, colours, sizes, price ranges), total_products, category_name

### POST /asos/v1/suggestions — 1 credit
search autocomplete suggestions for partial query

**Parameters:**
- `query` (string, required) — Partial search text to autocomplete.
- `store` (enum, optional, default "COM") — ASOS market/store — sets default language, currency and ship-to country. [one of: COM, GB, US, DE, FR, ROW]
- `lang` (string, optional) — Override the store's locale (advanced), e.g. en-GB, de-DE.
- `currency` (string, optional) — Override the store's currency (advanced), e.g. USD, EUR.
- `country` (string, optional) — Override ship-to country code (advanced), e.g. GB, US.

**Returns:** suggestions[] {term, result_count, group}

**Example request body:**
```json
{
  "query": "dre"
}
```

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