Довідник API
GET /v1/listings/search
Normalized search across listing sources
Normalized search across listing sources
Search by natural language (q) and/or structured filters. Combines the platform listings cache with a live fan-out to healthy sources (per-source timeout; a failing or blocked source is reported in errors[] and never fails the request). Results are deduplicated across sources and ranked. Requires scope read:listings.
- Автентифікація: заголовок
Authorization: Bearer rv_live_...(API-ключі та scopes) - Потрібний scope:
read:listings
Опис операції, параметрів і полів походить зі специфікації OpenAPI (
openapi.json) і подається англійською, як у самому API.Параметри
| Поле | Де | Тип | Обов’язк. | Опис |
|---|---|---|---|---|
q | query | string | ні | Natural-language query, e.g. "BMW X5 2019-2021 up to 35 000 EUR, diesel, under 150k km". Structured params below override what is parsed from q. |
make | query | string | ні | |
model | query | string | ні | |
year_from | query | integer | ні | |
year_to | query | integer | ні | |
price_min_eur | query | number | null | ні | |
price_max_eur | query | number | null | ні | |
mileage_max_km | query | number | null | ні | |
fuel | query | string | ні | Comma-separated: petrol,diesel,hybrid,phev,ev,lpg,cng,hydrogen,other. |
country | query | string | ні | Comma-separated ISO-3166 alpha-2 codes of the car location, e.g. DE,PL. |
market | query | string | ні | Comma-separated: us,eu,cn,kr,ua,ge. |
sources | query | string | ні | Comma-separated source keys to restrict the search to (e.g. mobile_de,otomoto). |
no_accidents | query | "true" | "false" | ні | Exclude salvage/rebuilt/flood titles. |
limit | query | integer | ні | |
live | query | "true" | "false" | ні | true: also query healthy live sources (slower, bounded by a timeout). false: only the platform cache. |
Відповіді
200
Normalized listings.
application/json · Схема: SearchListingsResponse
| Поле | Тип | Обов’язк. | Опис |
|---|---|---|---|
query | object | так | The structured query that was actually executed. |
query.text | string | ні | |
query.make | string | ні | |
query.model | string | ні | |
query.yearFrom | integer | ні | |
query.yearTo | integer | ні | |
query.priceMin | object | ні | |
query.priceMax | object | ні | |
query.mileageMaxKm | number | ні | |
query.fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other"[] | ні | |
query.gearbox | "manual" | "automatic" | "cvt" | "robot" | "other"[] | ні | |
query.body | "sedan" | "hatchback" | "wagon" | "suv" | "crossover" | "coupe" | "convertible" | "minivan" | "van" | "pickup" | "truck" | "motorcycle" | "other"[] | ні | |
query.drive | "fwd" | "rwd" | "awd" | "4wd"[] | ні | |
query.markets | "us" | "eu" | "cn" | "kr" | "ua" | "ge"[] | ні | |
query.countries | string[] | ні | |
query.noAccidents | boolean | ні | |
query.sourceKeys | string[] | ні | |
query.limit | integer | ні | |
query.page | integer | ні | |
query_parser | "structured" | "rules" | "llm" | так | How q was interpreted: structured (no q), rules (rule-based) or llm. |
results | object[] | так | |
results[].sourceKey | string | ні | |
results[].externalId | string | ні | |
results[].url | string (uri) | ні | |
results[].title | string | ні | |
results[].make | string | null | ні | |
results[].model | string | null | ні | |
results[].trim | string | null | ні | |
results[].year | integer | null | ні | |
results[].vin | string | null | ні | |
results[].price | object | ні | |
results[].priceEur | number | null | ні | |
results[].priceType | "fixed" | "current_bid" | "buy_now" | "estimate" | "unknown" | ні | |
results[].mileageKm | number | null | ні | |
results[].fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other" | null | ні | |
results[].gearbox | "manual" | "automatic" | "cvt" | "robot" | "other" | null | ні | |
results[].drive | "fwd" | "rwd" | "awd" | "4wd" | null | ні | |
results[].body | "sedan" | "hatchback" | "wagon" | "suv" | "crossover" | "coupe" | "convertible" | "minivan" | "van" | "pickup" | "truck" | "motorcycle" | "other" | null | ні | |
results[].engineCc | number | null | ні | |
results[].powerKw | number | null | ні | |
results[].batteryKwh | number | null | ні | |
results[].color | string | null | ні | |
results[].damage | object | ні | |
results[].titleStatus | "clean" | "salvage" | "rebuilt" | "flood" | "junk" | "parts_only" | "certificate" | "unknown" | null | ні | |
results[].location | object | ні | |
results[].market | "us" | "eu" | "cn" | "kr" | "ua" | "ge" | ні | |
results[].seller | object | ні | |
results[].photos | string (uri)[] | ні | |
results[].auction | object | ні | |
results[].listedAt | string | null (date-time) | ні | |
results[].fetchedAt | string (date-time) | ні | |
results[].completeness | number | ні | |
results[].details | object | ні | |
results[].sources | object[] | ні | All sources where this car was found (deduplicated by VIN / photo / fuzzy match). |
results[].score | number | ні | Rank score 0..1 (data completeness, freshness, multi-source confirmation). |
total | integer | так | Number of deduplicated results before the limit was applied. |
sources | object | так | |
sources.cache | object | так | |
sources.live | object | так | |
errors | object[] | так | Per-source problems. A failing source never fails the whole search. |
errors[].source_key | string | ні | |
errors[].code | "timeout" | "blocked" | "failed" | "unhealthy" | "aborted" | ні | |
errors[].message | string | ні | |
errors[].blocked_reason | string | ні | |
took_ms | integer | так |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Схема: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Схема: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Схема: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Схема: Problem
502
FX provider unavailable.
application/problem+json · Схема: Problem
Приклад
curl -s "https://api.importos.app/v1/listings/search?q=BMW%20X5%202019-2021%20%D0%B4%D0%BE%2035000%20EUR%20%D0%B4%D0%B8%D0%B7%D0%B5%D0%BB%D1%8C&limit=5" \
-H "Authorization: Bearer $IMPORTOS_API_KEY"