Авто ДанниПлатформа за автомобилни данни
ENВходЗапочнете безплатно
договор 2026-10-05
Изграждане

Рецепти

Шест цялостни сценария, които покриват повечето от това, за което е API. Всеки е пълна последователност, а не фрагмент.

Първо задайте API=https://api.thecarapi.com и KEY=your_key.

1. Странична лента с филтри с една заявка

Шест измерения, едно отиване и връщане, една единица от квотата:

bash
curl -sS -H "X-API-Key: $KEY" --compressed \
  "$API/api/facets?fields=brands,years,fuels,gearboxes,countries,sites"

След това стеснявайте според избора на потребителя. Фасетите се филтрират взаимно: подайте вече избраните филтри и всяко оставащо измерение се преброява спрямо тях, като всяко измерение пак игнорира собствения си филтър, за да може потребителят да промени решението си.

bash
# След „BMW, под 15 000 евро“: кои горива и години остават?
curl -sS -H "X-API-Key: $KEY" \
  "$API/api/facets?fields=fuels,years&brand=bmw&price_to=15000"

Моделите са за всяка марка и остават на собствен маршрут:

bash
curl -sS -H "X-API-Key: $KEY" "$API/api/models?brand=bmw&ordering=-count&limit=25"

Кеширайте страничната лента. Фасетите се сервират с max-age=600 и ETag; пазете го и изпращайте If-None-Match — обновяването струва празен 304.

2. Търсене, страниране и честни общи бройки

bash
curl -sS -H "X-API-Key: $KEY" --compressed \
  "$API/api/search?brand=bmw&fuel=Diesel&year_from=2018&sort=price_low&limit=50&page=1"
  • Страниране. Изберете един запис и се придържайте към него — page+page_size или offset+limit. Смесването им е 400. Обхождайте до total_pages; total на филтрираното търсене и редовете му вече съвпадат, така че няма да попаднете на къси страници.
  • Преброяването е скъпата половина. Ако обхождате поток, вместо да показвате брой страници, изпращайте include_total=false и го пропуснете изцяло. Ако ви трябва само числото, изпратете count_only=true и няма да получите редове.
  • Пазете site_name + auction_id_str, никога само auction_id — ID на japan надвишават 2^53.
bash
# „Колко дизелови BMW има?“ — едно евтино извикване, без редове.
curl -sS -H "X-API-Key: $KEY" \
  "$API/api/search?brand=bmw&fuel=Diesel&count_only=true" | jq .total

3. Отваряне на една кола: детайли, актуално наддаване, снимки

Една заявка връща спецификацията, състоянието и галерията заедно:

bash
curl -sS -D headers.txt -H "X-API-Key: $KEY" --compressed \
  "$API/api/auction/openlane/11409652" -o car.json

След това разклонете по три неща, в този ред:

text
live_price          има      -> това Е текущото наддаване; покажете го
live_price_pending  има      -> прочетете още веднъж след ~2 с, после спрете
нито едното                  -> цената от цикъла е цената; не опитвайте отново

is_blind: true      -> никога няма да има цена. Покажете estimated_value_eur,
                       отбелязано като оценка на аукционната къща.
details_pending: t  -> vehicle_details още го няма. Прочетете отново според
                       краткия max-age в отговора; междувременно покажете останалото.
vault_gallery.pending > 0 -> идват още снимки. Проверявайте на max-age=10.

Адресите на снимките са пътища, затова ги свържете с базата:

bash
jq -r '.auction.vault_gallery.images[] | .served_url // .remote_url' car.json \
  | sed "s|^/|$API/|"

Не ви трябва и /api/auction-images — vault_gallery е същото тяло, вградено. Използвайте отделния маршрут само когато искате само галерията.

4. Изберете отстъпките, после изчислете вноса

С правото за полета market_reference топ офертите съдържат референцията, използвана за оценката им:

bash
curl -sS -H "X-API-Key: $KEY" \
  "$API/api/top-offers?site=openlane&min_savings_pct=20&sort=savings&limit=10"

Вземете една и изчислете крайната ѝ цена. Прочетете is_margin от отговора с детайли и изпратете източника, така че моделът на таксите да съвпада с този, който е оценил обявата:

bash
curl -sS -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"price":9000,"site_name":"openlane","origin":"DE","destination":"BG","is_margin":false}' \
  "$API/api/calculator/calculate" | jq .breakdown.estimated_total

Сравнете тази крайна сума с пазара на дребно, а не с цената на лота:

bash
curl -sS -H "X-API-Key: $KEY" \
  "$API/api/cars-bg-market?brand=BMW&model=320d&year=2019&flex=1" \
  | jq '{n: .snapshot.listing_count, median: .snapshot.median_price_eur}'

Проверете listing_count, преди да се доверите на медианата. Пазарните снимки не са включени по подразбиране за нов ключ — поискайте ги.

5. Проследяване на една кола във времето

Движението на цената на лот, който наблюдавате:

bash
curl -sS -H "X-API-Key: $KEY" \
  "$API/api/auction/openlane/11409652/price-history" \
  | jq '.history[] | {observed_at, current_price, changed_fields}'

И животът ѝ преди тази обява, по VIN — това показва кола, минала през търг повече от веднъж:

bash
curl -sS -H "X-API-Key: $KEY" \
  "$API/api/vin/WBA8E9G50GNU12345/history" \
  | jq '.auctions[] | {site_name, last_seen_at, mileage, public_price_eur, archived}'

Историята по VIN не е включена по подразбиране за нов ключ — поискайте я. event_type в историята на цените е initial, baseline или change — няма стойност price_change.

6. Евтино огледално копие на целия поток

За да поддържате синхронизирано локално копие, а не за да отговорите на заявка:

bash
# Без филтри = без ограничение на дълбочината. Обходете с максималния размер на страницата.
curl -sS -H "X-API-Key: $KEY" -H "Accept-Encoding: gzip" --compressed \
  "$API/api/search?limit=100&offset=0&include_total=false"

Четири неща го правят с порядък по-евтино:

  1. 1--compressed — около една осма от байтовете.
  2. 2include_total=false — преброяването е скъпата половина на търсенето.
  3. 3Пазете ETag на всяка страница и изпращайте If-None-Match при повторното обхождане; непроменените страници отговарят с 304 без тяло.
  4. 4Не разширявайте всяка карта. Зареждайте детайли само за редове, чийто last_changed_at се е променил или които реално показвате.

Резултатите от търсенето винаги са с цени от цикъла, никога с актуални цени. Това ги прави достатъчно бързи за страниране — вижте какво остава с цени от цикъла.