1. How to search and browse offers


Allegro REST API allows you to browse and search through offers available on Allegro. With GET /offers/listing you can get such lists of offers.


GET /offers/listing is a resource that allows access to public data, therefore you can use the client_credentials flow for authorization.

The search result depends on the parameters you provide in the request. For a successful search, use one or more of the following variables:

  • phrase - a phrase you want to use when searching.

  • category.id - ID of the category you want to search for offers.

  • seller.id -D of a seller whose offers you want to search for. You can provide the ID of multiple sellers, e.g.: {seller.id}={value}&seller.id ={value}.

  • seller.login - login of a seller whose offers you want to search for. You can provide the login of multiple sellers, e.g.: {seller.login}={name}&seller.login ={neme}.

information

Note! You can only use one parameter out of {seller.id} and {seller.login} in a request.


You can combine above parameters in a single request, for example: GET https://api.allegro.pl/offers/listing?phrase={value}&seller.id={value}&category.id={value}

You can match the list of offers to your needs using the following parameters:

  • limit - specify the number of offers in the response (takes values ​​from 1-60, the default value is 60).

  • offset - select offset from which you want to download the next batch of data. The maximum value is 6000 (subtract the previously set limit from this value). When you use the seller.id/seller.login parameter in the request the maximum value is increased to 120,000.

  • fallback - define how the search engine should behave if we do not find any results for the given phrase (default value: true). This means that if we do not find results in a given category, we will also search through other categories and return related offers in the response. If the value is false - we will not return such offers. For example, you are looking for a ‘crankshaft’ in the ‘Groceries’ category. If the fallback mechanism is on, we will search the entire Allegro and display the results for the phrase “crankshaft” in other categories. However, if you turn off fallback, you will not get any results.

  • searchMode - specify where we will search for the phrase you entered:

    • REGULAR (default value) - only in the title,
    • DESCRIPTIONS - in the title and the descriptions,
    • CLOSED - in the title of closed offers.


Sample request::

  curl -X GET \
  'https://api.allegro.pl/offers/listing?category.id=77917&phrase=laptop&fallback=false&limit=1&searchMode=DESCRIPTIONS' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Click to view sample response:
{
    "items": {                                  -- list of offers.
        "promoted": [],                         --  promoted offers.
        "regular": [                            -- regular offers.
            {                       
                "id": "6685446754",             -- offer ID.
                "name": "Laptop Dell",          -- offer title.
                "seller": {             
                    "id": "44306431",           -- seller ID.
                    "login": "sellerLogin",     -- seller login.
                    "company": true,            -- whether the seller uses a company
                                                account.
                    "superSeller": false        -- whether the seller is a Super Seller.
                },
                "promotion": {                  -- promo options.
                    "emphasized": false,        -- featured offer.
                    "bold": false,              -- bold.
                    "highlight": false          -- highlighting.
                },
                "delivery": {
                    "availableForFree": false,  -- whether free shipping is available.
                    "lowestPrice": {            --  price of cheapest shipping method.
                        "amount": "8.99",
                        "currency": "PLN"
                    }
                },
                "images": [                     -- image paths, the first image in the
                                                array is also a thumbnail.
                   {
                    {
                        "url": "https://a.allegroimg.pl/original/11b105/0fdfeac9411596df365ec5cff395/Laptop-Dell"
                    }
                ],
                "sellingMode": {
                    "format": "BUY_NOW",        -- sales format; three values are supported:
                                                BUY_NOW (Buy it Now); AUCTION (auction);
                                                ADVERTISEMENT (classified ad)
                    "price": {                  -- item price displayed on a list of offers.
                                                In the case of BUY_NOW offers, it is the
                                                “buy now” price. In the case of
                                                AUCTION offers – current price.
                                                In the case of ADVERTISEMENT offers,
                                                it is the price of the advertisement.
                        "amount": "3675.00",            
                        "currency": "PLN"
                    },
                    "popularity": 1             -- offer popularity. In the case of
                                                BUY_NOW offers the number of
                                                transactions made by unique users
                                                within 30 days. In the case of AUCTION
                                                offers, it is the number of users
                                                placing bids.
                },
                "stock": {                      --  number of items available within the offer.
                    "unit": "UNIT",             -- three values are supported: UNIT,
                                                SET (sets), PAIR (pairs)
                    "available": 12             -- quantity of the available item.
                },
                "category": {
                    "id": "77917"               -- ID of a category that hosts the offer.
                }
            }
        ]
    },
    "searchMeta": {                             -- number of offers that meet the
                                                provided criteria.
        "availableCount": 1,                    -- number of offers that meet the
                                                provided criteria and are displayed.
                                                For example – the number of offers
                                                matching a particular request is 2,000,000,
                                                but we will display up to 6000.
                                                Therefore “6000” is the value
                                                of availableCount.
     "totalCount": 1,                           -- total number of offers that meet the
                                                requirements provided in the request.
                                                For example – the number of offers
                                                matching a particular request is
                                                2,000,000, but we will display up to 6000
                                                offers. Therefore “2,000,000” is the value
                                                of totalCount.
        "fallback": false                       --   information whether any offers
                                                matching the user criteria were found;
                                                two values are supported:
                                                true – no offers matching the user criteria
                                                were found and the search engine displayed
                                                similar offers; false – offers matching
                                                user criteria were found.
    },
    "categories": {                             -- categories where the offers were found.
        "subcategories": [
            {
                "id": "2",                     -- category ID.
                "name": "Komputery",           -- category name.
                "count": 1                     -- number of offers that were found in the
                                               particular category.
            }
        ],
        "path": [
            {
                "id": "954b95b6-43cf-4104-8354-dea4d9b10ddf",
                "name": "Allegro"
            }
        ]
    },
    "filters": [                              -- filters supported by the particular
                                              search.
        {
            "id": "parameter.11323",        
            "type": "MULTI",                  -- filter type; available values: MULTI,
                                              SINGLE, NUMERIC, NUMERIC_SINGLE, TEXT.
            "name": "Stan",
            "values": [
                {
                    "value": "11323_1",
                    "name": "nowe",
                    "count": 1,
                    "selected": false
                },
            ...
            ...
            ...
                {
                    "value": "11323_253806",
                    "name": "niewymagające renowacji",
                    "count": 0,
                    "selected": false
                }
            ]
        },
        {
            "id": "sellingMode.format",       -- sales format filter.
            "type": "MULTI",
            "name": "rodzaj oferty",
            "values": [
                {
                    "value": "BUY_NOW",
                    "name": "kup teraz",
                    "count": 0,
                    "selected": false
                },
                {
                    "value": "AUCTION",
                    "name": "licytacje",
                    "count": 0,
                    "selected": false
                },
                {
                    "value": "ADVERTISEMENT",
                    "name": "ogłoszenia",
                    "count": 0,
                    "selected": false
                }
            ]
        },
        {
            "id": "price",                    -- price filter.
            "type": "NUMERIC",
            "name": "cena",
            "values": [
                {
                    "idSuffix": ".from",
                    "name": "od",
                    "selected": false
                },
                {
                    "idSuffix": ".to",
                    "name": "do",
                    "selected": false
                }
            ],
            "minValue": 0,
            "maxValue": 1000000000,
            "unit": "zł"
        },
        {
            "id": "deliveryMethod",           -- filter of delivery methods
                                              available in offers.
            "type": "MULTI",
            "name": "sposoby dostawy",
            "values": [
                {
                    "value": "5b445fe6580ce26bb2f9960a",
                    "name": "Paczkomaty InPost",
                    "count": 1,
                    "selected": false
                },
               ...
               ...
               ...
                {
                    "value": "5b44605c580ce26bb2f99614",
                    "name": "Przesyłka elektroniczna",
                    "count": 0,
                    "selected": false
                }
            ]
        },
        {
            "id": "location.city",            -- location filter - shipping
                                              city.
            "type": "TEXT",
            "name": "miejscowość",
            "values": [
                {
                    "name": "miejscowość",
                    "selected": false
                }
            ]
        },
        {
            "id": "location.province",        -- location filter - shipping province.
            "type": "SINGLE",
            "name": "województwo",
            "values": [
                {
                    "value": "DOLNOSLASKIE",
                    "name": "z dolnośląskiego",
                    "selected": false
                },
                ...
                ...
                ...
                {
                    "value": "ZACHODNIOPOMORSKIE",
                    "name": "z zachodniopomorskiego",
                    "selected": false
                }
            ]
        },
        {
            "id": "option",                   -- filter of special offer options.
            "type": "MULTI",
            "name": "oferta ma",
            "values": [
                {
                    "value": "FREE_SHIPPING",
                    "name": "darmowa dostawa",
                    "selected": false
                },
                ...
                ...
                ...
                {
                    "value": "SMART",
                    "name": "Allegro Smart!",
                    "selected": false
                }
            ]
        },
        {
            "id": "campaign",                 -- campaign filter.
            "type": "MULTI",
            "name": "kampania",
            "values": [
                {
                    "value": "BARGAIN",
                    "name": "Strefa Okazji",
                    "selected": false
                },
                {
                    "value": "BARGAIN_REBATE",
                    "name": "rabaty",
                    "selected": false
                }
            ]
        }
    ],
    "sort": [                                 -- sorting types.
        {
            "value": "-relevance",
            "name": "trafność",
            "order": "największa",
            "selected": true
        },
        {
            "value": "+price",
            "name": "cena",
            "order": "od najniższej",
            "selected": false
        },
        {
            "value": "-price",
            "name": "cena",
            "order": "od najwyższej",
            "selected": false
        },
        {
            "value": "+withDeliveryPrice",
            "name": "cena z dostawą",
            "order": "od najniższej",
            "selected": false
        },
        {
            "value": "-withDeliveryPrice",
            "name": "cena z dostawą",
            "order": "od najwyższej",
            "selected": false
        },
        {
            "value": "-popularity",             
            "name": "popularność",
            "order": "największa",
            "selected": false
        },
        {
            "value": "+endTime",
            "name": "czas do końca",
            "order": "najmniej",
            "selected": false
        },
        {
            "value": "-startTime",
            "name": "czas dodania",
            "order": "najnowsze",
            "selected": false
        }
    ]
}

How to exclude specific response elements

Additionally, you can exclude specific response elements. To do this, use the include parameter and the prefix -. For example, if you want to receive in response only filters without offers: GET https://api.allegro.pl/offers/listing?phrase=telefon&searchMode=REGULAR&fallback=true&include=-all&include=filters


Sample request:

  curl -X GET \
  'https://api.allegro.pl/offers/listing?category.id=77917&include=-categories&include=-filters&include=-sort' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Click to view sample response:
{
    "items": {
        "promoted": [],
        "regular": [
            {
                "id": "6685446754",
                "name": "Laptop Dell",
                "seller": {
                    "id": "44306431",
                    "login": "sellerLogin",
                    "company": true,
                    "superSeller": false
                },
                "promotion": {
                    "emphasized": false,
                    "bold": false,
                    "highlight": false
                },
                "delivery": {
                    "availableForFree": false,
                    "lowestPrice": {
                        "amount": "8.99",
                        "currency": "PLN"
                    }
                },
                "images": [
                    {
                        "url": "https://a.allegroimg.pl/original/11b105/0fdfeac9411596df365ec5cff395/Laptop-Dell"
                    }
                ],
                "sellingMode": {
                    "format": "BUY_NOW",
                    "price": {
                        "amount": "3675.00",
                        "currency": "PLN"
                    },
                    "popularity": 1
                },
                "stock": {
                    "unit": "UNIT",
                    "available": 12
                },
                "category": {
                    "id": "77917"
                }
            }
        ]
    },
    "searchMeta": {
        "availableCount": 1,
        "totalCount": 1,
        "fallback": false
    }
}

2. How to filter search results


In response to your request on /offers/listing resource, in the “filters” section, you will receive all available filters in the given categories. The lower the category tree level, the more filters you can use. Based on them, you can build your request to precisely suit the query result to your needs. Each filter has a type. Currently, there are 5 of them:

  • MULTI - filter for multiple-choice parameters. You can use the same filter several times in a single request. We then treat them as connected by the OR operator - we will return all products that have at least one of the indicated values.

  • SINGLE - filter for single-choice selection parameters.

  • NUMERIC - filter for numeric parameters. You can create a filter by specifying the filter ID and a range of values by using “from” and “to” prefixes, according to formula: {filter.id}.from={value}&{filter.id}.to={value}.

  • NUMERIC_SINGLE - filter for range parameters. You can create the filter by using filter id and value according to the formula: {filter.id}={value}.

  • TEXT - filter for text parameters. You can enter any text.



You can specify many filters in the one query, we treat them as connected by the AND operator. In response, we will return offers that contain all the values ​you are searching for.



Sample request:

  curl -X GET \             
  ‘https://api.allegro.pl/offers/listing?category.id=165&phrase=Samsung&parameter.202865=202865_214113&parameter.202865=202865_214117&parameter.219=219_256’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Selling mode

Using the sellingMode.format filter you can get offers with a specific format:

  • sellingMode.format=BUY_NOW - buy now offers,

  • sellingMode.format=AUCTION - auctions,

  • sellingMode.format=ADVERTISEMENT - advertisements.



Sample request:

  curl -X GET \  
  'https://api.allegro.pl/offers/listing?phrase=sukienka+czerwona&sellingMode.format=BUY_NOW’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Parameters

You can filter the results by specific parameters of the item in the offers. You just need to use the parameter id and one of its values, e.g .:

  • parameter.11323=11323_1 to filter offers with the parameter “Stan”: “nowe” (“Condition”:”new”),

  • parameter.11323=11323_2 parameter.11323=11323_2 to filter offers with the parameter “Stan”: “używane” (“Condition”: ”used”).



Sample request:

  curl -X GET \
  'https://api.allegro.pl/offers/listing?category.id=78013&parameter.11323=11323_1’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Location

You can filter the results by location (the location is the city or province from which the seller declares shipping). Use the location parameter and provide the name of the city or province:

  • location.city=Poznań, allows you to filter offers from a specific city, in this case from Poznań,

  • location.province=WIELKOPOLSKIE, allows you to filter offers from a specific province, in this case from Wielkopolska.


Sample request:

  curl -X GET \ 'https://api.allegro.pl/offers/listing?category.id=78013&location.province=WIELKOPOLSKIE’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'


You can also search for offers with delivery from Poland or abroad. Just provide the value 1 (from Poland) or 0 (from abroad) in the shippingFromPoland parameter.


Sample request:

  curl -X GET \
  'https://api.allegro.pl/offers/listing?phrase=iPhone 8&shippingFromPoland=1’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Price

To filter results by price, use the parameter:

  • price.from - above the specified price,

  • price.to - below the specified price.



Sample request:

  curl -X GET \
  'https://api.allegro.pl/offers/listing?seller.id={Seller_ID}&price.from=10&price.to=1000&sort=+price’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Delivery methods

If you want to search for offers that have particular delivery methods, use the deliveryMethod filter, and use the id of the particular delivery method.


Sample request:

  curl -X GET \
  'https://api.allegro.pl/offers/listing?seller.id={Seller_ID}&deliveryMethod=5b445fe6580ce26bb2f9960a&deliveryMethod=5b446004580ce26bb2f9960c’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Badges

If you want to search for offers that have special badges, use the option parameter.

Currently available options are, for example:

  • FREE_SHIPPING - free delivery,
  • FREE_RETURN - free return,
  • VAT_INVOICE - VAT invoice,
  • COINS - Allegro Coins,
  • BRAND_ZONE - Brand Zone,
  • SUPERSELLER - Super Seller,
  • CHARITY - charity offer,
  • SMART - Allegro Smart!.



Sample request:

  curl -X GET \
  'https://api.allegro.pl/offers/listing?phrase=sukienka+czerwona&option=FREE_SHIPPING&option=SUPERSELLER’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Campaigns

Use the campaign parameter to filter offers that are included in promotional campaigns. Currently available campaigns are, for example:

  • INSTALLMENTS_ZERO - Zero installments,
  • BARGAIN - bargain.



Sample request:

  curl -X GET \
  'https://api.allegro.pl/offers/listing?seller.id={Seller_ID}&campaign=BARGAIN’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

3. How to sort the list of offers

You can define how the results are sorted. All you have to do is to provide the appropriate value in the sort parameter:

  • -relevance (default) - sort by relevance (high to low),

  • +price - sort by price (low to high),

  • -price - sort by price (high to low),

  • +withDeliveryPrice - sort by price with shipping (low to high),

  • -withDeliveryPrice - sort by shipping price (high to low),

  • -popularity - sort by popularity (high to low),

  • +endTime - sort by ending time (low to high),

  • -startTime - sort by starting time.

information

Note! You can only use one sorting method.



The prefix + or - indicates the sort direction:

  • ’+’ for ascending order,

  • ’-’ for descending order.



Sample request:

  curl -X GET \
  'https://api.allegro.pl/offers/listing?phrase=sukienka+czerwona&sort=+price’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

4. How to combine filtering and sorting methods

Use various combinations of filters, sorting methods, and the possibility of excluding response elements to precisely suit the query result to your needs. Pay attention to the type of filter - it tells you how you can use it and whether you can do it multiple times.


Here are some sample requests:

  1. Search for offers from a given seller and sort by relevance: https://api.allegro.pl/offers/listing?seller.id={Seller_ID}&sort=-relevance
  2. Search for offers of a given seller with prices in the range from 10 to 1000 PLN and sort by lowest prices: https://api.allegro.pl/offers/listing?seller.id={Seller_ID}&price.from=10&price.to=1000&sort=+price
  3. Search for offers in the “Desktop” category where “Graphics Chipset” (parameter.201793) is set to “GeForce RTX 2060” (201793_315098) and “Radeon RX 5700 XT” (201793_392581). Sort by lowest price: https://api.allegro.pl/offers/listing?category.id=486&parameter.201793=201793_315098&parameter.201793=201793_392581&sort=+price
  4. Search for offers in a specific category. Search for “telefon”. Use the search for related offers, if there are no results in the indicated category. In response, exclude all response elements, except for available filters: https://api.allegro.pl/offers/listing?category.id={Category_ID}&phrase=telefon&searchMode=REGULAR&fallback=true&include=-all&include=filters
  5. Search for offers with free Allegro Smart! delivery and from Super Seller: https://api.allegro.pl/offers/listing?phrase=iphone&option=SMART&option=SUPERSELLER

List of resources

You will find full documentation of resources in the swagger.yaml form file here.

List of basic resources used in tutorial: