# Uniqlo Product Scraper (`crawlerbros/uniqlo-scraper`) Actor

Scrape UNIQLO.com product catalog - search by keyword, browse by category, or fetch full product detail by product ID. Prices, colors, sizes, ratings, images, descriptions, and category breadcrumbs, no login/cookies/proxy required.

- **URL**: https://apify.com/crawlerbros/uniqlo-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Uniqlo Product Scraper

Scrape [UNIQLO.com](https://www.uniqlo.com) — search products by keyword, browse by category, or fetch full detail for specific product IDs. Get prices, colors, sizes, ratings, images, descriptions, and category breadcrumbs straight from UNIQLO's public commerce API. No login, no cookies, no proxy required.

### What this actor does

- **Three modes:** `search` (keyword), `byCategory` (taxonomy browse), `byProductIds` (exact product lookup with full description/composition/care info)
- **Filters:** category, color family, gender/age line, price range, minimum rating, on-sale-only, in-stock-only, product flag/badge (New, Coming Soon, Pre-order, ...), sort order
- **Rich detail mode:** long description, fabric composition, care instructions, design details, country of origin, size chart URL, customer rating breakdown
- **Real customer reviews (optional, mode=byProductIds):** review title/comment, star rating, fit rating, purchased size/color, reviewer demographics (gender, age range, height/weight range, shoe size, location)
- **Empty fields are omitted**

### Output per product

#### Search / category browse records

- `productId`, `name`, `genderName`
- `priceValue`, `promoPriceValue`, `discountPercentage`, `onSale`, `currencyCode`, `currencySymbol`
- `ratingAverage`, `ratingCount`
- `colorNames[]`, `colorCount`, `sizeNames[]`, `lengthName` (fit-length variant for pants/shorts, e.g. "Short"/"Regular"/"Tall")
- `colorHexCodes` (map of color name → swatch hex, for solid colors only), `representativeColorHex`
- `imageUrl`, `colorImageUrls[]`
- `flagNames[]` (e.g. "Limited-Time Offer"), `flagCodes[]` (UNIQLO's internal badge codes), `promotionText`
- `inStock` (representative color/size currently purchasable), `storeStockOnly` (only available in physical stores, not online)
- `sourceUrl`
- `recordType: "product"`, `scrapedAt`

#### Product-detail records (mode=byProductIds) — everything above, plus:

- `categoryName`, `subcategoryName`, `breadcrumbClass`, `breadcrumbGender`
- `shortDescription`, `longDescription`, `composition`, `careInstruction`, `washingInformation`, `designDetail`
- `additionalInformation` (e.g. color-nuance notes), `promoConditionText` (e.g. "Buy 2 for $14.90")
- `countriesOfOrigin[]`, `tagNames[]`, `sizeChartUrl`, `subImageUrls[]`, `relatedProductIds[]` (other fits/washes of the same style UNIQLO cross-sells on the product page)
- `ratingFit` (1-5 average fit score), `ratingBreakdown` (star-count histogram: `fiveStar`…`oneStar`)
- `inStockColorNames[]` (colors with at least one currently purchasable size)
- `inStockSizeNames[]` (sizes with at least one currently purchasable color)
- `isBestSeller`
- `reviews[]` (only when `includeReviews=true`) — each entry: `reviewId`, `rating`, `fitRating`, `title`, `comment`, `reviewerName`, `reviewerGender`, `reviewerLocation`, `reviewerAgeRange`, `reviewerHeightRange`, `reviewerWeightRange`, `reviewerShoeSize`, `purchasedSize`, `purchasedColorName`, `helpfulCount`, `isIncentivized`, `createdAt`; `reviewsFetched` (count)

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | select | `search` | `search` / `byCategory` / `byProductIds` |
| `searchQuery` | string | `jeans` | Keyword (mode=search) |
| `category` | select | – | Product category (required for `byCategory`, optional refinement for `search`) |
| `productIds` | array | – | Product IDs, e.g. `E482279-000` (mode=byProductIds) |
| `gender` | select | `any` | Women / Men / Kids / Baby / Unisex |
| `colorGroup` | select | – | Color family (White, Black, Blue, ...) |
| `sizeName` | select | – | Restrict results to a specific size (XS-3XL, waist inseams, shoe sizes, bra sizes, baby/kids ages) |
| `sortBy` | select | `relevance` | Relevance / Newest / Price asc / Price desc / Recommended / Popular |
| `minPrice` / `maxPrice` | int | – | Price range in USD |
| `minRating` | int | – | Minimum average customer rating (0–5) |
| `onSaleOnly` | bool | `false` | Only products currently discounted |
| `inStockOnly` | bool | `false` | Only products currently purchasable online |
| `flagFilter` | select | – | Only products carrying this UNIQLO badge (New, Coming Soon, Pre-order, Sale, Limited-Time Offer, Multibuy, New color, Select Colors/Sizes Only, Made with recycled materials, UNISEX) |
| `lengthFilter` | select | – | Only pants/shorts with this fit-length variant (Short / Regular / Tall) |
| `includeReviews` | bool | `false` | mode=byProductIds only — fetch real customer reviews per product |
| `maxReviewsPerProduct` | int | `5` | Most-recent reviews to fetch per product (0–25, UNIQLO API cap) |
| `maxItems` | int | `30` | Hard cap (1–1000) |

#### Example: browse a category

```json
{
  "mode": "byCategory",
  "category": "Jeans",
  "gender": "WOMEN",
  "sortBy": "priceLowToHigh",
  "maxItems": 40
}
```

#### Example: lookup exact products

```json
{
  "mode": "byProductIds",
  "productIds": ["E482279-000", "E465760-000"]
}
```

### Use cases

- **Price monitoring** — track UNIQLO pricing and promotions across categories
- **Assortment analysis** — see the full color/size range for a given item
- **Trend research** — compare "newest" vs "popular" sort to spot what's trending
- **Competitive retail intelligence** — benchmark fast-fashion pricing and ratings
- **Product feed enrichment** — pull rich descriptions, composition, and care data for cataloging

### FAQ

**Do I need a proxy or login?** No — the actor calls UNIQLO's public commerce API directly with a standard browser user agent. No cookies, API key, or Apify proxy credit required.

**Which country/locale does this cover?** The US storefront (`uniqlo.com/us/en`). Prices are in USD.

**What's the difference between `search` and `byCategory`?** `search` matches a free-text keyword against product names/descriptions; `byCategory` browses UNIQLO's own category taxonomy (no keyword needed) and is closer to clicking through the site's navigation menus.

**Why do some products show `onSale: true`?** UNIQLO periodically runs limited-time promotions; when the current promo price is below the standard base price, the actor flags it, includes both prices, and computes `discountPercentage` (rounded % off the base price).

**How do I find a product's ID?** Every record includes `productId` and `sourceUrl`. You can also copy it from a UNIQLO product page URL: `uniqlo.com/us/en/products/E482279-000/...`.

**Are ratings available for every product?** Only for products that have received customer reviews; `ratingAverage`/`ratingCount` are omitted otherwise (never emitted as `0`/`null`).

**How do I get customer review text?** Set `includeReviews: true` with `mode: byProductIds`. Each detail record gets a `reviews[]` array with the review title, comment, star/fit rating, purchased size/color, and any reviewer demographics they shared (some are optional and omitted per-reviewer if not provided). Use `maxReviewsPerProduct` (0–25) to control how many are fetched per product.

# Actor input Schema

## `mode` (type: `string`):

What to fetch.

## `searchQuery` (type: `string`):

Free-text keyword search (mode=search), e.g. `jeans`, `hoodie`, `airism`.

## `category` (type: `string`):

Restrict results to a UNIQLO product category. Required for mode=byCategory; optional refinement for mode=search.

## `productIds` (type: `array`):

UNIQLO product IDs, e.g. `E482279-000` (found in search results or in a product URL: uniqlo.com/us/en/products/{productId}).

## `gender` (type: `string`):

Filter results to a single gender/age line.

## `colorGroup` (type: `string`):

Restrict results to a color family.

## `sizeName` (type: `string`):

Restrict results to a specific size (as shown on the site, e.g. `M`, `28inch`, `Age3(100)`).

## `sortBy` (type: `string`):

Result ordering (mode=search / byCategory).

## `minPrice` (type: `integer`):

Drop products cheaper than this.

## `maxPrice` (type: `integer`):

Drop products more expensive than this.

## `minRating` (type: `integer`):

Drop products with a lower average customer rating. Products with no ratings are excluded when this is set.

## `onSaleOnly` (type: `boolean`):

Only keep products currently discounted below their base price.

## `inStockOnly` (type: `boolean`):

Only keep products whose representative color/size is currently purchasable online.

## `lengthFilter` (type: `string`):

Only keep pants/shorts with this fit-length variant, as shown on the site (e.g. `Regular` vs `Tall` inseam). Products with no length variant (most non-bottoms) are excluded when this is set.

## `flagFilter` (type: `string`):

Only keep products carrying this UNIQLO merchandising flag/badge (as shown on the site), e.g. `New` or `Coming Soon`.

## `includeReviews` (type: `boolean`):

mode=byProductIds only. Fetch real customer reviews (title, comment, star rating, fit rating, purchased size/color, reviewer demographics) for each product.

## `maxReviewsPerProduct` (type: `integer`):

Only used when `includeReviews` is on. Most-recent reviews are returned first (UNIQLO API cap: 25 per request).

## `maxItems` (type: `integer`):

Hard cap on emitted records.

## Actor input object example

```json
{
  "mode": "search",
  "searchQuery": "jeans",
  "category": "",
  "productIds": [],
  "gender": "any",
  "colorGroup": "",
  "sizeName": "",
  "sortBy": "relevance",
  "onSaleOnly": false,
  "inStockOnly": false,
  "lengthFilter": "",
  "flagFilter": "",
  "includeReviews": false,
  "maxReviewsPerProduct": 5,
  "maxItems": 30
}
```

# Actor output Schema

## `products` (type: `string`):

Dataset containing all scraped UNIQLO products.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "searchQuery": "jeans",
    "productIds": [],
    "gender": "any",
    "sortBy": "relevance",
    "onSaleOnly": false,
    "inStockOnly": false,
    "includeReviews": false,
    "maxReviewsPerProduct": 5,
    "maxItems": 30
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/uniqlo-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "searchQuery": "jeans",
    "productIds": [],
    "gender": "any",
    "sortBy": "relevance",
    "onSaleOnly": False,
    "inStockOnly": False,
    "includeReviews": False,
    "maxReviewsPerProduct": 5,
    "maxItems": 30,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/uniqlo-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "searchQuery": "jeans",
  "productIds": [],
  "gender": "any",
  "sortBy": "relevance",
  "onSaleOnly": false,
  "inStockOnly": false,
  "includeReviews": false,
  "maxReviewsPerProduct": 5,
  "maxItems": 30
}' |
apify call crawlerbros/uniqlo-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlerbros/uniqlo-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/DsLjGsStY7eW6ZQ0W/builds/5jqTnrLMXrqMAGRfk/openapi.json