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},
- marketplaceId - pobierz oferty widoczne na wskazanym rynku, domyślnie przeszukujemy allegro-pl,
- shipping.country - kraj dostawy, wartość domyślna jest zależna od przeszukiwanego rynku,
- currency - waluta ceny oferty, wartość domyślna zależy od przeszukiwanego rynku.
Dostępne rynki, kraje dostawy oraz waluty dla poszczególnych rynków sprawdzisz za pomocą GET /marketplaces.
Powyższe parametry możesz łączyć w pojedynczym żądaniu: GET https://api.allegro.pl/offers/listing?phrase={value}&seller.id={value}&category.id={value}&marketplaceId={value}&shipping.country={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 (dostępne tylko dla marketplace=allegro-pl).
Wyniki zwrócimy zgodnie z przekazanym w requeście nagłówkiem Accept-Language - domyślna wartość zależeć będzie od wartości przekazanej w parametrze marketplaceId. Jeżeli nie przekażesz żadnej wartości w parametrze marketplaceId - domyślnie zwrócimy wynik dla allegro.pl w języku polskim. Jeżeli w Accept-Language przekażesz wartość nieobsługiwaną na danym rynku - zwrócimy listę w języku domyślnym dla danego marketplace. Listę obsługiwanych języków w poszczególnych marketplace poznasz dzięki GET /marketplaces.
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'{
"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'{
"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
}
}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¶meter.202865=202865_214113¶meter.202865=202865_214117¶meter.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¶meter.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}'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.
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}'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ń:
- 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
- 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
- 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¶meter.201793=201793_315098¶meter.201793=201793_392581&sort=+price
- 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
- 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:
- GET /offers/listing - wyszukaj oferty
