Dokumentacja Auction API

Przegląd

Auction API obejmuje informacje o ogłoszeniach pojazdów, które są obecnie dostępne przez włączone źródła danych. Dane zawierają specyfikacje pojazdu, ceny, dane sprzedawcy, lokalizację, zdjęcia, URL-e ogłoszeń oraz pola aukcyjne, gdy są dostępne.

Twój API key jest wydawany osobno i musi być wysyłany jako parametr GET api_key na każdym endpoint.

Pokrycie

Aktywne ogłoszenia pojazdów dostępne w ramach subskrypcji i ograniczone włączonymi źródłami danych.

Dostarczanie

Dane są dostarczane przez zapytania Elasticsearch scroll, zoptymalizowane do wsadowego przetwarzania dużych zbiorów danych.

Synchronizacja

Endpoint stream zwraca tylko aktualnie aktywne, niearchiwalne pojazdy.

Kontrola dostępu

Każdy request jest weryfikowany przez API key, aktywną subskrypcję, włączone źródła danych i IP whitelist, jeśli jest włączony.

Request HTTP

Endpoint

requestGET

stream cars

GEThttps://api.auctionsapi.com/cars?api_key=YOUR_API_KEY

Przykład — Laravel / HTTP Client

Target:

Client:

SyncCars.php

1use Illuminate\Support\Facades\Http;2 3$response = Http::acceptJson()4    ->timeout(60)5    ->get('https://api.auctionsapi.com/cars', [6        'api_key' => 'YOUR_API_KEY',7    ]);8 9return $response->json();

Endpointy API

GET/carsKrok 1

Start synchronizacji

Rozpocznij synchronizację

api_keylimitscroll_time

https://api.auctionsapi.com/cars?api_key=YOUR_API_KEY&limit=1000&scroll_time=10

GET/carsKrok 2

Kontynuacja

Kontynuuj synchronizację

api_keyscroll_id

https://api.auctionsapi.com/cars?api_key=YOUR_API_KEY&scroll_id=SCROLL_ID

GET/search

Wyszukiwanie

Wyszukiwanie po słowie kluczowym

api_keyquerypageperPagesort

https://api.auctionsapi.com/search?api_key=YOUR_API_KEY&query=toyota&page=1&perPage=20&sort=newest

GET/search

Wyszukiwanie

Wyszukiwanie z filtrami

priceyearenumsbrands

https://api.auctionsapi.com/search?api_key=YOUR_API_KEY&price_from=5000&price_to=15000&currency_id=1&year_from=2015&year_to=2020&body_types[]=5&fuels[]=1&colors[]=13&transmission=1&drive_wheels[]=3&brands[0][id]=10&brands[0][models][]=101

GET/brands

Referencja

Marki

api_key

https://api.auctionsapi.com/brands?api_key=YOUR_API_KEY

GET/models/{brand_id}

Referencja

Modele

brand_idapi_key

https://api.auctionsapi.com/models/58?api_key=YOUR_API_KEY

Workflow paginacji

Zacznij od /cars bez scroll_id.
Odpowiedź zawiera scroll_id i next_url.
Jeśli next_url nie jest pusty, żądaj go dalej, aż stanie się pusty albo API nie zwróci więcej danych.
Jeśli pojazd nie został zwrócony w ciągu ostatnich 24 godzin, oznacz go jako zarchiwizowany albo usuń z bazy.

Parametry GET

Parametr	Endpoint	Typ	Domyślnie / limity	Opis
`api_key`	`Wszystkie endpoints`	`string`	Domyślnie: -	Twój unikalny API key. Musi być przekazany jako parametr GET.
`scroll_time`	`/cars`	`int`	Domyślnie: 10 Limity: Maks.: 15 minut	Czas trwania sesji scroll.
`limit`	`/cars`	`int`	Domyślnie: 1000 Limity: Maks.: 2000	Liczba aut w jednym pakiecie.
`scroll_id`	`/cars`	`string`	Domyślnie: -	Użyj tego, aby pobrać kolejny pakiet danych.
`page`	`/search`	`int`	Domyślnie: 1 Limity: Min.: 1	Numer strony.
`perPage`	`/search`	`int`	Domyślnie: 50 Limity: Min.: 2, Maks.: 50	Elementów na stronę.
`sort`	`/search`	`string`	Domyślnie: newest Limity: Zobacz opcje sortowania	Kolejność sortowania.
`query`	`/search`	`string`	Domyślnie: - Limity: Maks. długość: 200	Pełnotekstowe zapytanie wyszukiwania.
`price_from`	`/search`	`int`	Domyślnie: - Limity: Min.: 0	Cena minimalna, włącznie.
`price_to`	`/search`	`int`	Domyślnie: - Limity: Min.: 1	Cena maksymalna, włącznie.
`currency_id`	`/search`	`int`	Domyślnie: - Limity: Min.: 1	Waluta do filtrowania ceny. Ignorowana, jeśli zakres ceny nie jest podany.
`year_from`	`/search`	`int`	Domyślnie: - Limity: Min.: 1800, Maks.: 3000	Rok modelowy od, włącznie.
`year_to`	`/search`	`int`	Domyślnie: - Limity: Min.: 1800, Maks.: 3000	Rok modelowy do, włącznie.
`odometer_from`	`/search`	`int`	Domyślnie: - Limity: Min.: 0, Maks.: 999999999	Przebieg od, włącznie.
`odometer_to`	`/search`	`int`	Domyślnie: - Limity: Min.: 0, Maks.: 999999999	Przebieg do, włącznie.
`engine_volume_from`	`/search`	`int`	Domyślnie: - Limity: Min.: 0, Maks.: 999999999	Pojemność silnika od, włącznie.
`engine_volume_to`	`/search`	`int`	Domyślnie: - Limity: Min.: 0, Maks.: 999999999	Pojemność silnika do, włącznie.
`power_hp_from`	`/search`	`int`	Domyślnie: - Limity: Min.: 0, Maks.: 100000	Moc od, włącznie.
`power_hp_to`	`/search`	`int`	Domyślnie: - Limity: Min.: 1, Maks.: 100000	Moc do, włącznie.
`brands`	`/search`	`array<object>`	Domyślnie: - Limity: id, optional models[]	Filtr marki. Jeśli modele są pominięte, pasuje dowolny model w wybranej marce.
`body_types`	`/search`	`int[]`	Domyślnie: - Limity: Zobacz enum	ID typów nadwozia.
`colors`	`/search`	`int[]`	Domyślnie: - Limity: Zobacz enum	ID kolorów.
`fuels`	`/search`	`int[]`	Domyślnie: - Limity: Zobacz enum	ID paliw.
`seller_type`	`/search`	`int`	Domyślnie: - Limity: Zobacz enum	ID typu sprzedawcy.
`steering_wheel_position`	`/search`	`int`	Domyślnie: - Limity: Zobacz enum	ID pozycji kierownicy.
`transmission`	`/search`	`int`	Domyślnie: - Limity: Zobacz enum	ID skrzyni biegów.
`airbags`	`/search`	`int`	Domyślnie: - Limity: Zobacz enum	ID stanu poduszek.
`damages`	`/search`	`int[]`	Domyślnie: - Limity: Zobacz enum	ID uszkodzeń.
`conditions`	`/search`	`int[]`	Domyślnie: - Limity: Zobacz enum	ID stanów.
`availabilities`	`/search`	`int[]`	Domyślnie: - Limity: Zobacz enum	ID dostępności.
`emissions`	`/search`	`int[]`	Domyślnie: - Limity: Zobacz enum	ID standardów emisji.
`drive_wheels`	`/search`	`int[]`	Domyślnie: - Limity: Zobacz enum	ID napędu.
`keys_available`	`/search`	`boolean`	Domyślnie: - Limity: true/false albo 1/0	Filtr według dostępności kluczy.
`brand_id`	`/models/{brand_id}`	`int`	Domyślnie: - Limity: Path parameter	Brand ID używany do zwrócenia modeli konkretnej marki.

Opcje sortowania

Wartość	Opis
`newest`	Najpierw najnowsze ogłoszenia.
`oldest`	Najpierw najstarsze ogłoszenia.
`cheaper`	Najpierw najniższa cena.
`expensive`	Najpierw najwyższa cena.
`odometer_asc`	Najpierw najniższy przebieg.
`odometer_desc`	Najpierw najwyższy przebieg.
`year_asc`	Najpierw najstarszy rok modelowy.
`year_desc`	Najpierw najnowszy rok modelowy.
`auction_nearest`	Najpierw najbliższa data aukcji.

Tablice i parametry zagnieżdżone

Proste tablicecolors[]=13&colors[]=15&fuels[]=1&fuels[]=4

Marki i modelebrands[0][id]=10&brands[0][models][]=101&brands[0][models][]=102&brands[1][id]=12

Jeśli modele są pominięte, filtr pasuje do dowolnego modelu w wybranej marce. Dla paginacji wyszukiwania page * perPage musi być mniejsze lub równe 10000.

Wartości enum

Użyj numeric ID w query parameters. Na przykład colors[]=13 oznacza biały, a transmission=1 oznacza automatyczną skrzynię.

Typy nadwozia

body_types

1Sedan2Kombi3Coupe4Pickup5SUV6Kabriolet7Van11Hatchback12Roadster13Limuzyna20Liftback22Karawan27Auto sportowe

Kolory

colors

1Srebrny2Fioletowy3Pomarańczowy4Zielony5Czerwony6Złoty8Brązowy9Szary10Turkusowy11Niebieski12Brązowy metalik13Biały14Kremowy15Czarny16Żółty17Beżowy18Różowy100Dwa kolory

Paliwa

fuels

1Diesel2Elektryczny3Hybrydowy4Benzyna5Gaz6Flexible7Wodór8Etanol

Typ sprzedawcy

seller_type

1Osoba prywatna2Dealer

Pozycja kierownicy

steering_wheel_position

1Lewa2Prawa

Skrzynia biegów

transmission

1Automatyczna2Manualna

Poduszki powietrzne

airbags

1Nienaruszone2Wystrzelone3Brak

Uszkodzenia

damages

1Bok2Kradzież3Pożar4Elektryczny5Wandalizm6Woda7Dach8Transmission9Zawieszenie10Biohazard11Program złomowania12Przejęcie13Dachowanie14Całe auto15Silnik16Rama17Przód18Tył19Przód i tył20Grad21Mechaniczne22Drobne wgniecenia/rysy23VIN24Normalne zużycie25Odrzucona lub częściowa naprawa26Burza27Rozebrany28Podwozie

Stany

conditions

1Używany2Nowy3Uszkodzony

Dostępność

availabilities

1Na stanie2W transporcie3Na zamówienie

Emisje

emissions

1Euro 12Euro 23Euro 34Euro 45Euro 56Euro 67Zev

Napęd

drive_wheels

1Tył2Przód3Pełny

Odpowiedź JSON

Odpowiedź zawiera znormalizowane informacje o pojeździe, dane ogłoszenia, zdjęcia, cenę, lokalizację, typ sprzedawcy, stan, pola aukcyjne i dane paginacji do kontynuacji streamu.

Pola odpowiedzi

Parametr	Opis
`data`	Tablica znormalizowanych rekordów pojazdów dostępnych w subskrypcji albo pusta tablica, gdy nie ma więcej danych w streamie.
`id`	Wewnętrzny identyfikator pojazdu AuctionsAPI.
`brand / model`	Znormalizowane obiekty marki i modelu z ID oraz nazwami.
`engine_volume`	Pojemność silnika, gdy jest dostępna.
`body_type / transmission / fuel / color`	Znormalizowane obiekty enum z ID i nazwą.
`listings`	Rekordy ogłoszeń źródła z URL-em ogłoszenia, tytułem, ceną, typem sprzedawcy, zdjęciami, datami i statusem.
`external`	Oryginalny identyfikator ogłoszenia, placeholder domeny źródła i URL ogłoszenia.
`price`	Cena ogłoszenia, waluta, flaga negocjacji i opcjonalna historia ceny.
`location`	Metadane lokalizacji ogłoszenia i współrzędne, gdy są dostępne.
`condition / damage / auction fields`	Stan, data aukcji, oferta, klucze, uszkodzenia, stan poduszek i pola dokumentów, gdy są dostępne.
`scroll_id`	Token paginacji zwracany przez stream endpoint, gdy dostępne są kolejne pakiety.
`next_url`	Gotowy URL dla kolejnego pakietu. Zatrzymaj się, gdy jest pusty albo nie ma więcej danych.
`hash`	Stabilny hash znormalizowanych danych pojazdu.
`message`	Zwracane przez stream endpoint, gdy nie ma więcej danych.

Odpowiedź200 OK

application/json

1{2  "data": [3    {4      "id": "0z2OgJ0B0FUJVEfmXKRZ",5      "year": 2022,6      "vin": "wba5p9c02nfm40627",7      "brand": {8        "id": 16,9        "name": "BMW"10      },11      "model": {12        "id": 93,13        "name": "3er"14      },15      "body_type": {16        "name": "sedan",17        "id": 118      },19      "transmission": {20        "name": "automatic",21        "id": 122      },23      "transmission_steps": 5,24      "fuel": {25        "name": "gasoline",26        "id": 427      },28      "color": {29        "name": "grey",30        "id": 931      },32      "market_origin": {33        "name": "europe",34        "id": 135      },36      "drive_wheels": {37        "name": "all",38        "id": 339      },40      "badge": "330e xDrive Plug-In Hybrid - Leather - Sunroof !!",41      "listings": [42        {43          "external": {44            "id": "EXTERNAL_LISTING_ID",45            "domain": {46              "id": 1000,47              "name": "{domain.com}"48            },49            "url": "https://{domain.com}/vehicle-listing/example"50          },51          "archived": false,52          "title": {53            "en": "2022 BMW 3 Series 330e xDrive Plug-In Hybrid - Leather - Sunroof !!"54          },55          "odometer": 39650,56          "location": {57            "iso": "ca",58            "position": {59              "lon": -113.64258,60              "lat": 60.1086761            }62          },63          "images": [64            {65              "preview": "https://{image-domain.com}/vehicles/example-1-preview.jpg",66              "original": "https://{image-domain.com}/vehicles/example-1.jpg"67            },68            {69              "preview": "https://{image-domain.com}/vehicles/example-2-preview.jpg",70              "original": "https://{image-domain.com}/vehicles/example-2.jpg"71            },72            {73              "preview": "https://{image-domain.com}/vehicles/example-3-preview.jpg",74              "original": "https://{image-domain.com}/vehicles/example-3.jpg"75            },76            {77              "preview": "https://{image-domain.com}/vehicles/example-4-preview.jpg",78              "original": "https://{image-domain.com}/vehicles/example-4.jpg"79            },80            {81              "preview": "https://{image-domain.com}/vehicles/example-5-preview.jpg",82              "original": "https://{image-domain.com}/vehicles/example-5.jpg"83            }84          ],85          "video": null,86          "created_at": "2026-04-12T07:18:25.915404Z",87          "last_seen_at": "2026-04-29T07:59:47.901334Z",88          "updated_at": "2026-04-29T07:59:47.901337Z",89          "price": {90            "price": 30888,91            "currency": {92              "id": 28,93              "name": "cad"94            },95            "negotiable": false,96            "history": null97          },98          "seller_type": {99            "name": "dealer",100            "id": 2101          },102          "is_auction": false,103          "current_bid": null,104          "auction_at": null,105          "availability": null,106          "condition": {107            "name": "used",108            "id": 1109          },110          "keys_available": null,111          "damage": null,112          "second_damage": null,113          "airbag_state": null,114          "document_id": null,115          "description": "Sample 2022 BMW 330e xDrive Plug-In Hybrid listing with leather, sunroof, navigation, reverse camera, heated seats, and driver assistance features."116        }117      ],118      "hash": "60b52121bedf682865247f58ac068d217d2bc7d4dc3db88d2f7856b0dfa6e79e"119    }120  ],121  "scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAx...",122  "next_url": "https://api.auctionsapi.com/cars?scroll_id=DXF1ZX...&api_key=YOUR_API_KEY"123}

Brak dalszych danych w streamie

Odpowiedź200 OK

application/json

1{2  "scroll_id": null,3  "data": [],4  "message": "No more data"5}

Odpowiedź listy marek

Odpowiedź200 OK

application/json

1[2  {3    "id": 9,4    "name": "Audi"5  },6  {7    "id": 13,8    "name": "Bentley"9  },10  {11    "id": 16,12    "name": "BMW"13  },14  {15    "id": 88,16    "name": "Mercedes-Benz"17  },18  {19    "id": 110,20    "name": "Porsche"21  }22]

Odpowiedź listy modeli

Odpowiedź200 OK

application/json

1[2  {3        "id": 1665,4        "name": "X5",5        "generations": [6            {7                "name": "III (F15)",8                "from": 2013,9                "to": 201810            },11            {12                "name": "IV (G05)",13                "from": 2018,14                "to": 202215            },16            ...17        ]18    },19  {20    "id": 102,21    "name": "X6",22    "generations": []23  }24]

Odpowiedzi błędów

error

Gdy wystąpi błąd, API zwraca status błędu z kodem i komunikatem.

Kod	Opis	Rozwiązanie
`400`	scroll_time musi być mniejsze niż 15.	Użyj scroll_time do 15 minut.
`400`	limit musi być mniejszy niż 2000.	Użyj limit do 2000 aut na pakiet.
`403`	dodaj api_key w parametrze GET.	Dodaj api_key jako parametr GET.
`403`	nieprawidłowy api key.	Sprawdź, czy API key jest poprawny.
`403`	twoja subskrypcja API nie jest aktywna.	Aktywuj albo odnów subskrypcję.
`403`	adres IP nie jest w whitelist.	Wyślij request z dozwolonego IP albo zaktualizuj whitelist.
`403`	nie masz żadnych danych w subskrypcji.	Upewnij się, że źródła danych są włączone dla subskrypcji.
`422`	page * perPage przekracza 10000 dla search i API zwraca offset error.	Zmniejsz page albo perPage, aby offset pozostał w granicy 10000.
`500`	Nieoczekiwany błąd serwera.	Ponów request albo skontaktuj się ze wsparciem, jeśli problem się utrzymuje.

Auction APIDokumentacja

Przegląd

Pokrycie

Dostarczanie

Synchronizacja

Kontrola dostępu

Request HTTP

Rozpocznij synchronizację

Kontynuuj synchronizację

Wyszukiwanie po słowie kluczowym

Wyszukiwanie z filtrami

Marki

Modele

Parametry GET

Typy nadwozia

Kolory

Paliwa

Typ sprzedawcy

Pozycja kierownicy

Skrzynia biegów

Poduszki powietrzne

Uszkodzenia

Stany

Dostępność

Emisje

Napęd

Odpowiedź JSON

Odpowiedzi błędów