# Allegro Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/allegro/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 3 credits per call |
| **Documentation** | https://www.piloterr.com/library/allegro-search |

## Description

Allegro Search API. Query product listings by keyword, optional page number, or full allegro.pl listing URL. Returns results with prices, sellers, sponsorship flags and pagination. 3 credits per call.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/allegro/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search keyword 'mufowa' (page 1, 1628 results)

```json
{
  "results": [
    {
      "price": 17.84,
      "title": "ZŁĄCZKA MUFOWA ZAPRASOWYWANA PEX ALUPEX 32 x 1'' GW TYP SZCZĘK \"U\" MOSIĄDZ",
      "currency": "PLN",
      "offer_id": "13183761915",
      "position": 0,
      "image_url": "https://a.allegroimg.com/s360/116ee2/44bad5d14926a20193c6cb2d8c29/ZLACZKA-MUFOWA-ZAPRASOWYWANA-PEX-ALUPEX-32-x-1-GW-TYP-SZCZEK-U-MOSIADZ",
      "seller_id": "36900410",
      "product_id": "8d15c247-8aeb-4b82-b078-dfae9aa50931",
      "listing_url": "https://allegro.pl/oferta/zlaczka-mufowa-zaprasowywana-pex-alupex-32-x-1-gw-typ-szczek-u-mosiadz-13183761915?bi_s=ads&bi_m=productlisting%3Adesktop%3Aquery&bi_c=ZWUxZGI3YTktZjhmYS00M2U1LWFmZjktMWE2YWM2N2NmZGJjAA&bi_t=ape",
      "seller_name": "HYDMAR",
      "is_sponsored": true,
      "delivery_info": "28,33 zł z dostawą"
    },
    {
      "price": 3.8,
      "title": "Mufa ocynkowana TICKA złączka mufowa fi 125 do rur spiro wentylacja",
      "currency": "PLN",
      "offer_id": "16509668391",
      "position": 1,
      "image_url": "https://a.allegroimg.com/s360/112b7f/92e216854e069e9f43f2adbc4c74/Mufa-ocynkowana-TICKA-zlaczka-mufowa-fi-125-do-rur-spiro-wentylacja",
      "seller_id": "48847819",
      "product_id": "6357bbc1-df4f-48ec-8e99-b346a1326f3c",
      "listing_url": "https://allegro.pl/produkt/mufa-ocynkowana-ticka-zlaczka-mufowa-fi-125-do-rur-spiro-wentylacja-6357bbc1-df4f-48ec-8e99-b346a1326f3c?offerId=16509668391",
      "seller_name": "amster24_pl",
      "is_sponsored": false,
      "delivery_info": "14,29 zł z dostawą"
    },
    {
      "price": 16.03,
      "title": "ZŁĄCZKA MUFOWA ZAPRASOWYWANA PEX ALUPEX FI 25 mm x 1'' GW TYP SZCZĘK \"U\" MO",
      "currency": "PLN",
      "offer_id": "13183762597",
      "position": 2,
      "image_url": "https://a.allegroimg.com/s360/114c67/910f7eea4200aec18626dc2d5914/ZLACZKA-MUFOWA-ZAPRASOWYWANA-PEX-ALUPEX-FI-25-mm-x-1-GW-TYP-SZCZEK-U-MO",
      "seller_id": "36900410",
      "product_id": "261dee24-a4cc-4e11-bbb4-037bb429ad8d",
      "listing_url": "https://allegro.pl/oferta/zlaczka-mufowa-zaprasowywana-pex-alupex-fi-25-mm-x-1-gw-typ-szczek-u-mo-13183762597?bi_s=ads&bi_m=productlisting%3Adesktop%3Aquery&bi_c=ZWUxZGI3YTktZjhmYS00M2U1LWFmZjktMWE2YWM2N2NmZGJjAA&bi_t=ape",
      "seller_name": "HYDMAR",
      "is_sponsored": true,
      "delivery_info": "25,02 zł z dostawą"
    }
  ],
  "pagination": {
    "next": "https://allegro.pl/listing?string=mufowa&p=2",
    "page": 1,
    "per_page": 74,
    "total_pages": 13,
    "total_results": 1628
  }
}
```

### Search keyword 'mufowa' page 2 via page param

```json
{
  "results": [
    {
      "price": 17.84,
      "title": "ZŁĄCZKA MUFOWA ZAPRASOWYWANA PEX ALUPEX 32 x 1'' GW TYP SZCZĘK \"U\" MOSIĄDZ",
      "currency": "PLN",
      "offer_id": "13183761915",
      "position": 0,
      "image_url": "https://a.allegroimg.com/s360/116ee2/44bad5d14926a20193c6cb2d8c29/ZLACZKA-MUFOWA-ZAPRASOWYWANA-PEX-ALUPEX-32-x-1-GW-TYP-SZCZEK-U-MOSIADZ",
      "seller_id": "36900410",
      "product_id": "8d15c247-8aeb-4b82-b078-dfae9aa50931",
      "listing_url": "https://allegro.pl/oferta/zlaczka-mufowa-zaprasowywana-pex-alupex-32-x-1-gw-typ-szczek-u-mosiadz-13183761915?bi_s=ads&bi_m=productlisting%3Adesktop%3Aquery&bi_c=ZWUxZGI3YTktZjhmYS00M2U1LWFmZjktMWE2YWM2N2NmZGJjAA&bi_t=ape",
      "seller_name": "HYDMAR",
      "is_sponsored": true,
      "delivery_info": "28,33 zł z dostawą"
    },
    {
      "price": 3.8,
      "title": "Mufa ocynkowana TICKA złączka mufowa fi 125 do rur spiro wentylacja",
      "currency": "PLN",
      "offer_id": "16509668391",
      "position": 1,
      "image_url": "https://a.allegroimg.com/s360/112b7f/92e216854e069e9f43f2adbc4c74/Mufa-ocynkowana-TICKA-zlaczka-mufowa-fi-125-do-rur-spiro-wentylacja",
      "seller_id": "48847819",
      "product_id": "6357bbc1-df4f-48ec-8e99-b346a1326f3c",
      "listing_url": "https://allegro.pl/produkt/mufa-ocynkowana-ticka-zlaczka-mufowa-fi-125-do-rur-spiro-wentylacja-6357bbc1-df4f-48ec-8e99-b346a1326f3c?offerId=16509668391",
      "seller_name": "amster24_pl",
      "is_sponsored": false,
      "delivery_info": "14,29 zł z dostawą"
    }
  ],
  "pagination": {
    "next": "https://allegro.pl/listing?string=mufowa&p=3",
    "page": 2,
    "per_page": 74,
    "total_pages": 13,
    "total_results": 1628
  }
}
```

## Documentation

## Overview
The **Allegro Search API** queries product listings on allegro.pl, Poland's largest e-commerce marketplace. Pass a **keyword**, a full **`/listing` URL**, or a keyword with **`page`**, and receive structured JSON with `results[]` and `pagination`.

Costs **3 credits** per call. Parses Allegro's `__listing_StoreState` JSON from the rendered search page.

Pass each `listing_url` to [Allegro Product](https://www.piloterr.com/library/allegro-product) for full PDP data (**3 credits** per call).

## Quickstart
```
GET https://api.piloterr.com/v2/allegro/search?query=mufowa
GET https://api.piloterr.com/v2/allegro/search?query=mufowa&page=2
GET https://api.piloterr.com/v2/allegro/search?query=https://allegro.pl/listing?string=mufowa
GET https://api.piloterr.com/v2/allegro/search?query=https://allegro.pl/listing?string=mufowa&p=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search keyword or full Allegro listing URL (`/listing?string=…`) |
| `page` | integer | no | Page number (default `1`). Overrides `p=` in a listing URL |

## Input formats
| Format | Example | Notes |
|---|---|---|
| Keyword | `mufowa` | Resolves to page 1 (`/listing?string=mufowa`) |
| Keyword + `page` | `query=mufowa`, `page=2` | Appends `p=2` to the listing URL |
| Listing URL (page 1) | `https://allegro.pl/listing?string=mufowa` | Paste the URL copied from Allegro search |
| Listing URL (pagination) | `https://allegro.pl/listing?string=mufowa&p=2` | `p` in the URL selects the page |

When both a listing URL and `page` are set, `page` overrides `p=` in the URL.

## Response fields

### `results[]`
| Field | Type | Description |
|---|---|---|
| `product_id` | string | Allegro product UUID |
| `offer_id` | string | Offer ID (numeric string) |
| `title` | string | Listing title |
| `listing_url` | string | Full offer or product URL on allegro.pl |
| `image_url` | string | Thumbnail image URL |
| `price` | number | Listed price |
| `currency` | string | Price currency (`PLN`) |
| `seller_id` | string | Seller account ID |
| `seller_name` | string | Seller display name |
| `position` | integer | Position on the SERP (0-based) |
| `is_sponsored` | boolean | `true` for sponsored placements |
| `delivery_info` | string | Delivery price snippet when shown |

### `pagination`
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page number |
| `per_page` | integer | Listings returned on this page |
| `total_results` | integer | Total matching listings |
| `total_pages` | integer | Total pages available |
| `next` | string | Next page listing URL when available |

## Error codes
| Code | Meaning |
|---|---|
| `400` | Empty or invalid `query`, or non-allegro.pl URL |
| `404` | No listings found for the search |
| `500` | Page fetch or parse error |

## Notes
- Results include organic and sponsored listings (`is_sponsored`).
- Polish characters (ą, ę, ó, ż, etc.) are fully supported in keywords.
- Banner rows (e.g. best-price guarantee) are filtered out of `results[]`.
- Empty SERPs return `404`, not an empty array.

## Main use cases
- Monitor competitor listings and sponsored placements on Allegro SERPs
- Paginate with `page=2` or listing URLs with `&p=2`
- Feed repricing engines with live PLN prices and seller metadata
- Discover `listing_url` values for [Allegro Product](https://www.piloterr.com/library/allegro-product) enrichment (**3 credits** per call)