03 lipca 2018
Od dziś w ramach Allegro REST API możecie wyszukiwać i przeglądać oferty.
Dla list ofert przygotowaliśmy nowy zasób w REST API Allegro:
- GET /offers/listing - chcę pobrać listę ofert według podanych parametrów
GET /offers/listing
Tym samym metodę doGetItemsList wygasimy na początku drugiego kwartału 2019 roku. We wrześniu 2018’ oznaczymy ją jako deprecated.
W pierwszej kolejności wywołaj metodę z jednym z podstawowych wyszukiwań.
Ważne! Oferty możesz wyszukać po różnych zmiennych, musisz wybrać co najmniej jedną:
- category.id - numer ID kategorii
- phrase - fraza
- seller.id - numer ID sprzedawcy
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/offers/listing?seller.id={Seller_ID}’
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'content-type: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}' \
W response otrzymasz wszystkie dostępne w danych kategoriach filtry i na ich podstawie możesz rozbudować swoje zapytanie. Poniżej kilka przykładów wywołań:
- 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, które pasują do frazy czerwona sukienka: https://api.allegro.pl/offers/listing?phrase=czerwona+sukienka
- wyszukaj oferty z danej kategorii: https://api.allegro.pl/offers/listing?category.id=78013
- Jeśli chcesz ograniczyć ilość wyników, wystarczy że ustawisz odpowiednią wartość w parametrze limit. Natomiast parametrem offset sterujesz, od której oferty chcesz otrzymasz wynik. Jeśli wybierzesz np. 120, to jako pierwszą ofertę otrzymasz tą, która jest 120 wynikiem. https://api.allegro.pl/offers/listing?phrase=telefon&searchMode=REGULAR&offset=180&limit=2
- Możesz również wykluczać określone elementy odpowiedzi. Jeśli chcesz w odpowiedzi otrzymać tylko filtry bez ofert wywołaj: https://api.allegro.pl/offers/listing?phrase=telefon&searchMode=REGULAR&fallback=true&include=-all&include=filters
- wyszukaj oferty które pasują do frazy czerwona sukienka w tytułach zakończonych ofert https://api.allegro.pl/offers/listing?phrase=czerwona+sukienka&searchMode=CLOSED
- wyszukaj oferty które pasują do frazy czerwona sukienka w tytułach trwających ofert https://api.allegro.pl/offers/listing?phrase=czerwona+sukienka&searchMode=REGULAR
- wyszukaj oferty które pasują do frazy czerwona sukienka w opisach trwających ofert https://api.allegro.pl/offers/listing?phrase=czerwona+sukienka&searchMode=DESCRIPTION
- Możesz również w swoim zapytaniu wyłączyć fallback, który domyślnie jest włączony: https://api.allegro.pl/offers/listing?phrase=telefon6567878&searchMode=REGULAR&fallback=false Wówczas - w sytuacji gdy na dane zapytanie nie mamy żadnych wyników - nie przekierujemy Cię na inne wyniki. Przykładowo: szukasz ‘wał korbowy’ w kategorii ‘produkty spożywcze’, jednak w tej kategorii nie otrzymałbyś ż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.
Przykładowy response:
{
"items": { -- lista ofert
"promoted": [], -- oferty promowane
"regular": [ -- oferty niepromowane
{
"id": "7288661202", -- numer identyfikacyjny oferty
"name": "Laptop DELL Latitude", -- tytuł oferty
"seller": {
"id": "23584147", -- numer identyfikacyjny sprzedawcy
"company": false, -- firma; dostępne są dwie wartości: true
(sprzedawca jest użytkownikiem konta firma),
false (sprzedawca jest użytkownikiem
konta zwykłego)
"superSeller": false -- Super Sprzedawca, dostępne są dwie wartości:
true (dla kont Super Sprzedawców),
false (dla pozostałych kont)
},
"promotion": { -- opcje promowania
"emphasized": false, -- oferta wyróżniona
"bold": false, -- pogrubienie
"highlight": false -- podświetlenie
},
"delivery": {
"availableForFree": false, -- darmowa wysyłka
"lowestPrice": { -- cena najniższej dostawy
"amount": "8.6",
"currency": "PLN"
}
},
"images": [ -- ścieżki obrazków, pierwsze zdjęcie
w tablicy jest jednocześnie pierwszym
zdjęciem w ofercie (miniaturką).
{
"url": "https://7.allegroimg.com/original/033d14/30782d8c40d399cea60d10f9b651"
},
{
"url": "https://3.allegroimg.com/original/03a30d/010af0a14704bf319b650bc2b261"
},
{
"url": "https://4.allegroimg.com/original/033735/9eaa9a5b49d2a9fcd5cf303e44a1"
}
],
"sellingMode": { -- format sprzedaży; obecnie dostępne są
trzy wartości: BUY_NOW (Kup Teraz); AUCTION
(licytacja); ADVERTISEMENT (ogłoszenie)
"format": "BUY_NOW",
"price": {
"amount": 12.12, -- cena za przedmiot, którą wyświetlamy na
liście ofert. W przypadku oferty typu BUY_NOW,
jest to cena oferty ‘kup teraz’. W przypadku
oferty typu AUCTION - aktualna cena osiągnięta
w licytacji. Dla oferty typu ADVERTISEMENT,
jest to cena z ogłoszenia.
"currency": "PLN"
},
"popularity": 0 -- popularność oferty. W przypadku oferty
typu BUY_NOW jest to liczba zakupów od
unikalnych użytkowników z ostatnich
30 dni. W przypadku oferty typu AUCTION
jest to liczba użytkowników,
którzy biorą udział w licytacji.
},
"stock": { -- ilość dostępnych przedmiotów w danej ofercie
"unit": "UNIT", -- obecnie dostępne są trzy wartości: UNIT
(sztuki); SET (komplety); PAIR (pary).
"available": 2 -- liczba aktualnie dostępnych przedmiotów
},
"category": {
"id": "99730" -- numer identyfikacyjny 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ą to 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, jakie
zdefiniował użytkownik
},
"categories": { -- kategorie, w jakich znajdują się
wyszukane oferty
"subcategories": [
{
"id": "5", -- numer identyfikacyjny kategorii
"name": "Dom i Ogród", -- nazwa kategorii
"count": 3 -- ilość ofert, znalezionych w danej kategorii
},
{
"id": "73973",
"name": "Delikatesy",
"count": 2
},
{
"id": "64477",
"name": "Biuro i Reklama",
"count": 3
}
],
"path": [
{
"id": "954b95b6-43cf-4104-8354-dea4d9b10ddf",
"name": "Allegro"
}
]
},
"filters": [ -- filtry dostępne dla danego wyszukiwania
{
"id": "parameter.11323",
"type": "MULTI", -- typ filtru; obecnie dostępne są wartości:
MULTI - filtr wielokrotnego wyboru, SINGLE
- filtr pojedynczego wyboru, NUMERIC - zakres
wartości numerycznych (wyszukanie ofert,
dla których wartość parametru mieści się w
zakresie określonym przez ten filtr),
NUMERIC_SINGLE - wartość pojedyncza
(wyszukanie ofert, dla których zdefiniowany
zakres wartości parametru obejmuje wartość
podaną w filtrze), TEXT - filtr pozwalający
użytkownikowi wprowadzić dowolny teks
"name": "Stan",
"values": [
{
"value": "1",
"name": "nowe",
"count": 167811,
"selected": false
},
{
"value": "2",
"name": "używane",
"count": 19264,
"selected": false
},
{
"value": "246510",
"name": "nowe bez metki",
"count": 2443,
"selected": false
},
{
"value": "246514",
"name": "nowe z defektem",
"count": 471,
"selected": false
}
]
},
{
"id": "price", -- cena dla oferty
"type": "NUMERIC", -- dana numeryczna
"name": "cena (zł)",
"values": [
{
"idSuffix": ".from", -- cena od
"name": "od",
"selected": false
},
{
"idSuffix": ".to", -- cena do
"name": "do",
"selected": false
}
],
"minValue": 0, -- minimalna wartość
"maxValue": 1000000000 -- maksymalna wartość
}
],
"sort": [ -- rodzaje sortowań
{
"value": "-relevance", -- sortowanie po trafności od największej,
przykładowe wywołanie:
https://api.allegro.pl/offers/listing?
seller.id={Seller_ID}&sort=-relevance
"name": "trafność", -- sortowanie po trafności
"order": "największa", -- kierunek sortowania
"selected": true -- czy zastosowano dane sortowanie
},
{
"value": "+price", -- sortowanie od najniższej ceny oferty
"name": "cena",
"order": "od najniższej",
"selected": false
},
{
"value": "-price", -- sortowanie od najwyższej ceny oferty
"name": "cena",
"order": "od najwyższej",
"selected": false
},
{
"value": "+withDeliveryPrice", -- sortowanie od najniższej ceny z dostawą
"name": "cena z dostawą",
"order": "od najniższej",
"selected": false
},
{
"value": "-withDeliveryPrice", -- sortowanie od najwyższej ceny z dostaw
"name": "cena z dostawą",
"order": "od najwyższej",
"selected": false
},
{
"value": "-popularity",
"name": "popularność",
"order": "największa", -- kierunek sortowania (rosnące czy malejące)
"selected": false
},
{
"value": "+endTime",
"name": "czas do końca",
"order": "najmniej",
"selected": false
},
{
"value": "-startTime",
"name": "czas dodania",
"order": "najnowsze",
"selected": false
}
]
}
