1. Jak wyszukiwać i przeglądać oferty


information Dostęp do GET /offers/listing mają tylko zweryfikowane aplikacje.

Jak zweryfikować aplikację?

Jeśli jesteś w Programie Partnerskim skontaktuj się ze swoim opiekunem. W innym wypadku skontaktuj się z nami przez formularz.


W ramach Allegro REST API możesz wyszukiwać i przeglądać oferty dostępne na Allegro. Za pomocą GET /offers/listing pobierzesz taką listę ofert.


GET /offers/listing jest zasobem, który pozwala na dostęp do danych publicznych, dlatego do autoryzacji możesz wykorzystać client_credentials flow.

Wynik wyszukiwania zależy od parametrów, które przekażesz w żądaniu. Aby wyszukiwanie się powiodło, skorzystaj z co najmniej jednego z poniższych parametrów:

  • phrase - fraza, którą chcesz użyć podczas wyszukiwania.

  • category.id - numer ID kategorii, w której chcesz wyszukiwać oferty.

  • seller.id - numer ID sprzedawcy, którego oferty chcesz wyszukać. Możesz podać ID wielu sprzedawców, na zasadzie {seller.id}={value}&seller.id={value}.

  • seller.login - login sprzedawcy, którego oferty chcesz wyszukać. Możesz podać loginy wielu sprzedawców, na zasadzie {seller.login}={name}&seller.login={name}.

information Ważne! Możesz użyć tylko jednego parametru spośród {seller.id} i {seller.login} w danym żądaniu.


Powyższe parametry możesz łączyć w pojedynczym żądaniu: GET https://api.allegro.pl/offers/listing?phrase={value}&seller.id={value}&category.id={value}

Listę ofert możesz dostosować do twoich potrzeb. Użyj w tym celu parametrów:

  • limit - określ liczbę ofert, jaką zwrócimy w odpowiedzi (przyjmuje wartości od 1-60, wartość domyślna to 60).

  • offset - wskaż miejsce, od którego chcesz pobrać kolejną porcję danych. Maksymalna wartość wynosi 600 (odejmij od tej wartości wcześniej ustalony limit).

  • fallback - zdefiniuj, w jak ma zachować się wyszukiwarka, jeśli nie znajdziemy żadnych wyników dla przekazanej frazy. Domyślnie włączona jest wartość true. Oznacza to, że jeśli nie znajdziemy wyników we wskazanej kategorii, przeszukamy także inne i w odpowiedzi zwrócimy powiązane oferty. Dla wartości false - nie zwrócimy takich ofert. Przykładowo: szukasz ‘wał korbowy’ w kategorii ‘produkty spożywcze’, jednak w tej kategorii nie zwróciliśmy żadnych wyników. Gdy działa mechanizm fallback, przeszukamy całe Allegro i wyświetlimy wyniki dla frazy ‘wał korbowy’ w innych kategoriach. Gdy wyłączysz fallback, nie otrzymasz żadnych wyników.

  • searchMode - określ, gdzie mamy wyszukiwać wprowadzoną przez ciebie frazę:

    • REGULAR (wartość domyślna) - w tytule,
    • DESCRIPTIONS - w tytule i opisach,
    • CLOSED - w tytule ofert zamkniętych.


Przykładowy 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'

Kliknij, żeby zobaczyć przykładowy response:
{
    "items": {                                  – lista ofert.
        "promoted": [],                         – lista ofert promowanych.
        "regular": [                            – lista ofert niepromowanych.
            {
"id": "6685446754", – numer oferty. "name": "Laptop Dell", – tytuł oferty. "seller": {
"id": "44306431", – id sprzedawcy. "login": "sellerLogin", – login sprzedawcy. "company": true, – czy sprzedawca korzysta z konta firma "superSeller": false – czy sprzedawca jest Super Sprzedawcą. }, "promotion": { – opcje promowania. "emphasized": false, – oferta wyróżniona. "bold": false, – pogrubienie. "highlight": false – podświetlenie. }, "delivery": { "availableForFree": false, – czy w ofercie jest dostępna darmowa dostawa. "lowestPrice": { – cena najtańszej dostawy. "amount": "8.99", "currency": "PLN" } }, "images": [ – ścieżki zdjęć, pierwsze zdjęcie w tablicy jest jednocześnie pierwszym zdjęciem w ofercie (miniaturką). { { "url": "https://a.allegroimg.pl/original/11b105/0fdfeac9411596df365ec5cff395/Laptop-Dell" } ], "sellingMode": { "format": "BUY_NOW", – format sprzedaży; obecnie dostępne są trzy wartości: BUY_NOW(Kup Teraz); AUCTION (licytacja); ADVERTISEMENT (ogłoszenie). "price": { – cena za przedmiot, którą wyświetlamy na liście ofert. W przypadku formatu BUY_NOW, jest to cena oferty ‘kup teraz’. Dla oferty w formacie AUCTION - aktualna cena osiągnięta w licytacji. Dla ofert typu ADVERTISEMENT, jest to cena z ogłoszenia. "amount": "3675.00",
"currency": "PLN" }, "popularity": 1, – dolna wartość zakresu "popularityRange". "popularityRange": "[1-5]" – zakres popularności. Możliwe wartości: 0, [1-5], [6-10], [11-20], [21-50], [51-100], [101+]. W przypadku ofert formatu BUY_NOW zakres dotyczy liczby zakupów od unikalnych użytkowników z ostatnich 30 dni. W przypadku ofert formatu AUCTION liczby użytkowników, którzy biorą udział w licytacji. }, "stock": { – liczba dostępnych przedmiotów. "unit": "UNIT", – dostępne są 3 wartości: UNIT (sztuki), SET (komplety) oraz PAIR (pary). "available": 12 – liczba aktualnie dostępnych sztuk. }, "category": { "id": "77917" – numer id kategorii, w której znajduje się oferta. } } ] }, "searchMeta": { – liczba ofert, które spełniają warunki określone w zapytaniu. "availableCount": 1, – liczba ofert, które spełniają warunki określone w zapytaniu i które wyświetlamy w serwisie. Przykładowo: dla danego zapytania liczba ofert jakie je spełniają to 2 000 000, ale na listach ofert w serwisie wyświetlamy maksymalnie 6000. Liczba 6000 to availableCount. "totalCount": 1, – całkowita liczba ofert, które spełniają warunki określone w zapytaniu. Przykładowo: dla danego zapytania liczba ofert, jakie je spełniają wynosi 2 000 000, ale na listach ofert w serwisie wyświetlamy maksymalnie 6000. Liczba 2 000 000 to totalCount. "fallback": false – informacja o tym, czy znaleziono oferty które spełniają kryteria, jakie zdefiniował użytkownik. Dostępne są dwie wartości: true: - nie znaleziono ofert które spełniają kryteria jakie zdefiniował użytkownik i wyszukiwarka dostarczyła zbliżone oferty; false - znaleziono oferty dokładnie spełniające kryteria wyszukiwania. }, "categories": { – kategorie, w jakich znajdują się wyszukane oferty. "subcategories": [ { "id": "2", – numer id kategorii. "name": "Komputery", – nazwa kategorii. "count": 1 – ilość ofert, znalezionych w danej kategorii. } ], "path": [ { "id": "954b95b6-43cf-4104-8354-dea4d9b10ddf", "name": "Allegro" } ] }, "filters": [ – filtry dostępne dla danego wyszukiwania. { "id": "parameter.11323",
"type": "MULTI", – typ filtra; dostępne są następujące wartości: 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", – filtr formatu sprzedaży. "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", – filtr ceny. "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", – filtr dostępnych w ofertach metod dostawy. "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", – filtr lokalizacji - miejscowość wysyłki. "type": "TEXT", "name": "miejscowość", "values": [ { "name": "miejscowość", "selected": false } ] }, { "id": "location.province", – filtr lokalizacji - województwo wysyłki. "type": "SINGLE", "name": "województwo", "values": [ { "value": "DOLNOSLASKIE", "name": "z dolnośląskiego", "selected": false }, … … … { "value": "ZACHODNIOPOMORSKIE", "name": "z zachodniopomorskiego", "selected": false } ] }, { "id": "option", – filtr specjalnych oznaczeń oferty. "type": "MULTI", "name": "oferta ma", "values": [ { "value": "FREE_SHIPPING", "name": "darmowa dostawa", "selected": false }, … … … { "value": "SMART", "name": "Allegro Smart!", "selected": false } ] }, { "id": "campaign", – filtr kampanii. "type": "MULTI", "name": "kampania", "values": [ { "value": "BARGAIN", "name": "Strefa Okazji", "selected": false }, { "value": "BARGAIN_REBATE", "name": "rabaty", "selected": false } ] } ], "sort": [ – rodzaje sortowania. { "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": "+endTime", "name": "czas do końca", "order": "najmniej", "selected": false }, { "value": "-startTime", "name": "czas dodania", "order": "najnowsze", "selected": false } ] }

Jak wykluczać określone elementy odpowiedzi

Dodatkowo możesz wykluczać określone elementy odpowiedzi. Wykorzystaj w tym celu parametr include i przedrostek -. Na przykład, jeśli chcesz w odpowiedzi otrzymać tylko filtry bez ofert wywołaj: GET https://api.allegro.pl/offers/listing?phrase=telefon&searchMode=REGULAR&fallback=true&include=-all&include=filters


Przykładowy 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'

Kliknij, żeby zobaczyć przykładowy 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,
                    "popularityRange": "[1-5]"
                },
                "stock": {
                    "unit": "UNIT",
                    "available": 12
                },
                "category": {
                    "id": "77917"
                }
            }
        ]
    },
    "searchMeta": {
        "availableCount": 1,
        "totalCount": 1,
        "fallback": false
    }
}

2. Jak filtrować wyniki wyszukiwania


W odpowiedzi na żądanie które wykonasz na zasobie /offers/listing, w sekcji “filters” otrzymasz wszystkie dostępne filtry w danych kategoriach. Im niższy poziom drzewa kategorii, tym więcej filtrów możesz użyć. Na ich podstawie możesz rozbudować swoje żądanie, aby precyzyjnie dostosować wynik zapytania do swoich potrzeb. Każdy filtr ma zdefiniowany typ. Obecnie dostępnych jest 5 typów:

  • MULTI - filtr dla parametrów pojedynczego wyboru. W pojedynczym żądaniu możesz kilkukrotnie skorzystać z tego samego filtra. Traktujemy je wtedy jako połączone operatorem OR - czyli zwracamy wszystkie produkty, które mają choć jedną ze wskazanych wartości.

  • SINGLE - filtr dla parametrów pojedynczego wyboru.

  • NUMERIC - filtr dla parametrów liczbowych. Filtr tworzysz podając identyfikator filtra i zakres wartości w przyrostkach from i to, dla których chcesz otrzymać wyniki wyszukiwania, na zasadzie {filter.id}.from={value}&{filter.id}.to={value}.

  • NUMERIC_SINGLE - filtr dla parametrów zakresowych. Filtr tworzysz podając identyfikator filtra i szukaną wartość, na zasadzie {filter.id}={value}.

  • TEXT - filtr dla parametrów tekstowych. Możesz wprowadzić dowolny tekst.



W zapytaniu możesz podać wiele filtrów, traktujemy je jako połączone operatorem AND. W odpowiedzi zwrócimy oferty, które zawierają wszystkie wartości wskazane dla podanych filtrów.



Przykładowy 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}'

Format sprzedaży

Za pomocą filtra sellingMode.format pobierzesz oferty konkretnego formatu:

  • sellingMode.format=BUY_NOW - oferty Kup Teraz,

  • sellingMode.format=AUCTION - licytacje,

  • sellingMode.format=ADVERTISEMENT - ogłoszenia.



Przykładowy 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}'

Parametry

Możesz filtrować wyniki po konkretnych parametrach przedmiotu w ofercie. Wystarczy, że w zapytaniu przekażesz id parametru oraz podasz jego wartość, np.:

  • parameter.11323=11323_1 aby filtrować oferty z parametrem “Stan”: “nowe”,

  • parameter.11323=11323_2 aby filtrować oferty z parametrem “Stan”: “używane”.



Przykładowy 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}'

Lokalizacja

Możesz filtrować wyniki po lokalizacji (lokalizacja to miasto, bądź województwo, z którego sprzedający deklaruje wysyłkę przedmiotu). Skorzystaj z parametru location i przekaż nazwę miasta lub województwa:

  • location.city=Poznań, pozwala filtrować oferty z konkretnego miasta, w tym przypadku z Poznania,

  • location.province=WIELKOPOLSKIE, pozwala filtrować oferty z konkretnego województwa, w tym wypadku z Wielkopolski.


Przykładowy 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}'


Możesz także wyszukać oferty z dostawą z Polski lub zagranicy. Wystarczy, że w parametrze shippingFromPoland przekażesz wartość 1 (z Polski) lub 0 (z zagranicy).


Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/offers/listing?phrase=słuchawki&category.id=85166&shippingFromPoland=1'
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Cena

Aby filtrować wyniki po cenie, skorzystaj z parametru:

  • price.from - od ustalonej ceny wzwyż,

  • price.to - do ustalonej ceny.



Przykładowy 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}'

Metoda dostawy

Jeśli chcesz wyszukać oferty, które posiadają konkretne metody dostawy, skorzystaj z filtra deliveryMethod oraz wskaż identyfikatory konkretnych metod dostawy.


Przykładowy 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}'

Oznaczenia

Jeżeli chcesz wyszukać oferty, które posiadają specjalne oznaczenia, skorzystaj z parametru option.

Aktualnie dostępne oznaczenia to m.in.:

  • FREE_SHIPPING - darmowa dostawa,
  • FREE_RETURN - darmowy zwrot,
  • VAT_INVOICE - faktura VAT,
  • COINS - Monety Allegro,
  • BRAND_ZONE - Strefa Marek,
  • SUPERSELLER - Super Sprzedawca,
  • CHARITY - oferta charytatywna,
  • SMART - Allegro Smart!.



Przykładowy 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}'

Kampanie

Skorzystaj z parametru campaign, aby filtrować oferty, które biorą udział w kampaniach promocyjnych. Dostępne oznaczenia to m.in.:

  • INSTALLMENTS_ZERO - Raty Zero,
  • BARGAIN - Strefa Okazji.



Przykładowy 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. Jak sortować listę ofert

Możesz określić sposób sortowania wyników. Wystarczy, że w parametrze sort przekażesz odpowiednią wartość:

  • -relevance(domyślne) - sortowanie po trafności,

  • +price - sortowanie od najniższej ceny oferty,

  • -price - sortowanie od najwyższej ceny oferty,

  • +withDeliveryPrice - sortowanie od najniższej ceny z dostawą,

  • -withDeliveryPrice - sortowanie od najwyższej ceny z dostaw,

  • +endTime - czas do końca,

  • -startTime - czas dodania.

information Ważne! Możesz użyć tylko jednego sposobu sortowania.



Przedrostek + lub - oznacza kierunek sortowania:

  • ’+’ to kolejność rosnąca,

  • ’-’ to kolejność malejąca.



Przykładowy 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. Jak łączyć sposoby filtrowania i sortowania

Wykorzystaj różne kombinacje filtrów, sposobu sortowania, czy możliwości wykluczania elementów odpowiedzi, aby precyzyjnie dostosować wynik zapytania do twoich potrzeb. Zwróć uwagę na typ filtra - to po nim poznasz, jak możesz go wykorzystać i czy możesz to zrobić wielokrotnie.


Oto kilka przykładowych żądań:

  1. Wyszukaj oferty danego sprzedawcy i posortuj je po trafności (od największej): https://api.allegro.pl/offers/listing?seller.id={Seller_ID}&sort=-relevance
  2. Wyszukaj oferty danego sprzedawcy w których cena mieści się w przedziale od 10 do 1000 PLN i posortuj je od najniższej cen: https://api.allegro.pl/offers/listing?seller.id={Seller_ID}&price.from=10&price.to=1000&sort=+price
  3. Wyszukaj oferty w kategorii “Komputer stacjonarny”, w których parametr “Chipset karty graficznej” (parameter.201793) ma wartość “GeForce RTX 2060” (201793_315098) i “Radeon RX 5700 XT” (201793_392581). Posortuj od najniższej ceny: https://api.allegro.pl/offers/listing?category.id=486&parameter.201793=201793_315098&parameter.201793=201793_392581&sort=+price
  4. Wyszukaj oferty w konkretnej kategorii. Fraza, która ma znaleźć się w tytule to “telefon”. Skorzystaj z wyszukiwania ofert powiązanych, jeżeli we wskazanej kategorii nie będzie wyników. W odpowiedzi wyklucz wszystkie elementy odpowiedzi prócz dostępnych filtrów: https://api.allegro.pl/offers/listing?category.id={Category_ID}&phrase=telefon&searchMode=REGULAR&fallback=true&include=-all&include=filters
  5. Wyszukaj oferty z darmową dostawą Allegro Smart! oraz od Super Sprzedawcy: https://api.allegro.pl/offers/listing?phrase=iphone&option=SMART&option=SUPERSELLER

Lista zasobów

Pełną dokumentację zasobów w postaci pliku swagger.yaml znajdziesz tu.

Lista zasobów podstawowych opisanych w poradniku: