# H\&M API Scraper (`rl1987/h-and-m-api-scraper`) Actor

Scrapes H\&M product search results (PLP) and product detail (PDP) data via the mobile app's backend APIs.

- **URL**: https://apify.com/rl1987/h-and-m-api-scraper.md
- **Developed by:** [R.L.](https://apify.com/rl1987) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 plp results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

### What does H\&M API Scraper do?

H\&M API Scraper extracts product data directly from the backend APIs used by the official [H\&M](https://www2.hm.com/) Android app, instead of rendering and scraping HTML pages. Give it one or more search terms and it returns the full product-listing-page (PLP) result set for each — product names, prices, availability, color swatches, sizes/stock, images, and URLs — and, optionally, the deeper product-detail-page (PDP) data for every product found (description, material composition, price validity dates, and category tree).

Because this Actor talks to the app's JSON APIs, it's fast and doesn't need a browser. Run it on demand, on a [schedule](https://docs.apify.com/platform/schedules), or wire it into your pipeline via the [Apify API](https://docs.apify.com/api/v2) or [integrations](https://apify.com/integrations) (Make, Zapier, n8n, Google Sheets, and more).

### Why use H\&M API Scraper?

- **Price and stock monitoring** — track H\&M prices, discounts, and per-size stock levels for competitor or catalog research.
- **Catalog enrichment** — pull material composition, category trees, and product codes to enrich an internal product database.
- **Market research** — sample search results across locales (`en_us`, `en_gb`, `de_de`, ...) to compare regional pricing and assortment.

### How to use H\&M API Scraper

1. Open the Actor's **Input** tab.
2. Add one or more **Search queries** (e.g. `jeans`, `summer dress`).
3. Optionally set a **Locale**, cap the number of items per query, and choose whether to fetch full product details (PDP).
4. Click **Start** and download the results from the **Dataset** tab once the run finishes.

### Input

| Field | Type | Description |
|---|---|---|
| `searchQueries` | array of strings | Search terms to run against the PLP (search) API. |
| `locale` | string | Locale for search results, e.g. `en_us`, `en_gb`, `de_de`. Controls language/currency. |
| `maxItemsPerQuery` | integer | Max products to collect per query. `0` = unlimited (all pages). |
| `fetchProductDetails` | boolean | Also fetch PDP data (description, materials, category tree) for each product. |
| `market` | string | Market code for the PDP endpoint, format `hm-<country>`. Only `hm-us` is confirmed reliable across product codes. |
| `pdpLang` | string | Language code for PDP responses, e.g. `en`, `de`. |
| `proxyConfiguration` | object | Optional [proxy configuration](https://docs.apify.com/platform/proxy). |

See the **Input** tab for the full JSON schema.

### Output

Each dataset item is a flat object combining the PLP product and, if enabled, its matching PDP data — no nested `plp`/`pdp` wrapper objects:

```json
{
  "searchQuery": "jeans",
  "locale": "en_us",
  "productId": "1353272001",
  "productName": "Slim Jeans",
  "brandName": "H&M",
  "price": 29.99,
  "formattedPrice": "$29.99",
  "stockState": "Available",
  "inStock": true,
  "colors": ["Denim blue"],
  "articleIds": ["1353272001"],
  "sizes": ["S", "M", "L"],
  "imageUrl": "https://image.hm.com/assets/hm/...jpg",
  "productUrl": "https://www2.hm.com/en_us/productpage.1353272001.html",
  "pdpCode": "1353272001",
  "pdpName": "Slim Jeans",
  "description": "...",
  "currency": "USD",
  "priceValidFrom": "2026-02-03T23:00:00+00:00",
  "priceValidTo": "2999-12-31T23:00:00+00:00",
  "mainCategory": "Jeans",
  "supercategories": ["Clothing", "Jeans"],
  "fits": ["Slim fit"],
  "baseProductCode": "1353272_group_001",
  "ancestorProductCode": "1353272"
}
```

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel from the **Dataset** tab.

#### Main output fields

| Field | Source | Description |
|---|---|---|
| `productId` | PLP | Product/article code, also used to fetch PDP data. |
| `productName` / `brandName` | PLP | Product display name and brand. |
| `price` / `formattedPrice` | PLP | Listing price, raw and formatted. |
| `stockState` / `inStock` | PLP | Availability. |
| `colors` / `articleIds` | PLP | Color variants and their per-color article ids. |
| `sizes` | PLP | Sizes currently in stock. |
| `imageUrl` / `imageUrls` | PLP | Main product image and gallery images. |
| `productUrl` | PLP | Link to the product page. |
| `description` | PDP | Full product description. |
| `currency` / `priceValidFrom` / `priceValidTo` | PDP | Price and its validity date range. |
| `mainCategory` / `supercategories` | PDP | Category tree. |
| `baseProductCode` / `ancestorProductCode` | PDP | Links color variants of the same garment together. |

### Pricing / Cost estimation

This Actor makes lightweight JSON API requests (no browser rendering), so it's cheap to run. Cost scales with the number of search queries, pages per query, and whether PDP detail fetching is enabled (roughly one extra request per product). Apify's free tier is generally enough to try it out on a handful of queries.

### Tips

- Leave `fetchProductDetails` off if you only need listing-level data (price, name, stock) — this roughly halves the number of requests.
- `maxItemsPerQuery: 0` collects every page for a query; set a cap for quick sampling runs.
- Only `market: "hm-us"` is confirmed to reliably resolve product codes on the PDP endpoint; other market codes may return an "Invalid baseStore or locale" error.

### FAQ, disclaimers, and support

This Actor calls publicly reachable JSON endpoints used by H\&M's own mobile app. It is intended for research and legitimate data-collection use; you're responsible for complying with H\&M's Terms of Service and applicable law in your jurisdiction. Endpoint behavior may change without notice. Found a bug or need a custom variant? Open an issue on the Actor's **Issues** tab.

# Actor input Schema

## `searchQueries` (type: `array`):

Search terms to query on the H\&M product-listing (search) API, e.g. "jeans", "summer dress".

## `locale` (type: `string`):

Region/locale used for the search endpoint. Controls language and currency of results. en\_us, en\_gb, and de\_de are confirmed live; others follow H\&M's standard site locale pattern.

## `maxItemsPerQuery` (type: `integer`):

Maximum number of products to collect per search query. 0 = unlimited (collect all pages).

## `fetchProductDetails` (type: `boolean`):

For each product found in search results, also fetch full product-detail data (description, materials, price validity, category tree) from the PDP endpoint.

## `market` (type: `string`):

Market code used for the product-detail endpoint, format hm-<country>. Only hm-us is confirmed to work reliably; other market codes may return "Invalid baseStore" errors. Controls pricing/catalog context, not which product codes are valid.

## `pdpLang` (type: `string`):

Language code used for the product-detail endpoint, e.g. en, de.

## `proxyConfiguration` (type: `object`):

Optional proxy configuration for outgoing requests.

## Actor input object example

```json
{
  "searchQueries": [
    "jeans"
  ],
  "locale": "en_us",
  "maxItemsPerQuery": 60,
  "fetchProductDetails": true,
  "market": "hm-us",
  "pdpLang": "en",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "searchQueries": [
        "jeans"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("rl1987/h-and-m-api-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 = { "searchQueries": ["jeans"] }

# Run the Actor and wait for it to finish
run = client.actor("rl1987/h-and-m-api-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 '{
  "searchQueries": [
    "jeans"
  ]
}' |
apify call rl1987/h-and-m-api-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rl1987/h-and-m-api-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/5na8foP02gjQ7P9Rv/builds/dAfA1P7Gy920Bb7gF/openapi.json