# H&M Search API Documentation
H&M Search API returns 36 products per page for a keyword or a category: name, price, original price, sale price and discount, colours with images, sizes with availability per size, availability, markers and images. The brand of an item can be another brand of the H&M group that hm.com sells (for example Weekday, ARKET or H&M Move), so filter on brand if you want H&M items only. Sort with sort and page with page. The answer carries the total, the sort options and the filters the search offers.
Send query (a keyword or a 10 digit article id) or category (a path from the H&M menu such as /ladies/shop-by-product/dresses, or the menu url), not both. Choose the locale with locale (en_us, de_de, en_gb, fr_fr, sv_se, en_in, pl_pl, es_es); prices are in the currency of the locale.
Limits: send at most one filter as filters=facet:value, for example colorWithNames:black_000000 or sale:true. Take facet and value from the filters of an unfiltered search. Size and price filters, several filters and a filter with a category are not supported and return 422. A page past the last page, an unknown category and a filter that matches nothing return 422. A page that is not the requested page, or a sort or filter that H&M did not apply, is never returned. A successful request costs 1 credit. Failed requests are not billable.
- **Documentation:** [https://scrappa.co/docs/hm-api/hm_search](https://scrappa.co/docs/hm-api/hm_search)
- **API group:** H&M API
- **Endpoint:** `GET https://scrappa.co/api/hm/search`
## Authentication
Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | No | Search keyword or 10 digit article id. Send query or category. |
| `category` | string | No | Category path from the H&M menu, for example /ladies/shop-by-product/dresses, or the menu url. Send category or query. |
| `locale` | string | No | Locale: en_us (default), de_de, en_gb, fr_fr, sv_se, en_in, pl_pl or es_es. |
| `page` | integer | No | One-based page number, 1 to 250 (default 1). A page past the last page returns 422. |
| `sort` | string | No | RELEVANCE (default), NEWEST_FIRST, PRICE_ASCENDING or PRICE_DESCENDING. |
| `filters` | string | No | One filter as facet:value, for example colorWithNames:black_000000 or sale:true. Query search only. Size and price filters are not supported. |
## Example response
```json
{
"data": {
"page": 1,
"sort": "PRICE_ASCENDING",
"items": [
{
"url": "https://www2.hm.com/en_us/productpage.1331684001.html",
"name": "Denim Jeggings",
"brand": "H&M",
"price": 5.99,
"sizes": [
{
"id": "004",
"label": "4-6M",
"availability": "in_stock"
},
{
"id": "005",
"label": "6-9M",
"availability": "out_of_stock"
},
{
"id": "006",
"label": "9-12M",
"availability": "out_of_stock"
}
],
"colour": "Light blue",
"images": [
{
"url": "https://image.hm.com/assets/hm/51/4d/514d63891a6c205601c58960e88147fc43add575.jpg",
"type": "DescriptiveDetail"
}
],
"is_new": false,
"colours": [
{
"url": "https://www2.hm.com/en_us/productpage.1331684001.html",
"code": "767F99",
"name": "Light blue",
"image_url": "https://image.hm.com/assets/hm/28/de/28dea0c1a1b1eaa2686d40cf893aeb3a624432da.jpg",
"article_id": "1331684001"
}
],
"markers": [],
"currency": "USD",
"in_stock": true,
"has_video": false,
"image_url": "https://image.hm.com/assets/hm/28/de/28dea0c1a1b1eaa2686d40cf893aeb3a624432da.jpg",
"article_id": "1331684001",
"sale_price": 5.99,
"colour_code": "767F99",
"coming_soon": false,
"is_multipack": false,
"member_price": null,
"category_code": "kids_baby_girl_clothing_trousersjeans_jeans",
"colour_shades": [
"Blue gray",
"Bright blue",
"Pastel blue",
"Royal blue"
],
"original_price": 12.99,
"model_image_url": "https://image.hm.com/assets/hm/28/de/28dea0c1a1b1eaa2686d40cf893aeb3a624432da.jpg",
"discount_percent": 54
},
{
"url": "https://www2.hm.com/en_us/productpage.1272095006.html",
"name": "Flared Jeggings",
"brand": "H&M",
"price": 7.49,
"sizes": [
{
"id": "008",
"label": "1\u00bd-2Y",
"availability": "in_stock"
},
{
"id": "009",
"label": "2-3Y",
"availability": "out_of_stock"
},
{
"id": "010",
"label": "3-4Y",
"availability": "out_of_stock"
}
],
"colour": "Light gray",
"images": [
{
"url": "https://image.hm.com/assets/hm/13/f2/13f26f0e9bf441fa0d2114d9a0c06880817b5c6d.jpg",
"type": "DescriptiveDetail"
}
],
"is_new": false,
"colours": [
{
"url": "https://www2.hm.com/en_us/productpage.1272095006.html",
"code": "666B75",
"name": "Light gray",
"image_url": "https://image.hm.com/assets/hm/a8/17/a817c3912200811f3ef7b26591f6a6978d5f4676.jpg",
"article_id": "1272095006"
},
{
"url": "https://www2.hm.com/en_us/productpage.1272095002.html",
"code": "4C5164",
"name": "Dark denim blue",
"image_url": "https://image.hm.com/assets/hm/75/7a/757aa338258de152be92e1633278d3a25fb0e1c4.jpg",
"article_id": "1272095002"
}
],
"markers": [],
"currency": "USD",
"in_stock": true,
"has_video": false,
"image_url": "https://image.hm.com/assets/hm/a8/17/a817c3912200811f3ef7b26591f6a6978d5f4676.jpg",
"article_id": "1272095006",
"sale_price": 7.49,
"colour_code": "666B75",
"coming_soon": false,
"is_multipack": false,
"member_price": null,
"category_code": "kids_clothing_jeans_flared",
"colour_shades": [
"Dark gray",
"Stone"
],
"original_price": 19.99,
"model_image_url": "https://image.hm.com/assets/hm/a8/17/a817c3912200811f3ef7b26591f6a6978d5f4676.jpg",
"discount_percent": 63
}
],
"query": "jeans",
"total": 1470,
"filter": null,
"locale": "en_us",
"filters": [
{
"id": "colorWithNames",
"name": "ColorWithNames",
"values": [
{
"count": 218,
"value": "black_000000"
},
{
"count": 878,
"value": "blue_0000ff"
}
]
},
{
"id": "sale",
"name": "Sale",
"values": [
{
"count": 1389,
"value": "false"
},
{
"count": 81,
"value": "true"
}
]
}
],
"category": null,
"currency": "USD",
"page_size": 36,
"suggestions": [
"jeans",
"jeans women",
"jeans men"
],
"total_pages": 41,
"sort_options": [
{
"id": "RELEVANCE",
"label": "Relevance"
},
{
"id": "NEWEST_FIRST",
"label": "New"
},
{
"id": "PRICE_ASCENDING",
"label": "Lowest price"
},
{
"id": "PRICE_DESCENDING",
"label": "Highest price"
}
]
},
"meta": {
"credits": 1,
"billable": true,
"endpoint_family": "search"
},
"success": true
}
```
## Errors
| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid, the category is unknown, the page is past the last page or the filter matches nothing. This response is not billable. |
| 503 | Upstream Unavailable | H&M could not be reached, or it returned data that does not match the request (another page, another sort, a filter that was not applied). This response is not billable and is retryable. |
## More Scrappa resources
- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)