# Alternate Product Search API Documentation

`GET /api/alternate/search` returns Alternate products as structured JSON. A page holds up to 24 products.

## What you get

Each item has `position`, `id`, `title`, `brand`, `url`, `price`, `original_price`, `discount_percent`, `currency`, `rating`, `review_count`, `online_available`, `delivery_status`, `delivery_window` and `image`. Use `id` unchanged with the product and reviews endpoints.

## Prices and filters

Prices are numbers in EUR. `original_price` is the struck price and `discount_percent` the saving. `q` searches keywords. Use `t` with a category id from the storefront tree, or `category` with a category path. `s`, `pr1`, `pr2` and `filter_N` are passed to the storefront and honoured. `page` is 1-30. The page reads the storefront result counter, so a short query never invents later pages.

## Credits

A successful request costs **1 credit**. Errors, challenges and `404` answers cost nothing. The response shows the charge in `meta.credits_charged`.

- **Documentation:** [https://scrappa.co/docs/alternate-api/alternate_search](https://scrappa.co/docs/alternate-api/alternate_search)
- **API group:** Alternate API
- **Endpoint:** `GET https://scrappa.co/api/alternate/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 |
| --- | --- | --- | --- |
| `q` | string | No | Search words. Use this or a category. |
| `t` | integer | No | Category id from the storefront tree. Use this or q. |
| `category` | string | No | Category path such as Alle-Fernseher. Use this or q. |
| `s` | string | No | Storefront sort key, for example relevance. |
| `pr1` | number | No | Lowest price in euros. |
| `pr2` | number | No | Highest price in euros. Must not be lower than pr1. |
| `filter_N` | string | No | Storefront facet id and value, for example filter_7171=716. |
| `page` | integer | No | Result page of 24 products, 1-30. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/alternate/search?q=grafikkarte"
```

## Example response

```json
{
    "success": true,
    "query": "grafikkarte",
    "category": null,
    "items": [
        {
            "position": 1,
            "id": "100152872",
            "title": "Gainward GeForce RTX 4070 Ti Phoenix",
            "brand": "Gainward",
            "url": "https://www.alternate.de/html/product/100152872",
            "price": 999,
            "original_price": 1199,
            "discount_percent": 16,
            "currency": "EUR",
            "rating": 4.5,
            "review_count": 39,
            "online_available": true,
            "delivery_status": "Sofort verf\u00fcgbar",
            "delivery_window": null,
            "image": "https://www.alternate.de/p/600x600/example@@100152872.jpg"
        }
    ],
    "page": 1,
    "page_size": 24,
    "next_page": 2,
    "has_more": true,
    "total": 144,
    "applied_filters": {
        "q": "grafikkarte"
    },
    "meta": {
        "endpoint_family": "alternate-search",
        "billable": true,
        "attempts": 1,
        "credits_charged": 1,
        "unavailable_reason": []
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter is missing, unknown, conflicting or unusable. Unknown parameters are rejected, never ignored. Non-billable. |
| 503 | Upstream Unavailable | The storefront could not be reached, answered with a challenge, or changed its page shape (`upstream_blocked`, `upstream_unavailable`, `parser_drift`). Retryable and never billed. Clients are never rate limited. |

## 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)
