Първи стъпки

REST API върху нормализиран автомобилен инвентар от дванадесет източника — Auto1, OpenLane, Copart Germany, BCA, Autorola, Dealercars, Schadeautos, Encar, KB ChaChaCha, Korea Auctions, японските аукционни къщи и Guazi — плюс европейска мрежа от обяви на дребно от 681 портала в 39 държави. Отговорите с данни са JSON, четенето е с GET, а единствената задължителна идентификация е API ключ в заглавка.

Този справочник покрива стабилната интеграционна повърхност за клиенти и нищо друго. Помощните функции само за сайта и вътрешните операции по публикуване съществуват, но не са публични, нямат версии за вас и не са документирани тук.

Мисловният модел

Автомобилът се адресира с двойката site_name + auction_id_str — например encar/38112900. Двойката е стабилна през целия живот на обявата и е единственият идентификатор, който трябва да пазите. Всичко друго в API е или начин да намерите тази двойка (търсене, фасети, каталог, топ оферти), или начин да я разширите (детайли, снимки, история на цените, история по VIN).

1. 1Откриване. /api/search с филтри или /api/facets за попълване на самите контроли за филтриране. Получавате карти с резултати, съдържащи site_name и auction_id_str.
2. 2Разширяване. /api/auction/{site}/{id} връща пълния запис за една карта — спецификация, състояние, нормализирания блок vehicle_details и галерията, вградена като vault_gallery.
3. 3Обогатяване. Историята на цените, историята по VIN, пазарните референтни цени и калкулаторът за крайна цена приемат същата двойка или стойности от отговора с детайли.

Базов URL

https://api.thecarapi.com

Изисква се HTTPS; обикновен HTTP се отказва, а не се пренасочва. Изпращайте JSON тела на заявки с Content-Type: application/json. Няма префикс за версия в адреса — договорът за схемата се носи в полето contract_version на повечето отговори (вижте Отговори и страниране за малкото, които го пропускат) и е описан изцяло в /api/contract.

Първата ви заявка

curl -sS \
  -H "X-API-Key: $API_KEY" \
  -H "Accept-Encoding: gzip" \
  --compressed \
  "https://api.thecarapi.com/api/search?brand=bmw&fuel=Diesel&year_from=2018&sort=price_low&limit=24"

Успешният отговор съдържа success: true, данните под ключ, специфичен за маршрута, и полетата за корелация, описани в Отговори и страниране. Пазете request_id — това е единственото, което позволява на поддръжката да проследи конкретно извикване.

Анатомия на заявката

Отговорите може да съдържат и заглавки X-Perf-* и X-Local-Source. Те са диагностични, не са част от този договор и може да се променят или да изчезнат без предупреждение — не разклонявайте логиката си по тях.

Какво не е този API

• Не е интерфейс за наддаване. Той наблюдава цените в търговете; никога не поставя, не увеличава и не оттегля наддаване и не дава права за покупка в никоя платформа източник.
• Не е оферта за такси. Таксите на търговете, транспортът и доставката са изчислени за нашия акаунт на купувач и нашия адрес, затова се премахват на границата на отговора. Използвайте калкулатора за внос за крайна цена по вашия маршрут.
• Файловете с протоколи се сервират през API. Нормализираните адреси на документи и протоколи използват пътища /report-vault. Файловете се извличат и кешират; неподдържани хостове или страници, които не са файлове, може да пренасочват към източника.

Прочетете тези, преди да показвате каквото и да е

Три страници отговарят на въпросите, които причиняват най-много преработка, и трите са за това какво означават данните, а не как да ги заявите.